Package: knock-knock-x
knock-knockknock-knockis a tool for exploring, categorizing, and quantifying the sequence outcomes produced by genome editing experiments.Installationcondaconda config --add channels bioconda
conda config --add channels conda-forge
conda install knock-knockpippip install knock-knockIf installing withpip, non-Python dependencies need to be installed separately:blastn(2.7.1)minimap2(2.16)samtools(1.9)STAR(2.7.1)GNU parallel(20190522)Aboutknock-knocktries to identify the different ways that genome editing experiments can produce unintended shufflings and rearrangments of the intended editing outcome.
In order to do this, the strategy used to align sequencing reads makes as few assumptions as possible about how the reads should look.
Instead, it takes each amplicon sequencing read and attempts to produce a comprehensive set of local alignments between portions of the read and all relevant sequences present in the edited cell.
Each read is then categorized by identifying a parsimonious subset of local alignments that cover the whole read and analyzing the architecture of this set of covering alignments.knock-knocksupports Pacbio CCS data for longer (~thousands of nts) amplicons and paired-end Illumina data for shorter (~hundreds of nts) amplicons.Visualizationknock-knockprovides a few ways to interactively explore the different types of alignment architectures produced by each experiment. Clickherefor a guided tour, orherefor a small live demo.Summary tableOutcome-stratified amplicon length distributionsGetting startedThis tutorial will walk you through the process of using knock-knock to analyze amplicon sequencing data of an editing experiment, broken down into six steps:Setting up a project directoryObtain reference genomes and build alignment indices from themProvide information about the genomic locii targeted for editing and HDR donor sequencesFill out sample sheets associating each sample with sequencing data files and an editing strategyProcess data to generate alignments and classify outcomesGenerate summary tables and visualizationsSetting up a project directoryThe first step in using knock-knock is to create a project directory that will hold all input data, references sequences, and analysis output for a given project.Every time knock-knock is run, this directory is given as a command line argument to tell knock-knock which project to analyze.Throughout this documentation,PROJECT_DIRwill be used as a stand-in for the path to an actual project directory.knock-knock is packaged with some small example data sets for testing purposes. To install this example data to a user-specified project directory, runknock-knock install_example_data PROJECT_DIRAfter running this command, PROJECT_DIR will containPROJECT_DIR
├── data
│   ├── illumina
│   │   ├── BCAP31_ultramer_R1.fastq.gz
│   │   ├── BCAP31_ultramer_R2.fastq.gz
│   │   ├── CLTA_PCR_R1.fastq.gz
│   │   ├── CLTA_PCR_R2.fastq.gz
│   │   └── sample_sheet.csv
│   └── pacbio
│       ├── RAB11A_PCR.fastq.gz
│       ├── RAB11A_plasmid.fastq.gz
│       └── sample_sheet.csv
└── targets
    ├── amplicon_primers.csv
    ├── donors.csv
    ├── sgRNAs.csv
    └── targets.csvObtaining reference sequences and building indicesOnce you have created a project directory,knock-knockneeds to be provided with the reference genome of a targeted organism in fasta format in order to build indices from this reference.
