Quantifies CRISPR editing outcomes with CRISPResso2 (Clement 2019 Nat Biotechnol) across Cas9-nuclease (indels, HDR), CBE and ABE base editors (target conversion + bystander), and prime editor (pegRNA-templated) modes. Covers single-amplicon (CRISPResso), multi-sample batch (CRISPRessoBatch), pooled-amplicon (CRISPRessoPooled), WGS off-target (CRISPRessoWGS), and sample-comparison (CRISPRessoCompare) workflows; quantification-window math that controls what is called edited; substitution-vs-indel diagnostic to distinguish BE from Cas9 contamination; MMEJ deletion pattern interpretation; allele-frequency tables; and failure modes from amplicon misalignment or contamination. Use when quantifying editing from amplicon sequencing, choosing CRISPResso mode by design, distinguishing intended edits from bystanders and indel byproducts, debugging low-alignment runs, or generating publication-grade editing reports.
Quantifies CRISPR editing outcomes with CRISPResso2 (Clement 2019 Nat Biotechnol) across Cas9-nuclease (indels, HDR), CBE and ABE base editors (target conversion + bystander), and prime editor (pegRNA-templated) modes. Covers single-amplicon (CRISPResso), multi-sample batch (CRISPRessoBatch), pooled-amplicon (CRISPRessoPooled), WGS off-target (CRISPRessoWGS), and sample-comparison (CRISPRessoCompare) workflows; quantification-window math that controls what is called edited; substitution-vs-indel diagnostic to distinguish BE from Cas9 contamination; MMEJ deletion pattern interpretation; allele-frequency tables; and failure modes from amplicon misalignment or contamination. Use when quantifying editing from amplicon sequencing, choosing CRISPResso mode by design, distinguishing intended edits from bystanders and indel byproducts, debugging low-alignment runs, or generating publication-grade editing reports.
If code throws ImportError, AttributeError, or TypeError, introspect the installed package and adapt the example to match the actual API rather than retrying.
CRISPResso2 Editing Quantification
"Quantify CRISPR editing from my amplicon sequencing" -> Align amplicon reads against the reference, classify each read as unmodified / NHEJ / HDR / base-edited / prime-edited within the quantification window, and report per-edit-type frequencies, indel size distributions, allele-frequency tables, and substitution-position profiles.
CLI: CRISPResso -- single amplicon, single sample
CLI: CRISPRessoBatch -- multi-sample with per-sample parameters
CLI: CRISPRessoPooled -- multi-amplicon pooled amplicon sequencing
CLI: CRISPRessoWGS -- off-target quantification from whole-genome BAM
CLI: CRISPRessoCompare -- pairwise outcome comparison (e.g., treated vs untreated)
Mode Decision Tree
Experimental design
Mode
Key parameters
Single amplicon, single sample (e.g. pilot edit validation)
CRISPResso
--amplicon_seq, --guide_seq
Same amplicon, many samples (e.g. timecourse, dose response)
CRISPRessoBatch
--batch_settings table
Many amplicons, pooled in one library (e.g. arrayed validation pool)
CRISPRessoPooled
--amplicons_file
Off-target survey from whole-genome BAM
CRISPRessoWGS
--bam_file, --reference_file, --region_file
Comparing two CRISPResso runs (e.g. condition A vs B)
Pooled-amplicon mode applied to amplicons that share primer sequences -- reads get misassigned.
Base editor mode without specifying --conversion_nuc_from/--conversion_nuc_to -- defaults assume CBE (C->T); ABE runs will misclassify.
Prime editor mode without --prime_editing_pegRNA_extension_seq -- the RTT template is missing, no edit is detectable.
The Quantification Window
Why this matters for postdoc-level use: CRISPResso classifies reads as "edited" or "unmodified" based on whether modifications fall inside the quantification window (not the whole amplicon). The window is centered on the predicted cut site (Cas9: 3 bp upstream of PAM; Cas12a: 18 bp downstream of PAM) with a default size of 1. --quantification_window_size N extends N bp on EACH side, so the window is 2N bp wide.
# Default Cas9 setup
--quantification_window_size 1 # 1-bp window at cut site
--quantification_window_center -3 # 3 bp upstream of PAM# Base editor: widen window to cover editing positions 4-8
--quantification_window_size 10 # 10 bp each side (20 bp total)
--quantification_window_center -10 # center on the editing window
Consequences of mis-sized window:
Too narrow: misses edits at HDR positions or far bystanders; underestimates editing
Too wide: includes random sequencing errors; inflates editing rate
Wrong center: edits at correct position are scored as outside the window
For base editing screens a widened window is conventional; CRISPResso2's own base-editor guidance uses --quantification_window_center -17 with a window sized to span the editing positions. For prime editing with multi-base templated edits, widen to encompass the entire edit region.
Single-Amplicon Cas9 Editing
Goal: Quantify indel frequencies and HDR efficiency from a single target site.
Approach: Align FASTQ reads to the reference and (optional) expected-HDR amplicon, classify each read, and report aggregated statistics.
Same, restricted to quantification window (base-editor analysis)
Base Editor Quantification
Goal: Distinguish target base conversion from bystander edits and indel byproducts.
Approach: Run CRISPResso with --base_editor_output flag and specify the conversion direction; widen the quantification window to cover the editing window.
Cas9-like cut artifacts; should be <5% for clean BE
Substitution-vs-indel ratio
Derived
Ratio >10 indicates clean BE; <3 indicates cut-mediated mutagenesis instead
Critical: Bystander editing is intrinsic to base editors (the deaminase acts across a 5-nt window); it is not noise. Report bystander rates alongside target rates. See [[base-editing-analysis]] for variant-call implications.
Prime Editor Quantification
Goal: Quantify pegRNA-templated edits versus indel byproducts and partial edits.
Approach: Provide spacer, extension (PBS + RTT), and scaffold sequences; CRISPResso identifies reads matching the intended edit.
Failure mode: Amplicons with shared primer regions get reads assigned to whichever amplicon comes first. Design primers with ≥3-bp distinguishing regions or use unique molecular identifiers.
WGS Off-Target Mode
Goal: Quantify off-target editing from whole-genome sequencing.
Approach: Provide BAM file + reference + BED file of suspected off-target sites; CRISPResso extracts reads from each region and quantifies edits.
Use case: Validate empirically that an in vivo / clinical-grade edit has minimal off-target activity (combine with GUIDE-seq or CIRCLE-seq predicted sites).
Parse Output in Python
Goal: Pull editing metrics into downstream analysis or reports.
Approach: Read the tab-separated quantification files and the JSON metadata.
import pandas as pd
import json
from pathlib import Path
defparse_crispresso(output_dir):
'''Extract key metrics from CRISPResso output directory.'''
out = {}
# Mapping statistics
map_stats = {}
withopen(Path(output_dir) / 'CRISPResso_mapping_statistics.txt') as f:
for line in f:
k, v = line.strip().split('\t')
map_stats[k] = v
out['mapping_pct'] = float(map_stats.get('READS_ALIGNED_PERCENTAGE', 'nan'))
out['reads_aligned'] = int(map_stats.get('READS_ALIGNED', '0'))
# Editing quantification
quant = pd.read_csv(Path(output_dir) / 'CRISPResso_quantification_of_editing_frequency.txt', sep='\t')
out['editing_quant'] = quant.set_index('Amplicon').to_dict()
# JSON metadata
info_path = Path(output_dir) / 'CRISPResso2_info.json'if info_path.exists():
out['info'] = json.loads(info_path.read_text())
return out
Failure Modes
Low alignment rate (<50%)
Trigger: Wrong amplicon sequence (off by one nt, wrong strand, primer-trimmed vs untrimmed).
Mechanism: CRISPResso fails to align reads beyond the amplicon edges; discards as unmappable.
Symptom:READS_ALIGNED_PERCENTAGE <50%; per-position coverage drops at amplicon edges.
Fix: Re-derive amplicon from genome at primer-trimmed boundaries; verify strand orientation; check that primers are NOT included in --amplicon_seq.
High substitution rate but low indel (Cas9 sample)
Trigger: Sample contamination with adjacent amplicon, primer-dimer, or sequencing error inflation.
Mechanism: Random substitutions inflate the per-position substitution rate without true indels.
Symptom: Substitutions >2% at base positions outside the cut site; alignment metrics look fine.
Fix: Increase --min_average_read_quality to 30+; filter contaminating amplicons; check primer-dimer in CRISPResso_RUNNING_LOG.txt.
Trigger: Base-editor sample with wide quantification window; bystander Cs at adjacent positions counted as edits.
Mechanism: Default --quantification_window_size 10 includes all positions in editing window; bystander edits are real but distinct from target edit.
Symptom: Editing efficiency 80%+ but target SNV is 30%; bystander rate is 50%.
Fix: Always read the per-position table (Quantification_window_nucleotide_percentage_table.txt), not just the aggregate. Report target and bystander rates separately. See [[base-editing-analysis]].
Prime editor sample with high scaffold incorporation
Trigger: RTT is too short relative to PBS, or pegRNA stops short.
Mechanism: Reverse transcriptase reads past the edit into scaffold sequence; product is detectable but undesired.
Symptom: Scaffold incorporation >5%; intended edit efficiency lower than expected.
Fix: Re-design pegRNA with longer RTT; verify with PRIDICT2 (see [[prime-editing-screens]]).
MMEJ deletion misclassified as NHEJ
Trigger: Deletions with microhomology at junction; CRISPResso reports them as indels but doesn't distinguish MMEJ.
Mechanism: MMEJ creates predictable deletions using flanking microhomologies; biologically distinct from random NHEJ.
Symptom: Recurring same-size deletions in allele table (e.g., -7 bp deletion in 30% of reads).
Fix: Examine Alleles_frequency_table for over-represented allele patterns; flag MMEJ-mediated deletions for interpretation (these may be inferred from indel hotspots).
Quantitative Thresholds
Threshold
Value
Source / Rationale
Cas9 editing efficiency (functional KO)
>70% indels
Field convention; below this, KO is incomplete
Indel rate (clean base editor)
<5%
Field convention; >5% = unwanted cut activity
Target conversion (CBE)
>30%
Variable by target; below this, screen power is poor
Target conversion (ABE)
>30%
ABE typically lower per-base than CBE
Bystander rate (BE)
<10% acceptable; <5% ideal
Application-dependent; for variant function studies, must be controlled
Intended-edit % (prime editor)
>5% per-edit
Field convention; can be 50%+ at favorable sites
Scaffold incorporation (PE)
<2%
High-quality pegRNA design
Alignment rate
>85%
Below this, amplicon design or contamination issue
Minimum read quality
Phred 30
Q30 Illumina base-call-accuracy standard
Quantification window size (Cas9)
1
Clement 2019 default; precise cut-site analysis
Quantification window size (BE)
10
Cover editing window positions 4-13
Common Errors
Error / symptom
Cause
Solution
Alignment rate <50%
Wrong amplicon sequence
Re-verify; primers should NOT be in amplicon_seq
All reads "modified"
Misaligned reference
Check amplicon strand; reverse-complement test
BE shows mostly indels
Cas9 contamination or wrong protein
Re-derive cell line origin; check Cas9 vs nCas9-BE3
Inconsistent batch results
Different amplicon_seq per sample
Use CRISPRessoBatch with consistent amplicon
Pooled-amplicon misassignment
Primer overlap between amplicons
Re-design with ≥3-bp distinguishing regions
Out-of-window edits ignored
Window too narrow
Increase --quantification_window_size
Scaffold incorporation high (PE)
RTT too short
Re-design pegRNA
Allele frequency dominated by 1 read
Low input / clonal
Verify input cell count; rerun if singleton
References
Clement K et al. 2019. Nat Biotechnol 37:224. CRISPResso2 algorithm and modes.
Pinello L et al. 2016. Nat Biotechnol 34:695. Original CRISPResso.
Anzalone AV et al. 2019. Nature 576:149. Prime editing (PE-1/PE-2/PE-3).
Komor AC et al. 2016. Nature 533:420. Base editing (BE3).
Findlay GM et al. 2018. Nature 562:217. Saturation genome editing.
Related Skills
crispr-screens/base-editing-analysis - Variant-function analysis using CRISPResso2 BE output
