DotMatch

DotMatch is a deterministic CRISPR guide-counting and known-target short-DNA assignment tool. It assigns short FASTQ read windows to a known list of DNA sequences and reports every read as a unique match, an ambiguous match, unmatched, or invalid. It also supports barcodes, feature tags, primers, and other known targets.

Documentation · Getting started · Agent guide · CRISPR agent route · Perturb-seq agent route · Command reference · Capability JSON · Agent tools JSON · Checked agent fixture · Examples · Citation · Try the notebook in Binder · Try the notebook in Google Colab

Install

PyPI is the quickest route on Linux and macOS:

python3 -m pip install dotmatch
dotmatch --version

Conda users can install the current Bioconda build:

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

The Bioconda recipe supports Linux, Intel macOS, and Apple Silicon (osx-arm64). If a newly tagged version has not reached Bioconda yet, use the PyPI package or install from source.

macOS users who want the native CPU command without Python can use the third-party Homebrew tap:

brew tap dnncha/tap
brew install dnncha/tap/dotmatch
dotmatch --version

This tap is maintained outside Homebrew's official repositories and installs the native dotmatch command from a pinned release source archive. Use PyPI or Bioconda when you need the Python bindings, AssayCode, or the optional Metal backend.

For containerised workflows, the current release is also published to GHCR:

docker pull ghcr.io/dnncha/dotmatch:v0.3.1
docker run --rm ghcr.io/dnncha/dotmatch:v0.3.1 --version

The container package is useful when a workflow should pin the release without installing Python or Conda on the host.

BioContainers also publishes the Bioconda-derived image for workflow runners:

docker pull quay.io/biocontainers/dotmatch:0.2.2--py311h13f8228_1
docker run --rm quay.io/biocontainers/dotmatch:0.2.2--py311h13f8228_1 dotmatch --version

See the BioContainers package for the other Python-build tags.

Maintainers can refresh the download metrics snapshot with make download-metrics. It records provider-reported package retrievals by channel, version, platform, and Python build; it does not estimate unique users.

Choose by task

For an autonomous local workflow, inspect the installed contract first:

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

The six tools prepare, preflight, run, review, and hand off CRISPR or Perturb-seq direct-guide workflows using structured JSON only. They do not upload research data or accept free-form shell commands.

The Agent guide provides copy-paste commands, inputs, outputs, recovery steps, and evidence limits. Agents and workflow tools can read the same routes from agent-capabilities.json or the installed dotmatch capabilities --json command in DotMatch 0.3.0 and later.

The Binder and Colab notebooks run a small synthetic smoke demo without requiring a local install. They check mechanics only, not biological validation. If you work with a shareable or de-identified guide, barcode, or other fixed-target fixture, see the public validation request.

A small example

Prepare a tab-separated target file:

target_id	sequence
guide_001	ACGTACGTACGTACGTACGT
guide_002	ACGTACGTACGTACGTAGGT

Then assign a fixed 20-base window from each read:

dotmatch count \
  --targets guides.tsv \
  --reads sample_R1.fastq.gz \
  --sample-label sample_1 \
  --target-start 23 \
  --target-length 20 \
  --k 1 \
  --metric hamming \
  --out counts.tsv \
  --sample-qc sample_qc.tsv \
  --summary summary.json

DotMatch only counts a read when exactly one target is compatible under the selected matching rule. Reads that fit several targets remain visible as ambiguous instead of being assigned arbitrarily.

Try a public CRISPR dataset

After installing the published package, reproduce the checked public MAGeCK/Yusa guide-counting example from the repository:

git clone https://github.com/dnncha/dotmatch.git
cd dotmatch
python3 -m pip install dotmatch
DOTMATCH_BIN=dotmatch ./examples/crispr_guides/run.sh

This downloads a small public fixture and writes the count matrix, per-read assignments, and summary under examples/crispr_guides/output/. The example README explains how to fetch the full public data and links to the recorded CRISPR comparison report.

Reproduce the public Perturb-seq case study

The GSE146194 direct-guide-capture case study uses 32 published guide barcodes and a bounded, held-out prefix of SRR11214031:

git clone https://github.com/dnncha/dotmatch.git
cd dotmatch
make bench-perturb-seq-case-study-public
make perturb-seq-case-study-public-gate

The workflow verifies the publisher workbook, streams only the first 50,000 FASTQ records, excludes 2,000 discovery reads, and checks 48,000 evaluation reads against independent exact and exhaustive Hamming oracles. The report includes unmatched and ambiguous outcomes, hashes, commands, software versions, and resource measurements. This is per-read fixed-window guide assignment evidence; it is not guide-per-cell, UMI, expression, perturbation-effect, or speed-comparison evidence.

For a browser-based smoke demo, launch the Runnable DotMatch notebook in Binder or Google Colab. It uses a small synthetic fixture and is intended for workflow orientation, not biological validation.

What it is for

• counting CRISPR guides and writing MAGeCK-compatible count tables;
• demultiplexing fixed-position inline barcodes;
• assigning feature-barcode and guide-capture reads;
• checking primer, adapter, amplicon-panel, or whitelist sequences;
• auditing target lists before enabling mismatch correction;
• designing and checking barcode panels;
• writing TSV, JSON, FASTQ, and HTML results for pipelines and lab review.

If you work with guide-capture or perturb-seq data, the public case study above provides a checked starting point. The public validation invitation also asks for a short trial and concrete input/output feedback. Please do not post private reads or unpublished guide libraries.

