6 | 
7 | 
8 | 
9 | 10 |
5 |
6 |
7 |
8 |
9 |
10 |
15 | 
16 |
21 | 
22 |
23 | ## Overview
24 |
25 | `guide-counter` is a tool for processing FASTQ files from CRISPR screen experiments to generate a matrix of per-sample guide counts. It can be used as a faster, more accurate, drop in replacement for `mageck count`. By default `guide-counter` will look for guide seqeunces in the reads with 0 or 1 mismatches vs. the expected guides, but can be run in exact matching mode.
26 |
27 | ## Why `guide-counter`?
28 |
29 | If you have any experience analyzing CRISPR screens you've almost certainly tried [`mageck`][mageck-link]. It's widely used, highly cited and generally works well. Surprisingly though, `mageck count` is both rather slow _and_ misses counting a non-trivial amount of the data.
30 |
31 | As an example, we ran data from the [Sanson et al][sanson-link] paper through both tools. The dataset consists of:
32 |
33 | |Sample|Reads|Gzipped FASTQ Size|
34 | |------|-----|------------------|
35 | |Plasmid|9,821,128|377M|
36 | |RepA|76,471,324|2.3G|
37 | |RepB|85,301,059|2.5G|
38 | |RepC|75,356,900|2.2G|
39 |
40 | The following plot shows the amount of data recovered per sample by each of three different analyses:
41 |
42 | 
43 |
44 | And the following plot shows the runtime for each of the three analyses performed using a single CPU core/thread on an Intel Core i9 powered MacBook Pro laptop:
45 |
46 | 
47 |
48 | ## Installation
49 |
50 | Installation can be done using conda:
51 |
52 | ```
53 | conda install -c bioconda guide-counter
54 | ```
55 |
56 | or with `cargo` if installed:
57 |
58 | ```
59 | cargo install guide-counter
60 | ```
61 | ## Example Workflow
62 |
63 | The following shows an example of running `guide-counter` followed by `mageck test` on data from the [Sanson et al. 2018 paper][sanson-link]:
64 |
65 | ```
66 | guide-counter count \
67 | --input plasmid.fq.gz RepA.fq.gz RepB.fq.gz RepC.fq.gz \
68 | --control-pattern control \
69 | --essential-genes metadata/training_essentials.txt \
70 | --nonessential-genes metadata/training_nonessential.txt \
71 | --library metadata/broadgpp-brunello-library-corrected.txt.gz \
72 | --output sanson
73 |
74 | mageck test \
75 | --count-table sanson.counts.txt \
76 | --control-id plasmid \
77 | --treatment-id RepA,RepB,RepC \
78 | --norm-method median \
79 | --output-prefix sanson.test
80 |
81 | ```
82 |
83 | ## Inputs
84 |
85 | The full usage for `guide-counter count` is reproduced below; this section describes a few of the key inputs in more detail:
86 |
87 | |Input Option|Required|Description|
88 | |------------|--------|-----------|
89 | |`--input`|Yes|FASTQ files one per sample. Files may be gzipped or uncompressed.|
90 | |`--samples`|No|Names for the samples, matched positionally to the FASTQs. If not provided then the input file names minus any `.[fq|fastq][.gz]` suffixes are used instead.|
91 | |`--essential-genes`|No|An optional file of known essential genes. May be gzipped or uncompressed. May be either just gene names, one per line, or tab-delimited with the gene in the first column. If given, guides will be labeled as essential for matching genes, and mean coverage of guides for essential genes computed.|
92 | |`--nonessential-genes`|No|An optional file of known nonessential genes. May be gzipped or uncompressed. May be either just gene names, one per line, or tab-delimited with the gene in the first column. If given, guides will be labeled as nonessential for matching genes, and mean coverage of guides for nonessential genes computed.|
93 | |`--control-guides`|No|An optional file of guide IDs for control guides. May be gzipped or uncompressed. May be either just guide IDs, one per line, or tab-delimited data with the guide ID in the first column. If given, matching guides will be labeled as controls, and mean coverage of control guides computed. May be used alone _or_ in conjunction with `--control-pattern`.|
94 | |`--control-pattern`|No|An optional regular expression which is applied (case insensitive) to _both_ guide IDs and gene names, and when a match is found, guides are labeled as controls. For example `--control-pattern control` works well for many human libraries.|
95 |
96 | ## Outputs
97 |
98 | The output files are generated:
99 |
100 | 1. `{output}.counts.txt` - a standard count matrix with columns for the guide ID and gene, then one column per sample with raw/unnormalized guide counts.
101 | 2. `{output}.-extended-counts.txt` - an extended version of the counts matrix which includes a `guide_type` column which will have one of `[Essential, Nonessential, Control, Other]` per guide as determined based on the gene lists and control information provided.
102 | 3. `{output}.stats.txt` - a file of computed statistics, one row per input sample/FASTQ.
103 |
104 | The columns in the stats file are:
105 |
106 | |Column|Description|
107 | |------|-----------|
108 | |file|The path to the input FASTQ file used to generate the stats.|
109 | |label|The label or sample name given to the sample.|
110 | |total_guides|The total number of guides in the guide library (not sample dependent).|
111 | |total_reads|The total number of reads in the input FASTQ file.|
112 | |mapped_reads|The number of reads that could be mapped to a guide.|
113 | |frac_mapped|The fraction of reads (0-1) that could be mapped to a guide.|
114 | |mean_reads_per_guide|The mean number of reads mapped to each guide in the library.|
115 | |mean_reads_essential|The mean number of reads mapped to guides for essential genes.|
116 | |mean_reads_nonessential|The mean number of reads mapped to guides for nonessential genes.|
117 | |mean_reads_control|The mean number of reads mapped to control guides.|
118 | |mean_reads_other|The mean number of reads mapped to other guides (guides not flagged as essential, nonessential or control).|
119 | |zero_read_guides|
120 |
121 |
122 | ## Usage
123 |
124 | Usage for `guide-counter count`:
125 |
126 | ```
127 | guide-counter-count
128 |
129 | Counts the guides observed in a CRISPR screen, starting from one or more FASTQs. FASTQs are one per
130 | sample and currently only single-end FASTQ inputs are supported.
131 |
132 | A set of sample IDs may be provided using `--samples id1 id2 ..`. If provided it must have the same
133 | number of values as input FASTQs. If not provided the FASTQ names are used minus any fastq/fq/gz
134 | suffixes.
135 |
136 | Automatically determines the range of valid offsets within the sequencing reads where the guide
137 | sequences are located, independently for each FASTQ input. The first `offset-sample-size` reads
138 | from each FASTQ are examined to determine the offsets at which guides are found. When processing the
139 | full FASTQ, checks only those offsets that accounted for at least `offset-min-fraction` of the first
140 | `offset-sample-size` reads.
141 |
142 | Matching by default allows for one mismatch (and no indels) between the read sub-sequence and the
143 | expected guide sequences. Exact matching may be enabled by specifying the `--exact-match` option.
144 |
145 | Two output files are generated. The first is named `{output}.counts.txt` and contains columns for
146 | the guide id, the gene targeted by the guide and one count column per input FASTQ with raw/un-
147 | normalized counts. The second is named `{output}.stats.txt` and contains basic QC statistics per
148 | input FASTQ on the matching process.
149 |
150 | USAGE:
151 | guide-counter count [OPTIONS] --input ... --library