CRISPRSCope

CRISPRSCope is a Python-based analysis pipeline for single-cell CRISPR DNA sequencing experiments. It takes paired-end FASTQ files, assigns reads to valid cell barcodes, maps reads to expected amplicons, runs CRISPResso2 on each target, summarizes editing outcomes across cells, generates QC and summary plots, and can export results to .h5ad for downstream analysis in Scanpy or related tools.

At a high level, the pipeline:

• reads paired-end FASTQ inputs
• validates and error-corrects cell barcodes
• assigns reads to amplicons using primer matching and genome alignment
• runs CRISPResso2 on per-amplicon read sets
• builds filtered per-cell editing summaries and QC reports
• optionally writes an .h5ad file for downstream single-cell analysis

Installation

For installation, the recommended setup is the portable conda environment file in this repository:

conda env create -f environment.yml
conda activate crisprscope

If you want an editable local install of the package after activating the environment:

pip install -e .

A simple import sanity check is:

python -c "import CRISPRSCope; print(CRISPRSCope.__version__)"

Docker

CRISPRSCope can also be run from a Docker image. The image contains the software environment, but your sequencing data, settings file, barcode file, amplicon file, Bowtie2 index, and output directory should stay outside the image and be mounted at runtime.

Build the image from the repository root:

docker build -t crisprscope:local .

That local image is useful for testing on your own computer, but it only targets your current Docker architecture.

Check that the command-line tools are available:

docker run --rm crisprscope:local python -c "import CRISPRSCope; print(CRISPRSCope.__version__)"
docker run --rm crisprscope:local bowtie2 --version
docker run --rm crisprscope:local samtools --version
docker run --rm crisprscope:local CRISPResso --version

Run an analysis by mounting the folder that contains your settings file and input data. In this example, everything is under the current directory and is available inside the container as /data:

docker run --rm -v "$PWD:/data" crisprscope:local CRISPRSCope /data/example/example_settings.txt

For Docker Desktop from PowerShell, use ${PWD}:

docker run --rm -v "${PWD}:/data" crisprscope:local CRISPRSCope /data/example/example_settings.txt

The paths in the settings file must point to files visible inside the container. Relative paths are resolved relative to the settings file, so keeping the settings file, inputs, references, and results under the same mounted directory is the simplest approach.

To publish a Docker Hub image that supports both Intel/AMD and ARM machines, use Docker Buildx:

docker login
docker buildx build --platform linux/amd64,linux/arm64 -t DOCKERHUB_USERNAME/crisprscope:latest --push .

To publish both a versioned tag and latest:

docker buildx build --platform linux/amd64,linux/arm64 \
  -t DOCKERHUB_USERNAME/crisprscope:0.1.4 \
  -t DOCKERHUB_USERNAME/crisprscope:latest \
  --push .

This repository also includes a GitHub Actions workflow at .github/workflows/dockerhub.yml that publishes a multi-architecture image to Docker Hub. Add repository secrets named DOCKERHUB_USERNAME and DOCKERHUB_TOKEN, then run the workflow manually or push a version tag such as v0.1.4. The workflow builds and smoke-tests the linux/amd64 image on a native Intel/AMD GitHub runner before publishing the multi-architecture image.

Running The Pipeline

CRISPRSCope expects a tab-delimited settings file as its main input:

CRISPRSCope path/to/run_settings.txt

The first positional argument must be the settings file. A log file is written next to that settings file as:

path/to/run_settings.txt.log

Required Inputs

Before running the pipeline, you should have:

• paired-end FASTQ files (r1 and r2)
• a barcode whitelist file with one valid barcode per line
• an amplicon definition file
• a Bowtie2 genome index prefix
• a tab-delimited settings file that points to the above inputs

Example Input Files

These are visual examples only. They are included here to show the expected structure and are not shipped as runnable project files.

Example Settings File

The settings file must be tab-delimited, with one key<TAB>value entry per line.