These files are stored in directory calledindicesinside a project directory.knock-knock provides a built-in way to download references and build indices for human (hg38), mouse (mm10), or e. coli genomes. To do this, runknock-knock build-indices PROJECT_DIR ORGANISM [--num-threads NUM_THREADS]where ORGANISM is one of hg38, mm10, or e_coli, and NUM_THREADS is an optional argument that can be provided to use multiple threads for index building.
(This can take up to several hours for mammalian-scale genomes.)Running this command for hg38 will populatePROJECT_DIR/indices/hg38with the following files:PROJECT_DIR/indices/hg38/
├── STAR
│   ├── Genome
│   ├── SA
│   ├── SAindex
│   ├── chrLength.txt
│   ├── chrName.txt
│   ├── chrNameLength.txt
│   ├── chrStart.txt
│   └── genomeParameters.txt
├── fasta
│   ├── hg38.fa
│   └── hg38.fa.fai
└── minimap2
    └── hg38.mmiAlternatively, if reference genomes and indices already exist (e.g. in another project's directory), a YAML filePROJECT_DIR/index_locations.yamlthat lists paths can be provided.Specifying targetsThe next step is to provide information about which genomic location was targeted for editing and the sequence of the donor that was provided (if any).knock-knockrefers to the combination of a genomic location and associated homology donor as atarget.
Information about targets is stored in a directory calledtargetsinside a project directory.Genomic location is specified by providing the name of genome targeted (which must exist in PROJECT_DIR/indices), the protospacer of the (SpCas9) sgRNA that was used for cutting, and the amplicon primers flanking the genomic location of this protospacer that were used to amplify the genomic DNA.Targets are defined in a set of csv files inside thetargetsdirectory. A group of "parts-list" filessgRNAs.csv,amplicon_primers.csv,donors.csv, andextra_sequences.csvare used to register named sequences of each csv's corresponding type, and a master csv filePROJECT_DIR/targets/targets.csvdefines each target using references to these named sequences.A target is defined by filling out a row inPROJECT_DIR/targets/targets.csv, which must have the following columns:name: a short, descriptive name for the targetgenome: the name of the genome targeted (which must exist inPROJECT_DIR/indices)sgRNA_sequence: name of the protospacer sequence that was cut. knock-knock can analyze data produces by cutting with multiple nearby guides in no-donor mode. If there are multiple guides, include all sgRNA names joined by semicolons.amplicon_primers: name of the primer pair used to generate the amplicon for sequencingdonor_sequence: name of the homology-arm-containing donor, if anynonhomologous_donor_sequence: name of the non-homology-arm containing donor, if anyextra_sequences: name(s) of any extra sequences that may be present, joined by semicolons.As an example, the contents of thetargets.csvfile included with knock-knock's example data are:name,genome,sgRNA_sequence,donor_sequence,amplicon_primers,nonhomologous_donor_sequence,extra_sequences
BCAP31_GFP11_U_ILL,hg38,BCAP31,BCAP31_GFP11_U,BCAP31_ILL,,
CLTA_GFP11_PCR_ILL,hg38,CLTA,CLTA_GFP11_PCR,CLTA_ILL,,
RAB11A_150nt_plasmid,hg38,RAB11A,pML217_RAB11A-150HA,RAB11A_PAC,,
RAB11A_150nt_PCR,hg38,RAB11A,RAB11A-150HA_PCR_donor,RAB11A_PAC,,Further details:ThesgRNA_sequencecolumn oftargets.csvshould reference entries insgRNAs.csv.
Each row ofsgRNAs.csvdefines a single named sgRNA sequence, with columnsnameandsgRNA_sequence.
sgRNA sequences should be given as 5' to 3' sequence and not include the PAM.
They must exactly match a sequence in the targeted genome.As an example, the contents of thesgRNAs.csvfile included with knock-knock's example data are:name,sgRNA_sequence
BCAP31,GATGGTCCCATGGACAAGA
CLTA,GAACGGATCCAGCTCAGCCA
RAB11A,GGTAGTCGTACTCGTCGTCGTheamplicon_primerscolumn oftargets.csvshould reference entries inamplicon_primers.csv.
Each row ofamplicon_primers.csvdefines a named amplicon primer pair, with columnsnameandprimer_sequences.
Primer sequences should be given as the 5' to 3' sequences of the primer pair (i.e. the two sequences should be on opposite strands) joined by a semicolon.
If a primer pair is used together with an sgRNA, there must exist exact matches to the two primer sequences on opposite sides of the sgRNA sequence somewhere in the targeted genome.As an example, the contents of theamplicon_primers.csvfile included with knock-knock's example data are:name,amplicon_primer_sequences
BCAP31_ILL,GCTGTTGTTAGGAGAGAGGGG;GGGAAGCAGAAGGGCACAAA
CLTA_ILL,ACCGGATACACGGGTAGGG;AGCCGGGTCTTCTTCGC
RAB11A_PAC,GCAGTGAAGAAGCTCATTAAGACAAC;GAAGGTAGAGAGAGTTGCCAAATGGThedonor_sequenceandnonhomologous_donor_sequencecolumns oftargets.csvshould reference entries indonors.csv.
Rows ofdonors.csvdefine named donors, with columnsname,donor_type, anddonor_sequence.
If a donor is used in thedonorcolumn of a target definition, its sequence must contain two homology arms that flank the cut site of target's sgRNA.
Settingdonor_typetoplasmidcauses knock-knock to be aware that the sequence has a circular topology when processing alignments to it.As an example, the contents of thedonors.csvfile included with knock-knock's example data are:name,donor_type,donor_sequence
BCAP31_GFP11_U,ssDNA,CTACTGCTGTGGGATTTCTGTCCCTTTCCAGGCTG...
CLTA_GFP11_PCR,PCR,GGGAACCTCTTCTGTAACTCCTTAGCGTCGGTTGGTT...
pML217_RAB11A-150HA,plasmid,agcccgaccgctgcgccttatccggtaa...
RAB11A-150HA_PCR_donor,PCR,GCCGGAAATGGCGCAGCGGCAGGGAGGGG...where the actual donor sequences have been truncated for display purposes.After filling out all target-specification csvs, runknock-knock build_targets PROJECT_DIRto convert the information you have provided into the form needed for subsequent analysis.Sample sheetsInput sequencing data fastq files should be stored in a directory calleddatainside the project directory, with each group of experiments (typically from one sequencing run) stored in a further subdirectory (e.g.PROJECT_DIR/data/EXAMPLE_GROUP).Each group subdirectory needs a sample sheet to tell knock-knock which target to align each experiment to.
Samples are defined by rows insample_sheet.csv.
Every sample sheet should contain the columns:sample: a short, descriptive name of the sampleplatform:illuminaorpacbiotarget_info: the name of the target (which must have been built as describedabove)supplemental_indices: the name(s) of full genomes to which reads should be aligned, joined by semicolons. This should typically be the name of the targeted organism, plus e_coli if a plasmid donor produced in e. coli was used. Genome names referenced must exist inPROJECT_DIR/indicesas describedabove.color: an optional color to associate with this sample in visualizations. Can be an integer or any string format that matplotlib recognizes (seehere).The columns used to specify which fastq files belong to each sample are different for Illumina and Pacbio sequencing runs.
In both cases, all fastq files must be located inPROJECT_DIR/data/EXAMPLE_GROUP/and should be given with these leading directory components removed (i.e. as would be returned bybasename). Fastq files can be gzipped.Illumina sample sheets should contain columnsR1andR2, which should specify R1 and R2 file names for each sample.Pacbio sample sheets should contain columnCCS_fastq_fn, which should specify a circular consensus sequence fastq file name for each sample.As examples, the contents ofdata/illumina/sample_sheet.csvin knock-knock's example data are:sample,platform,R1,R2,target_info,supplemental_indices,color
B_ULT,illumina,BCAP31_ultramer_R1.fastq.gz,BCAP31_ultramer_R2.fastq.gz,BCAP31_GFP11_U_ILL,hg38,1
C_PCR,illumina,CLTA_PCR_R1.fastq.gz,CLTA_PCR_R2.fastq.gz,CLTA_GFP11_PCR_ILL,hg38,2and the contents ofdata/pacbio/sample_sheet.csvare:sample,platform,CCS_fastq_fn,target_info,supplemental_indices,max_relevant_length,color
R_plasmid,pacbio,RAB11A_plasmid.fastq.gz,RAB11A_150nt_plasmid,hg38;e_coli,6000,1
R_PCR,pacbio,RAB11A_PCR.fastq.gz,RAB11A_150nt_PCR,hg38;e_coli,6000,2Processing samplesOnce all relevant targets have been built and sample sheets filled out, process sequencing data from a single sample by runningknock-knock process PROJECT_DIR EXAMPLE_GROUP EXAMPLE_SAMPLETo process multiple samples in parallel, runknock-knock parallel PROJECT_DIR MAX_PROCSwhich will process all samples in all groups in PROJECT_DIR up to MAX_PROCS at a time. To process only samples from a single group,
runknock-knock parallel PROJECT_DIR MAX_PROCS --group EXAMPLE_GROUPGenerating tablesAfter experiments have been processed, generate tables summarizing the frequencies of different read architectures in each sample by runningknock-knock table BASE_DIRwhich will createPROJECT_DIR/results/EXAMPLE_GROUP.html. Seeherefor an explanation of these tables.