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

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.

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

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:

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.

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

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.

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:

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.

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

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

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.

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