.. _Homepage:
====================================
MPRAsnakeflow's Documentation
====================================
.. image:: https://img.shields.io/badge/GitHub-repository-brightgreen?logo=github
:alt: GitHub Repository
:target: https://github.com/kircherlab/MPRAsnakeflow
.. image:: https://img.shields.io/github/v/release/kircherlab/MPRAsnakeflow
:alt: Latest Release
:target: https://github.com/kircherlab/MPRAsnakeflow/releases/latest
.. image:: https://zenodo.org/badge/347005871.svg
:alt: DOI
:target: https://doi.org/10.5281/zenodo.18163777
.. image:: https://img.shields.io/github/license/kircherlab/MPRAsnakeflow
:alt: License
:target: https://github.com/kircherlab/MPRAsnakeflow/blob/master/LICENSE
.. image:: https://img.shields.io/badge/snakemake-≥8.24.1-brightgreen.svg
:alt: Snakemake
:target: https://snakemake.github.io/
.. image:: https://img.shields.io/badge/conda->24.7.1-brightgreen.svg
:alt: Conda
:target: https://github.com/conda-forge/miniforge
.. image:: https://github.com/kircherlab/MPRAsnakeflow/actions/workflows/main.yml/badge.svg
:alt: Tests
:target: https://github.com/kircherlab/MPRAsnakeflow/actions/workflows/main.yml
.. image:: https://img.shields.io/github/issues/kircherlab/MPRAsnakeflow
:alt: GitHub Issues
:target: https://github.com/kircherlab/MPRAsnakeflow/issues
.. image:: https://img.shields.io/github/issues-pr/kircherlab/MPRAsnakeflow
:alt: GitHub Pull Requests
:target: https://github.com/kircherlab/MPRAsnakeflow/pulls
**Welcome!**
MPRAsnakeflow is a pipeline designed to process sequencing data from Massively Parallel Reporter Assays (MPRAs) to create count tables for candidate sequences tested in the experiment.
MPRAsnakeflow is built on top of `Snakemake `_ (version ≥8.24.1 required) and is configured via a ``.yaml`` file.
Authors
-------
- Max Schubach (`@visze `_) | `Computational Genome Biology Group `_ | Berlin Institute of Health at Charité - Universitätsklinikum Berlin
Citation
---------
If you use MPRAsnakeflow in your work, please cite our recent preprint:
.. epigraph::
**Uniform processing and analysis of IGVF massively parallel reporter assay data with MPRAsnakeflow**
Jonathan D. Rosen, Arjun Devadas Vasanthakumari, Kilian Salomon, Nikola de Lange, Pyaree Mohan Dash, Pia Keukeleire, Ali Hassan, Alejandro Barrera, Martin Kircher, Michael I. Love, Max Schubach
*bioRxiv* (2025). `2025.09.25.678548 `_
Usage
-----
If you use this workflow in a paper, don't forget to give credit to the authors by citing the URL of the (original) repository.
Installation & Getting Started
------------------------------
Instructions for installing the program and examples to help you get started.
MPRAsnakeflow Workflows
-----------------------
An overview of how MPRAsnakeflow works and documentation for the MPRAsnakeflow sub-workflows.
MPRAsnakeflow Tutorials
-----------------------
Get to know MPRAsnakeflow by running it via Jupyter notebooks or Google Colab on small examples.
MPRAsnakeflow Examples
----------------------
Multiple examples from the literature are listed for every sub-workflow in MPRAsnakeflow.
Tips & Tricks
-------------
Find our FAQ here.
Project Information
-------------------
More information on the project, including the changelog, list of contributing authors, and contribution instructions.
-------------
Quick Example
-------------
To run MPRAsnakeflow, first activate the Snakemake environment with the following command:
.. code-block:: bash
conda activate snakemake
Then run the main workflow with:
.. code-block:: bash
snakemake --software-deployment-method conda --cores $N --configfile config/example_config.yaml
--------
Features
--------
.. list-table::
:widths: 25 80
:header-rows: 1
* - Option
- Description
* - ``--software-deployment-method``
- When ``conda`` is set, the utility uses conda to efficiently query repositories and manage package dependencies. MPRAsnakeflow can also use containers via Apptainer by using ``--software-deployment-method apptainer conda``. This will use a container to run all rules but will activate the pre-installed conda environments inside it. Recommended option: ``--software-deployment-method apptainer conda``.
* - ``--cores``
- This utility sets the number of cores (``$N``) to be used by MPRAsnakeflow.
* - ``--configfile``
- This file (e.g., ``config/example_config.yaml``) contains the project configuration, including objects and properties that **must** be set before running MPRAsnakeflow.
-------------------
Investigate Results
-------------------
The best option to investigate your results is to review the QC report.
(In development) After successful execution, you can create a self-contained interactive HTML report with all results via:
.. code-block:: bash
snakemake --report report.html --configfile config/example_config.yaml
This report can be shared with collaborators. An example of a generated report (using some trivial test data) can be seen `here `_.
--------
Feedback
--------
Feel free to leave feedback, ask questions, or report bugs on our issues page: `MPRAsnakeflow Issues `_.
Indices and Tables
==================
* :ref:`genindex`
* :ref:`search`
.. toctree::
:caption: Installation & Getting Started
:name: getting-started
:maxdepth: 1
:hidden:
1_getting_started/quickstart
1_getting_started/install
1_getting_started/config
1_getting_started/cluster
.. toctree::
:caption: MPRAsnakeflow Workflows
:name: mprasnakeflow-workflows
:maxdepth: 1
:hidden:
2_workflows/overview
2_workflows/assignment
2_workflows/experiment
.. toctree::
:caption: MPRAsnakeflow Tutorials
:name: mprasnakeflow-tutorials
:maxdepth: 1
:hidden:
3_tutorial/tutorial
.. toctree::
:caption: MPRAsnakeflow Examples
:name: mprasnakeflow-examples
:maxdepth: 2
:hidden:
4_examples/assignment_example1
4_examples/count_example1
4_examples/combined_example1
4_examples/plasmid_example
.. toctree::
:caption: Tips & Tricks
:name: tips-tricks
:maxdepth: 1
:hidden:
5_tips/faq
.. toctree::
:caption: Project Info
:name: project-info
:maxdepth: 1
:hidden:
6_info/contributing
6_info/authors
6_info/history
6_info/license
6_info/todo_list