Quickstart Guide 

Install 

To install iGUIDE, simply clone the repository to the desired destination.:

git clone https://github.com/cnobles/iGUIDE.git

Then initiate the install using the install script. If you would like the installed environment to be named something other than ‘iguide’, the new conda environment name can be provided to the install.sh script as provided below.:

cd path/to/iGUIDE
bash install.sh

Or:

cd path/to/iGUIDE
bash install.sh -e {env_name}

Additionally, help information on how to use the install.sh can be accessed by:

bash install.sh -h

Setup a Run 

Once the config and sampleInfo files have been configured, a run directory can be created using the command below where {ConfigFile} is the path to your configuration file:

cd path/to/iGUIDE
iguide setup {ConfigFile}

The directory should look like this (RunName is specified in the ConfigFile):

> tree analysis/{RunName}
analysis/{RunName}/
├── config.yml -> {path to ConfigFile}
├── input_data
├── logs
├── output
├── process_data
└── reports

Components within the run directory:

config.yml - This is a symbolic link to the config file for the run
input_data - Directory where input fastq.gz files can be deposited
logs - Directory containing log files from processing steps
output - Directory containing output data from the analysis
process_data - Directory containing intermediate processing files
reports - Directory containing output reports and figures

As a current convention, all processing is done within the analysis directory. The above command will create a file directory under the analysis directory for the run specified in by the config (‘/iGUIDE/analysis/{RunName}’). At the end of this process, iGUIDE will give the user a note to deposit the input sequence files into the /analysis/{RunName}/input_data directory. Copy the fastq.gz files from the sequencing instrument into this directory if you do not have paths to the files specified in the config file.

iGUIDE typically uses each of the sequencing files (R1, R2, I1, and I2) for processing since it is based on a dual barcoding scheme. If I1 and I2 are concatenated into the read names of R1 and R2, it is recommended the you run bcl2fastq ... --create-fastq-for-index-reads on the machine output directory to generate the I1 and I2 files.

As iGUIDE has its own demultiplexing, it is recommend to not use the Illumina machine demultiplexing through input of index sequences in the SampleSheet.csv. If your sequence data has already been demultiplexed though, please see the User Guide for setup instructions.

List Samples in a Run 

As long as the config and sampleInfo files are present and in their respective locations, you can get a quick view of what samples are related to the project. Using the iguide list_samples command will produce an overview table on the console or write the table to a file (specified by the output option). Additionally, if a supplemental information file is associated with the run, the data will be combined with the listed table.:

> iguide list_samples configs/simulation.config.yml

Specimen Info for : simulation.

 specimen   replicates       gRNA        nuclease
---------- ------------ --------------- ----------
   iGXA         1            TRAC         Cas9v1
   iGXB         1        TRAC;TRBC;B2M    Cas9v1
   iGXD         1             NA            NA

Processing a Run 

Once the input_data directory has the required sequencing files, the run can be processed using the following command:

cd path/to/iGUIDE/
iguide run {ConfigFile}

Snakemake offers a great number of resources for managing the processing through the pipeline. I recommend familiarizing yourself with the utility (https://snakemake.readthedocs.io/en/stable/).

An Example Workflow 

To perform a local test of running the iGUIDE informatic pipeline, run the below code after installing. This block first activates your conda environment, ‘iguide’ by default, and then creates a test directory within the analysis directory. The run information is stored in the run specific configuration file (config file). Using the -np flag with the snakemake call will perform a dry-run (won’t actually process anything) and print the commands to the terminal, so you can see what snakemake is about to perform. Then the entirety of processing can start.:

# If conda is not in your path ...

source ${HOME}/miniconda3/etc/profile.d/conda.sh

# Activate iguide environment

conda activate iguide

# After constructing the config file and having reference files (i.e. sampleinfo)
# You can check the samples associated with the run.

iguide list_samples configs/simulation.config.yml

# Create test analysis directory

iguide setup configs/simulation.config.yml

# Process a simulation dataset

iguide run configs/simulation.config.yml -- -np
iguide run configs/simulation.config.yml -- --latency-wait 30

# Processing will complete with several reports, but if additional analyses are required,
# you can re-evaluate a run by its config file. Multiple runs can be evaluated together,
# just include multiple config files.

iguide eval configs/simulation.config.yml \
  -o analysis/simulation/output/iguide.eval.simulation.test.rds \
  -s sampleInfo/simulation.supp.csv

# After evaluation, generate a report in a different format than standard.
# Additionally the evaluation and report generation step can be combined using
# config file(s) as inputs for the 'report' subcommand (using the -c flag instead of -e).

iguide report -e analysis/simulation/output/iguide.eval.simulation.test.rds \
  -o analysis/simulation/reports/report.simulation.pdf \
  -s sampleInfo/simulation.supp.csv \
  -t pdf

# When you are all finished and ready to archive / remove excess files, a minimal structure
# can be achieved with the 'clean' subcommand.

iguide clean configs/simulation.config.yml

# Or you realized you messed up all the input and need to restart

iguide clean configs/simulation.config.yml --remove_proj

# Deactivate the environment

conda deactivate

Reviewing Results 

The output reports from a run are deposited under analysis/{RunName}/reports. For more informtion on output files, see User Guide!

Quickstart Guide

Install

Setup a Run

List Samples in a Run

Processing a Run

An Example Workflow

Reviewing Results