CRISPRtOE Analysis Pipeline

Overview

This repository provides analysis pipelines for CRISPRtOE (CRISPR transposon-mediated OverExpression) experiments using a Tn-seq approach to analyze insertions. The project consists of two main pipelines:

1. Guides Pipeline: Processes guide RNA design files for use in the results pipeline
2. Results Pipeline: Processes raw sequencing data to identify and quantify transposon insertions

Pipeline Components

Guides Pipeline

The guides pipeline takes in a guide RNA design file and processes it for use in the CRISPRtOE results pipeline. This pipeline:

• Annotates and formats guide RNA designs to include information about genes located downstream of target Tn insertions.
• Creates a list of transposon insertions consistent with the guide design.
• Creates unique Tn insertion ID's using chromosome, coordinates, and orientation values.

Results Pipeline

The CRISPRtOE results pipeline processes raw sequencing data for Read 1 only through several steps:

• Read trimming (cutadapt)
• Read alignment (single-end; bowtie)
• Conversion of alignment files (SAM/BAM) to TSV
• Calculation of transposon insertion coordinates
• Addition of unique transposon site identifiers
• Verification of transposon sites against the designed library
• Creation of separate files for:
  • Insertions in the library ({prefix}_library.tsv)
  • Flipped orientation equivalents of library insertions ({prefix}_wrong_orientation.tsv)
  • Insertions not accounted for by the library design ({prefix}_offtarget.tsv)
• Aggregation of counts across all samples
• Generation of summary statistics

Data Analysis Approach

In this pipeline, unique transposon insertions are the fundamental unit of measurement and aggregation. Each insertion is annotated with information about the downstream gene, allowing:

• Insertion-level data to be aggregated to gene-level data
• Downstream analyses such as differential abundance using edgeR

Requirements, Setup, and Usage

Computational Resources

Analysis can be run using an interactive node on Scarcity with 16GB RAM and 4 cores. The results pipeline for E. coli and Z. mobilis datasets can take approximately 12-24 hours to run. It is possible that the analysis could be submitted as a job, but this has not been tested.

Repository Cloning

This repository is available through the WEI gitpub. You will need to use your GLBRC user credentials to access the repository.

Clone this repository into your directory of choice, and then navigate into the main repo directory with the following:

git clone https://gitpub.wei.wisc.edu/aroarty/ctoe_analysis.git
cd ctoe_analysis

Environment

This pipeline can be run using the 'bioinfo' conda environment on Scarcity, located at /home/glbrc.org/aroarty/.conda/envs/bioinfo. You can also install the required packages locally using the environment.yml file in the main project directory.

To load the existing conda environment on Scarcity:

conda activate /home/glbrc.org/aroarty/.conda/envs/bioinfo

To build a conda environment using the environment.yml file:

conda env create --name bioinfo --file=environment.yml
conda activate bioinfo

Custom Package Installation

This pipeline requires the installation of two custom packages in the conda environment. If you build your own conda environment, after acivating the conda environment, run the following commands from the main project directory:

pip install -e lib/tn_feature_annotator/
pip install -e lib/tn_downstream_annotator/

Input Data: Guides Pipeline

The guide design file should contain at minimum the following columns: 'chr', 'tar_start', 'tar_end', 'sp_dir'

These columns are based on the sgRNA design pipeline from this github repository: https://github.com/ryandward/crispr_experiment/tree/main

• chr: Chromosome.
• tar_start and tar_end: Start and end positions of the protospacer in the genome.
• sp_dir: Orientation of the spacer/protospacer in the genome.

Input Data: Results Pipeline

Only the R1 read from the standard CRISPRtOE sequencing approach is required. All sequencing lanes for a given sample should be combined into a single fastq file prior to analysis.

All fastq files of interest should be placed in fastq_files directory, or the directory name for the fastq files should be specified when running the pipeline.

Setup of User Directories

The pipeline has a set of expected files and directories, whose locations and names can be customized. However, the a generic approximation of the default setup is as follows:

• Experiment directory (Example: experiment_dir): User directory to work from. Path and name will be specified in commands and in config file.
• experiment_dir/fastq_files: Default directory for fastq files.
• guides.tsv: User's sgRNA design file - name and path will be specified when running pipeline. Typically will be placed in experiment_dir.

Configuration

