.. _Getting started:

=====================
Getting Started
=====================

We highly recommend starting with the MPRAsnakeflow :ref:`Tutorial` or the :ref:`Assignment example` and :ref:`Count example` examples. Below, we provide a quick overview of what you need to start the workflow.

MPRAsnakeflow consists of two subworkflows: :ref:`Assignment` and :ref:`Experiment`. This quickstart shows the configuration for both. If you only want to run one of them, leave out the respective part.

1. **Experiment Workflow Only:** Create an :code:`experiment.csv` file in the format below, including the header. 
   - `DNA_BC_F` or `RNA_BC_F`: The name of the gzipped FASTQ file of the forward read of the DNA or RNA from the defined condition and replicate.
   - `DNA_UMI` or `RNA_UMI`: The corresponding index read with UMIs (excluding sample barcodes).
   - `DNA_BC_R` or `RNA_BC_R`: The reverse read.

   Multiple FASTQ files can be used for each column by separating them with :code:`;`.

   **Note:** Currently, a UMI is required. If you want to use MPRAsnakeflow without a UMI, please switch to MPRAflow or contact us.

   Here is an example of an :code:`experiment.csv` file, which can be downloaded here: :download:`experiment.csv <../../resources/example_experiment.csv>`.

   .. csv-table:: experiment.csv
      :file: ../../resources/example_experiment.csv
      :widths: 5, 2, 25, 25, 25, 25, 25, 25
      :header-rows: 1

2. **Experiment Workflow Only:** If you would like each designed sequence to be colored based on different user-specified categories (e.g., `positive control`, `negative control`, `shuffled control`, `putative enhancer`), you can create a :code:`label.tsv` file in the format below. This file maps the name to the category to assess the overall quality:

   .. code-block:: text

      oligo_name_1 label1
      oligo_name_2 label1
      oligo_name_3 label2

   The `oligo_name_X` must exactly match the `header` in the design FASTA file.

3. **Set Up the Config File:**

   The config file is the heart of MPRAsnakeflow. Here, different runs can be configured. We recommend using one config file per MPRA experiment or MPRA project. However, in theory, many different experiments can be configured in a single file. The config file is divided into:
   - :code:`version`: Specifies the MPRAsnakeflow version used.
   - :code:`assignments`: Configures the assignment workflow.
   - :code:`experiments`: Configures the count workflow.

   See :ref:`Config` for more details about the config file. Below is an example of running only the count experiments and using a provided assignment file:

   .. include:: ../../config/example_config.yaml
      :code: yaml

4. **Run MPRAsnakeflow:**

   Use the following command to run the workflow:

   .. code-block:: bash

      conda activate snakemake
      snakemake --software-deployment-method conda --configfile config/example_config.yaml -p --cores 4

   .. note:: This will run in local mode using 4 cores. Please submit this command to your cluster's queue if you would like to run a highly parallelized version.

   Ensure that the files :code:`experiment.csv` and :code:`example_config.yaml` are correct. All FASTQ files for the count/experiment part must be in the same folder specified by the :code:`data_folder` option. Please specify your barcode length and UMI length (if available) with :code:`bc_length` and :code:`umi_length`.

   - The assignment files generated by the workflow are named :code:`assignment_barcodes.<config>.tsv.gz` and can be found in the :code:`results/assignment/<assignment>/` folder.
   - The count files generated by the experiment workflow are named :code:`<condition>_<replicate>_merged_assigned_counts.tsv.gz` and can be found in the :code:`results/experiments/<project>/assigned_counts/<assignment>/<config>/` folder.