# DotMatch

> DotMatch is an Apache-2.0 command-line and Python tool for deterministic fixed-window assignment of FASTQ reads to a finite list of known short DNA targets. Use it for CRISPR guide counting, inline barcode demultiplexing, per-read feature-barcode or guide-capture assignment, barcode panel design, and other known-target matching. It is not a genome aligner, basecaller, UMI or cell quantifier, variant caller, or downstream screen-statistics package.

Install the current public release with `python3 -m pip install dotmatch==0.4.1` and verify it with `dotmatch --version`. DotMatch 0.4 adds `dotmatch agent tools --json` and six structured, local-only tools. Use `dotmatch capabilities --json` or the public capability manifest for task routing. Coordinates are zero-based. Count only `unique` assignments; `ambiguous`, `none`, and `invalid` remain separate. Audit a target list before enabling mismatch correction.

## Agent start

- [Agent guide](https://raw.githubusercontent.com/dnncha/dotmatch/main/docs/agent-guide.md): Task-to-command routing, copy-paste workflows, limitations, and recovery steps.
- [Full agent reference](https://dnncha.github.io/dotmatch/llms-full.txt): Self-contained install, routing, input, output, and safety reference.
- [Capability manifest](https://dnncha.github.io/dotmatch/agent-capabilities.json): Versioned JSON task routing for agents and workflow tools.
- [Capability schema](https://dnncha.github.io/dotmatch/agent-capabilities.schema.json): JSON Schema for the capability manifest.
- [Agent tool contract](https://dnncha.github.io/dotmatch/agent-tools.json): Six structured local execution tools and their safety policy.
- [Agent tool schema](https://dnncha.github.io/dotmatch/agent-tools.schema.json): JSON Schema for tool inputs and the stable result envelope.
- [CRISPR agent route](https://raw.githubusercontent.com/dnncha/dotmatch/main/docs/agent-crispr.md): Exact inputs, outputs, limits, and copyable JSON starts.
- [Perturb-seq agent route](https://raw.githubusercontent.com/dnncha/dotmatch/main/docs/agent-perturb-seq.md): Direct-guide assignment route and evidence boundary.

## Core documentation

- [Getting started](https://raw.githubusercontent.com/dnncha/dotmatch/main/docs/getting-started.md): Installation and first count or demultiplexing run.
- [Command reference](https://raw.githubusercontent.com/dnncha/dotmatch/main/docs/command-reference.md): Stable command map and supported correction radii.
- [Output schemas](https://raw.githubusercontent.com/dnncha/dotmatch/main/docs/schemas.md): TSV and JSON file contracts.
- [Scope and limitations](https://raw.githubusercontent.com/dnncha/dotmatch/main/docs/trust-and-scope.md): Tested scope and explicit non-goals.
- [Scientific claims](https://raw.githubusercontent.com/dnncha/dotmatch/main/docs/scientific-claims.md): Claim-by-claim evidence and limitations.

## Examples

- [CRISPR guide counting](https://raw.githubusercontent.com/dnncha/dotmatch/main/examples/crispr_guides/README.md): Checked MAGeCK/Yusa workflow and expected outputs.
- [CRISPR first run](https://raw.githubusercontent.com/dnncha/dotmatch/main/docs/tutorials/crispr-count-first-run.md): Direct and reviewable project routes.
- [Feature barcode and guide capture](https://raw.githubusercontent.com/dnncha/dotmatch/main/docs/tutorials/scverse-perturb-seq.md): Narrow per-read assignment route with cell and UMI limitations.
- [Barcode panel design](https://raw.githubusercontent.com/dnncha/dotmatch/main/docs/barcode-panel-design.md): Design, audit, simulate, and export barcode panels.

## Optional

- [Repository](https://github.com/dnncha/dotmatch): Source, tests, issues, and releases.
- [PyPI](https://pypi.org/project/dotmatch/): Published Python package metadata and files.
- [Citation](https://raw.githubusercontent.com/dnncha/dotmatch/main/CITATION.cff): Release citation metadata.