A pipeline to analyze functional screening data from shRNA, CRISPR/Cas9 and CRISPR/dCas9 experiments.

PitViper is a versatile and user-friendly pipeline designed to process, interpret, and visualize functional screening data obtained from various experimental methods such as shRNA, CRISPR/Cas9, and CRISPR/dCas9. This repository hosts the codebase for PitViper, providing researchers with a powerful tool for extracting meaningful insights from their screening experiments.

It stands for "Processing, InTerpretation, and VIsualization of PoolEd screening Results." It is a comprehensive pipeline that streamlines the analysis workflow for functional screening data. The pipeline is built using a combination of powerful tools, including Snakemake for workflow management, Flask for a lightweight web framework, and Jupyter for interactive computational documents.

• Modularity: PitViper supports a wide range of functional screening data, including shRNA, CRISPR/Cas9, and CRISPR/dCas9 experiments.

• Reproducibility: Built using Snakemake, PitViper ensures reproducibility and scalability in data analysis.

• User Interface: PitViper offers a user-friendly web-based interface powered by Flask, making it accessible to both beginners and experienced researchers.

• Flexibility: Whether you have raw FASTQ or BAM files, or a pre-processed count matrix, PitViper adapts to your data input preference.

• Visualization: Interactive Jupyter Notebook reports facilitate results visualization and interpretation.

• Prerequisites

• Installation

  • Using the Automated Script

  • Run PitViper from Docker container

• Inputs

  • Starting from raw FASTQ or BAM files

  • Starting from count matrix

• PitViper CLI

Before using this script, ensure you have the following prerequisites:

• Conda: Install Conda to manage the application's environment and dependencies. You can download Conda from the official Conda website.

• Git: If the application's dependencies include external repositories, Git is required for cloning those repositories. You can download Git from the official Git website.

PitViper can be effortlessly installed using the provided run.sh script. This script sets up the Conda environment, installs all necessary dependencies, and launches the PitViper GUI. Dependencies are only installed during the first run.

# Clone the PitViper repository and navigate to its root directory
$ git clone https://github.com/PaulArthurM/PitViper.git
$ cd PitViper

# Run the installation script
$ ./run.sh

Available options:

--mode: Specify the mode for creating the Conda environment (yaml or lock).
--installer: Specify the Conda package manager to use (conda or mamba).
--noflask: Optionally skip running the Flask application.

Once installation is complete, the PitViper GUI will automatically open in your default web browser, allowing you to start analyzing your functional screening data seamlessly.

PitViper main directory contains a Dockerfile that allows easy building of PitViper image. From this folder simply run:

$ docker build -t [image_name] .

PitViper docker image can also be downloaded from dockerhub using:

$ docker pull lobrylab/pitviper:v1.0

To start a PitViper container simply run:

$ docker run -p 5000:5000 -p 8888:8888 -v [fastq/bam_files_path]: [fastq/bam_files_path] -n [name_the_container] [PitViper_image_name]

For example:

$ docker run -p 5000:5000 -p 8888:8888 -v /home/data/:/home/data/ -n pitviper lobrylab/pitviper:v1.0

PitViper GUI can now be accessed in your web browser at the address: localhost:5000.

Upon completion of PitViper analysis, the jupyter notebook will be accessible following the localhost:8888/[token] link displayed in the terminal.

To quit PitViper and stop the container simply quit the jupyter notebook session.

To start a new analysis, just restart the container using the following command :

$ docker start -a [container_name]

To access the notebook of a previously ran PitViper analysis, first start the container :

$ docker start [container_name]

Then execute the notebook script:

$ docker exec -ti [container_name] bash /PitViper/notebook.sh

The folder containing all previously ran analysis will be accessible in jupyter notebook following the localhost:8888/[token] link displayed in the terminal.

PitViper accommodates diverse input data formats, allowing you to initiate an analysis using raw data files, aligned BAM files, or a count matrix. The specific input requirements vary based on your starting data type.

For this approach, you will need the following:

1. Path to FATSQ files on your system.
2. A library file comprising three comma-separated columns without headers: guide ID, guide sequence, target element.
3. A design matrix summarizing your experimental conditions, their replicates, and associated FASTQ files.

Suppose you have two conditions, A (control) and B (treatment), each with three replicates. Your design matrix should be structured as follows:

In the order column, the control condition (A) is designated by order = 0, and any condition with an order value greater than 0 (e.g., 1 for B) is treated as a treatment condition. The order should remain consistent across replicates.

The library file should be comma-separated with three columns: guide's ID, guide's sequence, and the corresponding target element.

guide_A.1,CTTAGTTTTGAACAAGTACA,element_A
guide_A.2,GTTGAGTTATCACACATCAT,element_A
guide_A.3,AATGTAGTGTAGCTACAGTG,element_A
guide_B.1,TTAGTTTATATCTTATGGCA,element_B
guide_B.2,GATTGTCTGTGAAATTTCTG,element_B

If you have aligned BAM files instead of raw FASTQ files, follow these modifications to the design matrix:

• Replace the fastq column with a bam column, and replace the paths to FASTQ files with paths to BAM files.

Starting from a count matrix eliminates the need for a fastq or bam column:

However, the replicate column must contain the same labels as those in the count matrix header:

PitViper CLI is a command-line tool for running the PitViper pipeline.

$ pitviper.py --configfile <configfile> [--dry_run] [--jobs <jobs>] [--notebook <notebook>]

--configfile: Path to the configuration file. The configuration file must be in YAML format.
--dry_run: If enabled, the pipeline will be run in dry run mode, which means that no commands will be executed. This is useful for testing the pipeline without actually running it.
--jobs: Number of Snakemake rules to run in parallel. The default is 1.
--notebook: Output file(s) of a PitViper rule with "notebook" entry.

$ pitviper.py --configfile config.yaml

# Run the pipeline in dry run mode
$ pitviper.py --configfile config.yaml --dry_run

# Run the pipeline with 4 jobs in parallel
$ pitviper.py --configfile config.yaml --jobs 4

# Run the pipeline and save the output notebook to notebook.html
$ pitviper.py --configfile config.yaml --notebook notebook.html