bio-crispr-screens-crispresso-editing

## Version Compatibility Reference examples tested with: CRISPResso2 2.2.14+ (pinellolab/CRISPResso2), pandas 2.2+, numpy 1.26+, matplotlib 3.8+. Before using code patterns, verify installed versions match. If versions differ: - CLI: `CRISPResso --version`; `CRISPRessoBatch --help`; `CRISPRessoPooled --help`; `CRISPRessoWGS --help`; `CRISPRessoCompare --help` - Python: `from CRISPResso2 import ...` 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) | `CRISPRessoCompare` | two positional output folders | | HDR / knock-in validation | `CRISPResso` with `--expected_hdr_amplicon_seq` | Same as base CRISPResso | | Cytosine base editor (C->T) | `CRISPResso --base_editor_output` | `--conversion_nuc_from C --conversion_nuc_to T` | | Adenine base editor (A->G) | `CRISPResso --base_editor_output` | `--conversion_nuc_from A --conversion_nuc_to G` | | Prime editor (templated edit) | `CRISPResso` with pegRNA parameters | `--prime_editing_pegRNA_spacer_seq`, `--prime_editing_pegRNA_extension_seq`, `--prime_editing_pegRNA_scaffold_seq` | **Fails when:** - 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. ```bash # 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. ```bash CRISPResso \ --fastq_r1 sample_R1.fastq.gz \ --fastq_r2 sample_R2.fastq.gz \ --amplicon_seq <amplicon_sequence_ref_genome> \ --guide_seq <20nt_protospacer_no_PAM> \ --expected_hdr_amplicon_seq <edited_amplicon_for_HDR> \ # OPTIONAL --quantification_window_size 1 \ --quantification_window_center -3 \ --min_average_read_quality 30 \ # Phred quality filter --output_folder sample_results \ --name sample_id # Outputs: # sample_results/<name>/CRISPResso_mapping_statistics.txt # sample_results/<name>/CRISPResso_quantification_of_editing_frequency.txt # sample_results/<name>/Alleles_frequency_table.zip # sample_results/<name>/3a.<ref>.Indel_size_distribution.pdf # sample_results/<name>/4b.<ref>.Insertion_deletion_substitution_locations.pdf # (PDF by default; add --save_also_png for PNG) ``` **Key outputs:** | File | Content | |------|---------| | `CRISPResso_mapping_statistics.txt` | Tab-separated, one data row: READS IN INPUTS, READS AFTER PREPROCESSING, READS ALIGNED, N_COMPUTED_ALN, ... (no percentage columns) | | `CRISPResso_quantification_of_editing_frequency.txt` | % unmodified, % NHEJ, % HDR (if expected), per-edit-class breakdown | | `Alleles_frequency_table.zip` | Per-allele sequences and frequencies (allele-level resolution) | | `Nucleotide_percentage_table.txt` | Per-position A/C/G/T/- frequencies (substitutions + deletions) | | `Quantification_window_nucleotide_percentage_table.txt` | 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. ```bash # Cytosine Base Editor (CBE): C->T conversion CRISPResso \ --fastq_r1 cbe_sample.fastq.gz \ --amplicon_seq <amplicon_seq> \ --guide_seq <20nt_protospacer> \ --base_editor_output \ --conversion_nuc_from C \ --conversion_nuc_to T \ --quantification_window_size 10 \ --quantification_window_center -10 \ --output_folder cbe_results \ --name cbe_sample # Adenine Base Editor (ABE): A->G conversion CRISPResso \ --fastq_r1 abe_sample.fastq.gz \ --amplicon_seq <amplicon_seq> \ --guide_seq <20nt_protospacer> \ --base_editor_output \ --conversion_nuc_from A \ --conversion_nuc_to G \ --quantification_window_size 10 \ --quantification_window_center -10 \ --output_folder abe_results \ --name abe_sample ``` **Reading the output:** | Metric | Where | Interpretation | |--------|-------|----------------| | Target editing % | `Quantification_window_nucleotide_percentage_table.txt`, target C/A row | Primary endpoint | | Bystander editing % | Same table, other C/A positions in window | Off-target byproduct in window | | Indel rate | `CRISPResso_quantification_of_editing_frequency.txt` | 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. ```bash CRISPResso \ --fastq_r1 pe_sample.fastq.gz \ --amplicon_seq <amplicon_seq> \ --guide_seq <20nt_protospacer> \ --prime_editing_pegRNA_spacer_seq <20nt_protospacer> \ --prime_editing_pegRNA_extension_seq <RTT+PBS_sequence> \ --prime_editing_pegRNA_scaffold_seq <scaffold_sequence> \ --output_folder pe_results \ --name pe_sample # Output adds: # Prime-editing outcomes are extra amplicon rows (Reference / Prime-edited / Scaffold-incorporated) # inside CRISPResso_quantification_of_editing_frequency.txt ``` **Reading prime-editor output:** | Metric | Interpretation | |--------|----------------| | Intended edit % | The pegRNA-encoded edit was correctly installed | | Scaffold incorporation % | Reverse transcription read into scaffold instead of stopping at edit; failure mode | | Indel % | Nick-only editing without templated repair; common at low-PE-activity sites | | Unmodified % | Read matches the reference exactly | A high-quality prime-edit run shows intended-edit fraction >5% and scaffold incorporation <2%. See [[prime-editing-screens]] for pegRNA design rules. ## Batch Mode (Multi-Sample, Same Amplicon) **Goal:** Process tens to hundreds of samples with same amplicon design (e.g., a timecourse, dose response, or replicate panel). **Approach:** Provide a tab-separated batch settings file with per-sample parameters; CRISPRessoBatch runs all in parallel. ```bash # batch_settings.txt (tab-separated, headers required) # name fastq_r1 fastq_r2 amplicon_seq guide_seq # t0 t0_R1.fq.gz t0_R2.fq.gz ACGT... GUIDE # t6 t6_R1.fq.gz t6_R2.fq.gz ACGT... GUIDE # t12 t12_R1.fq.gz t12_R2.fq.gz ACGT... GUIDE # t24 t24_R1.fq.gz t24_R2.fq.gz ACGT... GUIDE CRISPRessoBatch \ --batch_settings batch_settings.txt \ --batch_output_folder batch_run \ --skip_failed \ --n_processes 8 # Outputs: # batch_run/CRISPRessoBatch_RUNNING_LOG.txt # batch_run/CRISPRessoBatch_quantification_of_editing_frequency.txt (aggregated) # batch_run/CRISPResso_on_<name>/ for each sample ``` ## Pooled-Amplicon Mode **Goal:** Process multi-amplicon sequencing libraries (e.g., arrayed validation pools). **Approach:** Provide an amplicon table with one row per target; CRISPRessoPooled de-multiplexes reads to the correct amplicon. ```bash # amplicons.txt (tab-separated; header may vary by CRISPResso2 version) # amplicon_name amplicon_seq guide_seq # BRCA1_exon3 ACGT... GUIDE1 # TP53_exon7 ACGT... GUIDE2 # KRAS_codon12 ACGT... GUIDE3 CRISPRessoPooled \ --fastq_r1 pooled_R1.fastq.gz \ --fastq_r2 pooled_R2.fastq.gz \ --amplicons_file amplicons.txt \ --output_folder pooled_run \ --n_processes 8 # Outputs: # pooled_run/SAMPLES_QUANTIFICATION_SUMMARY.txt # pooled_run/CRISPResso_on_<amplicon>/ for each amplicon ``` **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. ```bash CRISPRessoWGS \ --bam aligned.bam \ --reference genome.fa \ --region_file off_targets.bed \ --output_folder wgs_run \ --n_processes 8 ``` **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. ```python import pandas as pd import json from pathlib import Path def parse_crispresso(output_dir): '''Extract key metrics from CRISPResso output directory.''' out = {} # Mapping statistics map_stats = {} with open(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).