r1	data/sample_A_R1.fastq.gz,data/sample_B_R1.fastq.gz
r2	data/sample_A_R2.fastq.gz,data/sample_B_R2.fastq.gz
constant1	GTTTAAGAGCTATGCTGGAAACAG
constant2	GTTTTAGAGCTAGAAATAGCAAGT
barcodes	inputs/barcodes.txt
amplicons	inputs/amplicons.tsv
bowtie2_index	references/hg38/hg38
output_root	results/demo_run
processes	8
allowBarcodeMismatches	True
keep_intermediate_files	False
ignore_substitutions	False
assign_reads_to_all_possible_amplicons	False
suppress_sub_crispresso_plots	False
min_total_reads_per_barcode	10
min_reads_per_amplicon_per_cell	0
amplicon_score_min_reads_per_amplicon	5
amplicon_score_min_covered_fraction	0.6666666666666666
amplicon_score_max_barcode_rank	10000
include_high_score_high_depth	True
include_high_score_low_depth	True
include_low_score_high_depth	False
include_low_score_low_depth	False
write_editing_rate_ci	True
editing_rate_ci_bootstrap_iterations	10000
editing_rate_ci_permutation_iterations	10000
editing_rate_ci_confidence_level	0.95
editing_rate_ci_seed	42
editing_rate_ci_coverage_exact_max_reads	10
editing_rate_ci_coverage_bin_width_reads	5
write_h5ad	True
write_output_manifest	False
h5ad_output	results/demo_run.h5ad
h5ad_wt_max_mod_pct	20
h5ad_het_max_mod_pct	80
h5ad_hom_min_mod_pct	80
h5ad_compound_het_min_allele2_pct	20

Example Barcode File

The barcode file is one barcode per line.

AACCGGTTAA
AACCGGTTAC
AACCGGTTAG
TTGCAACGTA
TTGCAACGTC
TTGCAACGTG

Example Amplicon File

The amplicon file is tab-delimited. The first two columns are required:

1. amplicon name
2. amplicon sequence

Optional columns currently supported by the pipeline are:

3. guide sequence
4. reference allele count

AMP_TARGET_1	ACTGACTGACTGACTGACTGACTGACTGACTGACTGACTG	GGACTGACTGACTGACTGA	2
AMP_TARGET_2	TGACCTGATCGATCGTAGCTAGCTAGCTAGCATCGATCGA	CTGATCGATCGTAGCTAGC	2
AMP_TARGET_3	GGCTAACCGGTTAACCGGTTAACCGGTTAACTGACTGACT	ACCGGTTAACCGGTTAACT	2

Example Alternate Alleles File

This file is optional. The current implementation expects a header row and uses:

• column 1: amplicon name
• column 3: comma-separated alternate allele sequences

amplicon_name	label	alternate_alleles
AMP_TARGET_1	edited	ACTGACTGACTGACTGACTGACTGACTGACTGACTGACTG,ACTGACTGACTGACTGACTG---TGACTGACTGACTG
AMP_TARGET_2	edited	TGACCTGATCGATCGTAGCTAGCTAGCTAGCATCGATCGA,TGACCTGATCGATCGTAGCTAG---GCTAGCATCGATCGA

Settings Reference

Required Settings

Key	Description
r1	Comma-separated list of R1 FASTQ files.
r2	Comma-separated list of matching R2 FASTQ files.
constant1	First constant sequence used during barcode/read parsing.
constant2	Second constant sequence used during barcode/read parsing.
barcodes	Path to barcode whitelist file.
amplicons	Path to tab-delimited amplicon definition file.
bowtie2_index	Bowtie2 index prefix.

You may also use genome instead of bowtie2_index; internally the pipeline resolves either key to the Bowtie2 index prefix.

Optional Settings

