DotMatch

DotMatch assigns short FASTQ read windows to a known list of DNA sequences. It is useful when you already know the guides, barcodes, feature tags, primers, or other targets that may be present and want every read reported as a unique match, an ambiguous match, unmatched, or invalid.

CI PyPI Documentation Bioconda License DOI

Documentation · Getting started · Command reference · Examples · Citation

FASTQ reads and a target table are compared at a fixed read window. DotMatch writes counts, split FASTQs, QC tables, and reports.

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.

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.

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.

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

Outcome Meaning
unique Exactly one target is compatible.
ambiguous More than one target is compatible.
none No target is within the selected distance.
invalid The requested read window could not be extracted.

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

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.

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 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

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.

Project links

Data verified by PyPI on Jul 17, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.2.2)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for dnncha from gravatar.com dnncha

Credits

Author: Donncha O'Toole

GitHub Statistics

Data verified by PyPI on Jul 17, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

Apache-2.0
View SPDX License List

Requires

Python >=3.9

Provides Extra

pandas anndata polars multiqc dev

Tags

bioinformatics computational biology CRISPR FASTQ known-target assignment feature barcodes sequencing QC barcode demultiplexing edit distance

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

dotmatch-0.2.1.tar.gz (228.5 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

dotmatch-0.2.1-py3-none-musllinux_1_2_x86_64.whl (316.4 kB view details)

Uploaded Python 3musllinux: musl 1.2+ x86-64

dotmatch-0.2.1-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (312.1 kB view details)

Uploaded Python 3manylinux: glibc 2.17+ x86-64manylinux: glibc 2.28+ x86-64

dotmatch-0.2.1-py3-none-macosx_11_0_universal2.whl (422.5 kB view details)

Uploaded Python 3macOS 11.0+ universal2 (ARM64, x86-64)

File details

Details for the file dotmatch-0.2.1.tar.gz.

File metadata

  • Download URL: dotmatch-0.2.1.tar.gz
  • Upload date:
  • Size: 228.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for dotmatch-0.2.1.tar.gz
Algorithm Hash digest
SHA256 f597371b3d7043605618d7fd9a008114d8355b6d95322047b6808c8dfcaa0332
MD5 03e08a18fdc2852d18e75b73d46ee055
BLAKE2b-256 53a3d0cb543ec17c52bee85c7727f53993ac13a2c0e07962e243efb14fb37e5f

See more details on using hashes here.

Provenance

The following attestation bundles were made for dotmatch-0.2.1.tar.gz:

Publisher: release.yml on dnncha/dotmatch

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file dotmatch-0.2.1-py3-none-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for dotmatch-0.2.1-py3-none-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 05314cc88af7aa19218ddc4e2db33c3ae9e134ac4d63e32085143e96973d63db
MD5 f14541bdceca6db86e4d34811d91507e
BLAKE2b-256 fdd77a83517d7f7042c7fd39d3e358e782147b827dcd54dd306ca8ffa78c18c2

See more details on using hashes here.

Provenance

The following attestation bundles were made for dotmatch-0.2.1-py3-none-musllinux_1_2_x86_64.whl:

Publisher: release.yml on dnncha/dotmatch

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file dotmatch-0.2.1-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for dotmatch-0.2.1-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 15ca7dd82424a7b74ce2dc45db3c35de2c38a53b145c4d5a8b187aa66b84dcf3
MD5 cf78c466b7fd47e04eb915ae5b129f6b
BLAKE2b-256 5ef861a8514f0661b520b8ea087b467a3ba2845019b0ae3a62802c1b53d4e81d

See more details on using hashes here.

Provenance

The following attestation bundles were made for dotmatch-0.2.1-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl:

Publisher: release.yml on dnncha/dotmatch

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file dotmatch-0.2.1-py3-none-macosx_11_0_universal2.whl.

File metadata

File hashes

Hashes for dotmatch-0.2.1-py3-none-macosx_11_0_universal2.whl
Algorithm Hash digest
SHA256 0379cce8566618e25d81cf05b36650db7c0cfed58b2663a842ff430c745deaba
MD5 107bebd4f88165a8b2b1e0be5138ad7b
BLAKE2b-256 473fdb6a859363b5629a758e48b5ac1a2e4e716c60ce3cbeb5ffc9d128f14458

See more details on using hashes here.

Provenance

The following attestation bundles were made for dotmatch-0.2.1-py3-none-macosx_11_0_universal2.whl:

Publisher: release.yml on dnncha/dotmatch

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.2.2

4 files

This release

0.2.1 This release

4 files

0.2.0

4 files

0.1.9

4 files

0.1.8

4 files

0.1.7

4 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page