DotMatch Documentation

Cinematic DotMatch workflow: sequencing reads flow through a precise known-target matching gate into count matrices, demultiplexed barcode lanes, QC panels, and visible ambiguity diagnostics.

DotMatch is a deterministic command-line and Python toolkit for known-target short-DNA assignment. It is designed for computational biologists and bioinformaticians who already have a table of expected sequences and need to count, demultiplex, audit, or diagnose reads without hiding ambiguous cases.

Use DotMatch when the biological question is:

Which known guide, barcode, primer, feature tag, adapter, or panel target did this read contain?

DotMatch is intentionally narrower than a genome aligner, basecaller, UMI pipeline, or screen-level statistics package. It works on extracted short windows and known target lists. That narrow scope is what makes its assignment contract easy to inspect: each read is reported as unique, ambiguous, none, or invalid.

Evidence boundary: performance statements are scoped to the benchmark reports and readiness gates in DotMatch Evidence Notes. The strongest current evidence is native fixed-window indexed assignment, public CRISPR guide-counting comparisons, and checked public inline-barcode lanes; broader alignment, demultiplexing, screen-analysis, or BCL replacement claims need their own gates before they are public claims.

Start Here

New evaluators should begin with Getting Started.
Use Command Reference when choosing the right namespace or compatibility entrypoint.
CRISPR teams can follow the first-run CRISPR guide-counting tutorial.
Labs evaluating scientific claims should read Trust, Scope, and Evidence.
Workflow and pipeline authors should use the public output schemas.
Bioinformatics teams evaluating package maturity, workflow fit, and current public limitations should read the Bioinformatics Evaluation Packet.
External reviewers should use the External Review Packet, the Integration Target Tracker, and the DotMatch Evaluation Protocol for a structured technical review.
Maintainers can verify these reviewer materials with make reviewer-readiness-ready, which checks the Reviewer Readiness Record.
Industry evaluators and maintainers should use the Workflow Integration Kit to route citations, evaluations, and workflow submissions.
Maintainers pushing the next adoption layer should use the Workflow Integration Roadmap and the checked workflow-integration-plan.json tracker.
Teams evaluating the open-core boundary should read Commercial Boundary and Evidence Packet v1.

Core Ideas

DotMatch compares a fixed read window with a known target table under explicit edit-distance rules. By default, a read is counted only when exactly one target falls inside the configured radius. If several targets are compatible, the read is reported as ambiguous rather than assigned by accident.

This behavior matters in real assays. Unsafe one-mismatch correction, shifted barcode positions, duplicate targets, low-quality rescued bases, and ambiguous near-neighbors can all create plausible but wrong counts. DotMatch makes those states visible in TSV, JSON, and HTML reports so results can be reviewed by people and consumed by workflow systems.

User Guide

Reference