Key	Default	Description
output_root	settings file path	Prefix used for generated outputs.
processes	all available CPUs	Number of processes to use.
allowBarcodeMismatches	off	Enables single-mismatch barcode rescue.
keep_intermediate_files	False	Keeps intermediate files instead of cleaning them up.
ignore_substitutions	False	Ignores substitution annotations when parsing CRISPResso read-alignment output and summarizing downstream editing calls.
assign_reads_to_all_possible_amplicons	False	If True, assigns ambiguous reads to every plausible amplicon.
suppress_sub_crispresso_plots	False	Disables per-amplicon CRISPResso plot/report generation.
alt_alleles_file	not used	Optional alternate allele definition file.
min_total_reads_per_barcode	10	Minimum total reads required for a barcode to be considered downstream.
min_reads_per_amplicon_per_cell	0	Optional stricter gate requiring this many reads at every usable amplicon before a barcode is scored; it also sets per-amplicon eligibility in editing-rate analyses.
amplicon_score_min_reads_per_amplicon	5	Reads required for an amplicon to count as supported in the breadth score; must be at least 1.
amplicon_score_min_covered_fraction	0.6666666666666666	Fraction of usable amplicons that must be supported for a high score; must be greater than 0 and no greater than 1.
amplicon_score_max_barcode_rank	10000	Largest total-read barcode rank classified as high depth; must be at least 1.
write_editing_rate_ci	True	Enables pointwise bootstrap confidence intervals for first-pass cell/allele editing rates; set to False to disable.
editing_rate_ci_bootstrap_iterations	10000	Number of bootstrap resamples per amplicon; must be at least 100.
editing_rate_ci_permutation_iterations	10000	Number of configured analysis-group label permutations used for each two-sided significance test; must be at least 100.
editing_rate_ci_confidence_level	0.95	Pointwise confidence level; must be greater than 0 and less than 1.
editing_rate_ci_seed	42	Non-negative base seed used for reproducible per-amplicon resampling.
editing_rate_ci_coverage_exact_max_reads	10	Highest per-amplicon read count kept as an exact coverage stratum for the coverage-controlled test; must be non-negative.
editing_rate_ci_coverage_bin_width_reads	5	Width of coverage strata above the exact-count ceiling; must be at least 1. With the defaults, the first binned strata are 11–15, 16–20, and 21–25 reads.
write_editing_rate_depth_stability	False	Enables the optional finite-cohort downsampling table and detailed plot 14 for AllCells and InGroup.
editing_rate_depth_stability_iterations	1000	Number of without-replacement subsamples at each retained-cell percentage; must be at least 100.
editing_rate_depth_stability_percentages	10,25,50,75,90	Strictly increasing, unique retained-cell percentages between 0 and 100; an exact 100% reference is added automatically.
write_h5ad	True	Enables .h5ad export after the main run.
h5ad_output	<output_root>.h5ad	Output path for the generated .h5ad file.
write_output_manifest	False	Writes <output_root>.outputManifest.json, an ordered diagnostic inventory of output status, paths, data links, and any pipeline failure.

Cell-Quality Inclusion Flags

If none of these flags are provided, the pipeline defaults to including only HQ_HI.

The amplicon score is the fraction of usable first-pass amplicons meeting amplicon_score_min_reads_per_amplicon. A barcode is high score when it has at least ceil(amplicon_score_min_covered_fraction × usable amplicons) supported amplicons. Reads beyond the support threshold at one amplicon do not increase its contribution, so isolated amplification jackpots cannot compensate for missing coverage elsewhere in the panel. High versus low depth remains a separate classification based on amplicon_score_max_barcode_rank.

The .amplicon_score.txt table reports Amplicon Score on a 0–1 scale together with Supported Amplicons, Usable Amplicons, total read count, barcode rank, and the four-way quality classification. It is regenerated on every run so changed scoring settings cannot silently reuse stale classifications.

Key	Meaning
include_high_score_high_depth	Include high-score, high-depth cells (HQ_HI).
include_high_score_low_depth	Include high-score, low-depth cells (HQ_LO).
include_low_score_high_depth	Include low-score, high-depth cells (LQ_HI).
include_low_score_low_depth	Include low-score, low-depth cells (LQ_LO).

Editing-Rate Confidence Intervals

By default, CRISPRSCope resamples cells with replacement and computes pointwise percentile-bootstrap intervals from the first-pass inferred allele percentages in editingSummary.txt. Set write_editing_rate_ci to False to disable this analysis. Calls with missing modification percentages or coverage below min_reads_per_amplicon_per_cell are excluded independently for each amplicon.

The output reports estimates for each amplicon from:

• AllCells: all analyzable cells with an eligible first-pass call
• InGroup: eligible cells in the quality categories enabled by the include_* settings
• OutGroup: every other eligible cell
• the InGroup-minus-AllCells and InGroup-minus-OutGroup differences
• a coverage-controlled InGroup-minus-OutGroup difference

For each amplicon, CRISPRSCope first permutes InGroup labels among AllCells without replacement while preserving the observed InGroup size. This unconditional two-sided test asks whether the InGroup behaves differently from a random same-sized subset. The exact permutation draws used for the p-value are also written to .editingRateUnconditionalPermutationSimulations.txt, summarized in .editingRateUnconditionalPermutation.txt, and shown in .12_EditingRateUnconditionalPermutation.{png,pdf} for every estimable amplicon.

The same draws are also shown in .13_EditingRateObservedCenteredPermutationSwarm.{png,pdf}. Each point is a simulated InGroup-sized subset mean shown relative to that amplicon's observed InGroup mean, in percentage points; the dashed zero line marks the observed editing rate. This is a second view of the existing simulation output, not an additional resampling procedure.

