DotMatch CRISPR Count QC

DotMatch CRISPR QC evaluates guide-counting and representation diagnostics for a pooled CRISPR screen. It does not replace MAGeCK, BAGEL, drugZ, CERES, CRISPResso2, or other downstream screen/editing analysis methods. Its job is narrower: help detect likely FASTQ-to-guide counting configuration problems, surface guide representation issues, and make suspicious samples visible before downstream statistics.

Command

dotmatch crispr qc \
  --counts counts.mageck.tsv \
  --sample-qc sample_qc.tsv \
  --library guides.csv \
  --out crispr_qc.json \
  --summary-tsv crispr_qc.summary.tsv \
  --report crispr_qc.html

dotmatch assay run writes these CRISPR QC artifacts automatically for mode = "count" and assay_type = "crispr".

The legacy-compatible alias dotmatch crispr-qc runs the same QC command.

CRISPR-First Workflow

dotmatch crispr infer \
  --library guides.csv \
  --reads sample_R1.fastq.gz \
  --out assay.toml \
  --report inference_report.json

dotmatch crispr plan assay.toml
dotmatch crispr run assay.toml

These commands are thin wrappers over AssaySpec so the CRISPR interface and the general workflow layer produce the same artifacts and validation behavior.

Metrics

The report computes count-matrix representation metrics directly from the count matrix instead of trusting precomputed values:

  • total guide counts per sample;

  • guide coverage and zero-count guide fraction;

  • Gini index over guide counts;

  • fraction of total assigned guide counts in the top 1% of guides;

  • sample assignment, ambiguity, no-match, and invalid rates when sample_qc.tsv is provided;

  • pairwise sample Pearson correlation on log2(count + 1);

  • pairwise Spearman correlation on raw guide counts;

  • duplicate guide IDs and duplicate guide sequences;

  • duplicate guide pairs and guide pairs within one edit;

  • non-ACGT guide sequences.

When sample_qc.tsv is omitted, assignment, ambiguity, no-match, and invalid rates are not evaluated and the report records a review warning. When the guide library is omitted, duplicate/collision/sequence-content checks are not evaluated and the report records a review warning.

For --k 2 or higher, CRISPR QC still reports duplicate/one-edit guide collisions only and records safe_for_k = null in the library summary. Use dotmatch audit --audit-mode exact for target-collision auditing at larger radii. Exact audit reports safe_at_hamming_k2 and safe_at_hamming_k3 for same-length Hamming guide-count libraries; fast audit reports those fields as not computed.

Conservative Review Thresholds

DotMatch emits review warnings when any sample crosses these defaults:

assignment_rate < 0.80
ambiguous_rate > 0.05
no_match_rate > 0.15
invalid_rate > 0.02
coverage_fraction < 0.90
zero_count_fraction > 0.10
gini_index > 0.50
top_1pct_fraction > 0.30
pairwise_sample_pearson < 0.80

These are diagnostic thresholds, not biological pass/fail laws. Screens differ by library, cell model, selection pressure, PCR depth, and sampling strategy. The report is deliberately conservative so suspicious guide-counting or sample representation problems are reviewed before downstream modeling. qc_status = "pass" means no configured DotMatch QC threshold was crossed; it does not certify screen quality or biological success.

Scientific Boundary

CRISPR QC provides diagnostics for the counting layer. It does not prove that a count table is biologically correct, call enriched or depleted genes, infer essentiality, quantify editing outcomes, evaluate off-target biology, or decide whether a screen is biologically successful. Use MAGeCK-style or other screen-analysis tools for hit calling and CRISPResso2-style tools for amplicon editing outcomes.