Variables affecting the guides and results pipelines can be configured with experiment_config.yaml.

Prior to running the pipeline, a configuration file for the experiment needs to be placed in experiment_dir. A template of this file can be found in config/ and can be copied to the user's experimental directory as follows:

cp config/experiment_config.yaml experiment_dir

Parameters include:

• Experiment information
  • experiment_name (name of experiment folder)
  • experiment_directory
  • organism (for selecting genome for alignment: Currently ecoli and zmobilis are supported)
• Annotation Parameters:
  • Which downstream genes to annotate?
    • --next-downstream-5prime: Restrict downstream gene annotation to the next gene downstream whose 5' end is proximal to the Tn insertion.
    • --next-downstream-any
• Results Pipeline Parameters
  • fastq_suffix: Shared suffix of fastq files
• Guides Pipeline Parameters
  • expected_distance: Expected distance between protospacer and Tn insertions
  • acceptable_range: Number of base pairs upstream and downstream of expected_distance to consider a Tn insertion that is consistent with the library design.

Pipeline Usage

python main_pipeline.py --pipeline {guides,results} 
                 --experiment-dir EXPERIMENT_DIR 
                 [--guides-file GUIDES_FILE]

Run python main_pipeline.py -h to view other parameters and their defaults.

The pipeline must be run from the ctoe_analysis directory that contains main_pipeline.py to work.

Required Arguments

• --pipeline: Specify which pipeline to run (guides or results)
• --experiment-dir: Directory containing experiment files
• --guides-file: Path to guide design file (required for guides pipeline only)

Output Files

Guides Pipeline

• A fully annotated version of the guide design file with predicted transposon insertion sites and downstream genes
• A file containing all possible transposon insertion sites that are part of the experimental design

Results Pipeline

This pipeline will create a directory called results in your experiment directory. Within results will be a directory for each sample that was processed.

The final output files for each sample will include:

• Library transposon sites ({prefix}_library.tsv)
• Wrong orientation transposon sites ({prefix}_wrong_orientation.tsv)
• Off-target transposon sites ({prefix}_offtarget.tsv)

Log files are created for each sample, which contain information about read trimming, alignment, and relevant information that may be useful in troubleshooting.

Within the results directory will be aggregated files with information corresponding to all samples analyzed. These will be named based on the experiment directory:

• Aggregated counts file for all samples
• Summary statistics file

Rerunning and/or Restarting Results Pipeline

The results pipeline is set up to, at each step, check if the corresponding output file is present before proceeding. This allows the pipeline to restart where it left off if it is interrupted or if it runs into an error.

This includes the final aggregated files. Therefore, if you want to add more samples to your fastq directory and run the pipeline on these additional files, you should delete the final aggregated files before starting the pipeline, as they will not be updated.

Downstream Analysis

Most downstream analyses using these datasets have been performed in R. Relevant downstream analyses for the CRISPRtOE preprint can be found in this repository: https://gitpub.wei.wisc.edu/aroarty/ctoe_downstream_analysis.git

The output files from this repository's pipelines that are required for the downstream analyses are:

• {organism}_tn_sites_in_lib.tsv
• {experiment_dir}_all_counts.tsv

An additional file outlining the experimental design will be required for downstream analyses.

The scripts for downstream analysis are provided to document how the CRISPRtOE analysis was performed for the preprint, and to provide an example of how the analysis could be done for future projects. It is not a pipeline.

Adaptation for CRISPRt

The default guide pipeline will output information for both the genomic feature present at the site of Tn insertion, and the downstream feature. For CRISPRt, the genomic feature at the site of Tn insertion is what is of interest.

The results pipeline will work for CRISPRt reads as well as CRISPRtOE reads.

Downstream analyses in R can then associate the features at the site of Tn insertion, rather than the downstream features, with each unique Insertion_ID.

Known limitation

Predicted Tn Insertion Sites Bordering Genomic Features

The guides pipeline uses a GenBank file to annotate genomic features at the site of Tn insertion and downstream of Tn insertion. The script that expands the list of predicted Tn insertion sites to include n bases upstream and downstream of the predicted insertion site does not revisit the GenBank file: It directly copies the feature information from the original Tn insertion site to its cognate expanded sites.

Therefore, any Tn insertions on the border of genomic features may not have correct annotations for their cognate expanded list of sites.