bio-crispr-screens-crispresso-editing

What this skill does

## 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` | `--amplicon_file` |
| Off-target survey from whole-genome BAM | `CRISPRessoWGS` | `--bam`, `--reference`, `--regions_file` |
| Comparing two CRISPResso runs (e.g. condition A vs B) | `CRISPRessoCompare` | `--crispresso_output_folder_1`, `_2` |
| 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 (the cut site itself).

```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                 # extend to capture position 4-8
--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, the convention is `--quantification_window_size 10` to cover positions 4-13 from PAM-distal end. 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>/Indel_size_distribution.png
#   sample_results/<name>/Insertion_deletion_substitution.png
```

**Key outputs:**

| File | Content |
|------|---------|
| `CRISPResso_mapping_statistics.txt` | Reads aligned, reads in quantification window, % alignment, % discarded |
| `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) |
| `Reference_modified_chr11_115...png` | Sequencing pile-up over amplicon |

## 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 ide