quickstart.rst

.. _Getting started:


=====================
Getting started
=====================

1. Create an :code:`experiment.csv` in the format below, including the header. 
   `DNA_F` or `RNA_F` is name of the gzipped fastq of the forward read of the DNA or RNA from the defined condition and replicate. 
   `DNA_UMI` or `RNA_UMI` is the corresponding index read with UMIs (excluding sample barcodes), and 
   `DNA_R` or `RNA_R` of the reverse read.
   
   Multiple fastq files can be used for each column by seperating them with :code:`;`.

   Right now an UMI have to be used. If you want to use MPRAsnakeflow without an UMI please sitch to MPRAflow or contact us.

   Here is an example of an :code:`experiment.csv` file and it can be downloaded :download:`experiment.csv <../resources/sample/experiment.csv>`:

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

2. If you would like each insert to be colored based on different user-specified categories, such as `positive control`, `negative control`, `shuffled control`, and `putative enhancer`. To assess the overall quality, you can create a ``label.tsv`` in the format below that maps the name to category as shown here:

  .. code-block:: text

     insert1_name label1
     insert2_name label1
     insert3_name label2

  The insert `names` must exactly match the `names` in the design FASTA file.

3. Set up the config file

The config file is the heart of MPRAsnakflow. Here different runs can be configured. We recommend to use one config file per MPRA experiment or MPRA roject. But in theory many different experiments can be configured in only one file. It is divided into :code:`global` (generell settings), :code:`assignments` (assigment workflow), and :code:`experiments` (count workflow including variants).

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

.. include:: ../resources/sample/config.yml
   :code: yaml

4. Run MPRAsnakeflow

  .. code-block:: bash

     conda activate snakemake
     snakemake --configfile config/config.yaml --use-conda -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.

  Be sure that the files, :code:`experiment.csv` and the :code:`config.yaml` are correct. All fastq files for the count/experiment part must be in the same folder given by the :code:`data_folder` option. Please specify your barcode length and umi-length with :code:`bc_length` and :code:`umi_length`.

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