The coverage-controlled follow-up runs for every testable amplicon. Read counts through editing_rate_ci_coverage_exact_max_reads define exact strata; higher counts are grouped into consecutive bins of editing_rate_ci_coverage_bin_width_reads. Labels are permuted only within strata containing both InGroup and OutGroup cells. The adjusted effect is an information-weighted average of the within-stratum InGroup-minus-OutGroup differences. Cells in single-cohort coverage strata remain in the unconditional estimates but cannot contribute to the controlled effect; common-support counts and retained percentages are reported explicitly. The table also reports common-depth standardized InGroup and OutGroup means using the same normalized overlap weights; their difference equals the coverage-adjusted effect. A separate within-stratum bootstrap supplies the adjusted effect's confidence interval.

The unconditional and controlled permutation p-values receive separate Benjamini-Hochberg adjustments across all testable amplicons. The confidence-interval figure and optional editing-stability figure are filtered using the coverage-controlled adjusted p-value at or below 0.05, while the raw-versus-adjusted comparison figure and full output tables retain all estimable amplicons. If no amplicon passes the controlled threshold, the significance-filtered figures are omitted but the comparison figure is retained when possible.

These intervals and significance tests quantify cell-sampling and cell-selection behavior within the current run. The controlled effect applies only to coverage ranges represented in both populations. It does not represent uncertainty across biological replicates or establish a biological or causal effect of cell-quality selection.

Editing-Rate Cell-Depth Stability

Set write_editing_rate_depth_stability to True to request this optional detailed analysis; it is disabled by default. CRISPRSCope then repeatedly downsamples eligible cells without replacement, independently for AllCells and InGroup. Requested percentages are applied to each amplicon's eligible cohort, so the actual number of sampled cells is reported for every result.

Within each iteration, the percentage levels are nested: one random ordering of eligible cells supplies the first 10%, 25%, 50%, 75%, and 90%. The output reports the median editing rate, a central interval controlled by editing_rate_ci_confidence_level, and absolute deviations from the full-cohort estimate. An exact 100% reference is appended automatically. Random sampling uses editing_rate_ci_seed, making identical inputs and settings reproducible across serial and parallel runs.

Plot 14 reports percentage-point deviations for coverage-controlled significant amplicons with a usable cohort and orders them by the full InGroup editing rate, highest first. If no amplicon passes the coverage-controlled threshold, the table is retained and plot 14 is omitted.

The stability bands answer how much the inferred editing rate changes as cells from this run are retained or removed. They are finite-cohort downsampling diagnostics, not confidence intervals across biological replicates.

h5ad Zygosity Parameters

These parameters control how the .h5ad export encodes zygosity calls.

Key	Default
h5ad_wt_max_mod_pct	20.0
h5ad_het_max_mod_pct	80.0
h5ad_hom_min_mod_pct	80.0
h5ad_compound_het_min_allele2_pct	20.0

Expected Outputs

Given output_root = results/demo_run, you should expect outputs such as:

results/demo_run.html
results/demo_run.log
results/demo_run.seq_by_amplicon/
results/demo_run.crispresso/
results/demo_run.crispresso.filtered/
results/demo_run.amplicon_score.txt
results/demo_run.filteredEditingSummary.txt
results/demo_run.filteredEditingSummaryPseudobulk.txt
results/demo_run.editingRateConfidenceIntervals.txt
results/demo_run.editingRateUnconditionalPermutation.txt
results/demo_run.editingRateUnconditionalPermutationSimulations.txt
results/demo_run.10_EditingRateConfidenceIntervals.{png,pdf}
results/demo_run.11_EditingRateCoverageAdjustedEffects.{png,pdf}
results/demo_run.12_EditingRateUnconditionalPermutation.{png,pdf}
results/demo_run.13_EditingRateObservedCenteredPermutationSwarm.{png,pdf}
results/demo_run.h5ad

When write_output_manifest=True, CRISPRSCope also writes results/demo_run.outputManifest.json. This compact diagnostic inventory records each declared final artifact's path and lifecycle status, linked data artifacts, intermediate-directory summaries, and the active stage/error if a run fails.

When write_editing_rate_depth_stability=True, the additional detailed outputs are:

results/demo_run.editingRateDepthStability.txt
results/demo_run.14_EditingRateDepthStability.{png,pdf}

The exact set of plot PDFs, PNGs, and intermediate files depends on settings and on whether intermediate files are retained.

Additional Notes

• The pipeline requires external command-line tools, especially bowtie2 and CRISPResso2.
• The main workflow is designed for Linux-like environments such as Linux, WSL, or an HPC cluster.
• The settings file is strict about format: each non-comment line must contain exactly one key and one value separated by a tab.
• Multiple FASTQ pairs can be analyzed together by passing comma-separated file lists in r1 and r2.