If you are choosing a CRISPR guide-counting workflow, see the workflow comparison for the documented fit and scope of DotMatch, guide-counter, MAGeCK, and alignment-based alternatives.

DotMatch is not a genome aligner, basecaller, UMI pipeline, variant caller, or screen-level statistics package. It compares short read windows with a finite target list.

Read outcomes

These states appear in the assignment and QC outputs. They are not folded into the unique counts.

Common workflows

Count CRISPR guides

For a new screen, DotMatch can prepare a small assay project and infer a likely guide window for review:

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

Review crispr_screen/inference_report.json and assay.toml, then run:

dotmatch assay start crispr_screen/assay.toml

After a completed run, create a compact technical review bundle without copying raw FASTQs:

dotmatch assay handoff crispr_screen/assay.toml

The bundle includes configuration, QC, reports, methods, citation material, and checksums for declared inputs and copied outputs. See the lab evaluation and handoff guide for the review sequence and data-handling boundary.

For an explicit one-command run, use dotmatch crispr-count. The CRISPR tutorial covers both routes.

Demultiplex inline barcodes

dotmatch demux \
  --barcodes barcodes.tsv \
  --reads pooled.fastq.gz \
  --barcode-start 0 \
  --barcode-length 8 \
  --k 1 \
  --metric hamming \
  --out-dir demuxed/ \
  --summary demux.summary.json

If a run has an unexpectedly high unmatched or ambiguous rate, inspect it with:

dotmatch barcode autopsy \
  --barcodes barcodes.tsv \
  --reads pooled.fastq.gz \
  --scan-starts 0:12 \
  --k-values 0,1 \
  --out-dir autopsy/

Open autopsy/report.html first. The tables beside it record offset scans, near-neighbour barcodes, correction safety, and frequent unmatched windows.

Build a cell-by-feature matrix from extracted observations

When an upstream workflow has already extracted feature windows and attached an explicit cell identifier, DotMatch can write a sparse cells × features matrix:

dotmatch feature matrix \
  --observations feature_observations.tsv \
  --targets feature_library.tsv \
  --id-column observation_id \
  --cell-column cell_barcode \
  --sequence-column feature_seq \
  --metric hamming --k 1 \
  --out-dir feature_matrix/

The output directory contains matrix.mtx, cell and feature axes, long-form counts, per-observation assignments, per-cell QC, and a JSON summary. Only unique assignments add a matrix count. This command does not perform FASTQ pairing, cell-barcode correction, UMI deduplication, or cell calling; those upstream steps should remain documented with the observation table.

See the scverse and feature-barcode tutorial for the file contract and AnnData handoff.

Count target pairs across R1 and R2

Use pair-count when a left target and a right target are sequenced in synchronized FASTQ mates:

dotmatch pair-count \
  --left-targets r1_targets.tsv \
  --right-targets r2_targets.tsv \
  --left-reads sample_R1.fastq.gz \
  --right-reads sample_R2.fastq.gz \
  --left-start 0 --left-length 20 \
  --right-start 0 --right-length 20 \
  --k 1 --metric hamming \
  --out pair_counts.tsv \
  --summary pair_summary.json

R1 and R2 must contain the same records in the same order. DotMatch checks the canonical read identifier before assignment and records input synchronization, side-specific unmatched totals, and side-specific invalid totals in the summary.

Check a target library

Before allowing mismatch correction, check whether neighbouring targets can produce ambiguous assignments:

dotmatch audit \
  --targets guides.tsv \
  --k 1 \
  --audit-mode auto \
  --out-dir audit/

The barcode panel guide also covers panel design, optimisation, simulation, layout, and export.

Python API

import dotmatch

distance = dotmatch.distance("ACGT", "AGGT")
assert distance == 1

result = dotmatch.assign_posterior("ACGT", ["ACGT", "AGGT"], "IIII")
print(result.status)

The posterior helper is experimental and is not used by the high-throughput CLI path. The Python API documentation describes the supported streaming interfaces.

Outputs and workflow integration

Depending on the command, DotMatch writes count tables, split FASTQs, sample_qc.tsv, per-read assignments, unmatched-read tables, summary.json, and self-contained HTML reports. The formats are documented in the output schema reference.

Examples for Nextflow, nf-core, Snakemake, Galaxy, and MultiQC live under examples/workflows. The ecosystem status ledger separates local examples, open upstream submissions, accepted contributions, released integrations, and installable package-manager channels. The desktop Workbench is maintained separately in dotmatch-community.

Matching rules and performance

Hamming distance is the usual choice for fixed-length windows where only base substitutions should be considered. Levenshtein distance can also account for short insertions and deletions. The default radius policy requires a single compatible target; the optional best policy exists for compatibility with workflows that select the nearest target.

Indexed candidate generation and native distance kernels make fixed-window assignment practical for large FASTQ inputs. Benchmark results, hardware, commands, and known limitations are kept with the benchmark reports. Those reports cover the tested workloads; they are not a claim that DotMatch replaces general alignment or every demultiplexing workflow.

Documentation

• Agent guide
• Getting started
• Command reference
• AssaySpec workflows
• Lab evaluation and handoff
• CRISPR count QC
• Barcode panel design
• Output schemas
• Methods and citation
• Packaging notes

Citation

Run dotmatch citation to print the citation for the installed version. The repository also includes CITATION.cff, and release archives are deposited with Zenodo.

Development

git clone https://github.com/dnncha/dotmatch.git
cd dotmatch
make
make test

See CONTRIBUTING.md for the development setup and pull-request checks.

License

Apache-2.0. See LICENSE.