DotMatch

CRISPR guide counts and assignment QC from FASTQ reads.

DotMatch turns FASTQ reads and a known guide library into count tables and assignment QC. Use it for CRISPR guide counting, fixed-position barcode demultiplexing, and other short-DNA assays with known targets. It runs locally on Linux and macOS and writes MAGeCK-compatible counts.

Start counting guides · Check a library in your browser · Documentation · Methods and results

What the counts mean

An assigned-read percentage cannot tell you which targets gained counts, which reads fit several targets, or whether a more permissive matching rule changed the result. DotMatch keeps those decisions inspectable.

Read outcomes are unique, ambiguous, none (unmatched), or invalid (the requested window could not be extracted). Only unique calls contribute to a target count. Choose the matching policy deliberately; a unique call is not proof of biological origin.

Keep downstream screen statistics in the workflow you already use. DotMatch is not a genome aligner, basecaller, cell/UMI pipeline or gene-level hit-calling package.

Install

Release 0.6.2 is the current DotMatch release. It includes the six dotmatch agent tools described below:

python3 -m pip install dotmatch==0.6.2
dotmatch --version

Conda and container routes:

conda create -n dotmatch -c conda-forge -c bioconda dotmatch
conda activate dotmatch

# Or use the pinned release container:
docker run --rm ghcr.io/dnncha/dotmatch:v0.6.2 --version

Bioconda and its generated BioContainers images can lag PyPI/GHCR. When a newly tagged version has not reached Bioconda yet, use PyPI or the source build. Check the installed version. The Bioconda recipe includes osx-arm64 for Apple Silicon. Review the packaging details for platform and container verification. See the installation guide for platform details, source builds and the third-party Homebrew tap. The desktop Workbench is developed separately as dotmatch-community; the commands below use the core CLI.

Try a checked first run

The packaged fixture checks expected native assignment counts without using study data or making network requests:

dotmatch demo --out-dir first-run/

Open first-run/index.html for the local review bundle. To compare existing raw-count tables, use dotmatch compare-counts.

Count a CRISPR screen

You need a guide CSV/TSV with target sequences and the FASTQ files from your screen. The first-run tutorial explains the library columns and provides a small example. Keep biological sample names distinct from sequencing filenames when preparing the library and sample configuration.

Start a new assay project:

dotmatch crispr quickstart \
  --library guides.csv \
  --fastq 'fastqs/*.fastq.gz' \
  --out crispr_screen/

This creates a draft project. Review crispr_screen/inference_report.json and assay.toml: confirm the guide window, orientation, library and sample files. After confirming the settings, change the top-level status = "draft" to status = "ready" in assay.toml, then run and review:

dotmatch assay start crispr_screen/assay.toml

# After reviewing a completed run:
dotmatch assay handoff crispr_screen/assay.toml

The handoff carries configuration, QC, methods and checksums without copying raw FASTQs. Follow the complete CRISPR tutorial for inputs, direct CLI options and count-table outputs.

Understand the effect of mismatch correction

The dotmatch sensitivity command, introduced in 0.5.0, compares exact, radius-one and best-distance Hamming assignment using the same windows in one FASTQ pass. It produces three count matrices, per-guide deltas, read-state transitions, checksums and a self-contained HTML report. It never selects a policy for you.

Run the included synthetic example from a checkout of the v0.6.2 release:

python3 -m pip install dotmatch==0.6.2
dotmatch sensitivity \
  --targets examples/assignment_sensitivity/targets.tsv \
  --reads examples/assignment_sensitivity/reads.fastq \
  --target-start 0 --target-length 20 \
  --write-read-changes --out-dir sensitivity-example

The nine-read synthetic example shows why equal assigned totals can hide different per-guide counts. Read the output contract. This is sensitivity analysis, not an estimate of biological accuracy.

Explore the interactive review example without installing anything. The example uses the public nine-read synthetic fixture. The interactive assignment review is published on the DotMatch 0.6.2 site. The installed dotmatch sensitivity command continues to write its static report. The synthetic fixture demonstrates software behavior, not biological accuracy.

Choose by task

Feature matrices require upstream cell identifiers and extracted feature windows. They do not perform cell calling, UMI deduplication or perturbation-effect analysis.

Research and reproducibility

Cheerful Duck Research publishes our bioinformatics software investigations, reproducible examples, and follow-up corrections. For DotMatch-specific methods and measurements, use the reports below and record the release and assignment policy used in your own run.

Reproduce a comparison

The benchmark reports include commands, hardware and assignment rules. Those reports cover the tested workloads; they are not universal speed or biological-accuracy guarantees.

Public CRISPR comparisons record Yusa and Brunello inputs, methods, count differences, runtime and memory. Exact, Hamming and Levenshtein results use different semantics and should be compared separately. A comparison that completed successfully is not necessarily an identical count matrix or biological validation.

The GSE146194 direct-guide-capture case study separates discovery and evaluation reads and checks per-read assignments against independent reference implementations. It does not establish guide-per-cell or perturbation-effect accuracy.

For an installation-free synthetic smoke demo, use Binder or Google Colab. For a shareable or de-identified workflow evaluation, see the public validation invitation. Do not post private reads or unpublished guide libraries.

Pipelines, Python and local agents

DotMatch provides a Python streaming API, output schemas, and workflow examples. The ecosystem status ledger distinguishes local examples from accepted upstream integrations.

The six structured agent tools are included in release 0.5.0:

dotmatch capabilities --json
dotmatch agent tools --json
dotmatch agent export-skill --target ./dotmatch-agent

They prepare, preflight, run, review and hand off local assays without accepting free-form shell commands or uploading research data. Start with the Agent guide, CRISPR agent route, or Perturb-seq agent route. Machine-readable discovery: agent-capabilities.json, agent-tools.json, and the checked contract fixture.

Citation and contributing

DotMatch is Apache-2.0 licensed. Use dotmatch citation and CITATION.cff to record the actual software version. Use the methods and citation guide to cite the actual release and configuration used. Improvements, discrepancy fixtures and reproducible bug reports are welcome: contributing guide.