DotMatch Barcode Panel Design

DotMatch does not merely design barcodes. It designs barcode panels that come with proof of how they will behave during assignment.

dotmatch panel is for barcode design for known-target assignment. It is not general genome alignment, not UMI entropy generation, not basecalling, and not a replacement for downstream biological interpretation.

Commands

dotmatch panel design --n 96 --length 16 --preset illumina-inline-strict --seed 42 --out-dir panel/
dotmatch panel check panel/barcodes.tsv --k 1 --metric hamming --out-dir panel_check/
dotmatch panel optimize vendor_barcodes.tsv --n 24 --out-dir optimized/
dotmatch panel simulate panel/barcodes.tsv --reads 1000000 --out-dir simulation/
dotmatch panel layout panel/barcodes.tsv --plate 96 --out plate_layout.tsv
dotmatch panel export panel/barcodes.tsv --format illumina-samplesheet --out-dir sample_sheet_templates/

Every designed panel includes a machine-checkable safety certificate:

• panel_summary.json

• target_safety.tsv

• collision_pairs.tsv

• ambiguous_error_spheres.tsv

• reverse_complement_warnings.tsv

• prefix_collisions.tsv

• suffix_collisions.tsv

• cycle_balance.tsv

• context_risk.tsv

• flanked_sequences.tsv

• panel_report.html

target_safety.tsv includes a per-barcode safe_hamming_correction_radius field. This is the largest Hamming correction radius, up to the certificate’s exact enumeration limit, for which that specific target has no ambiguous or silent-assignment variants under DotMatch radius semantics.

Safety Semantics

Panel safety is checked under DotMatch assignment outcomes: unique, ambiguous, none, and invalid, using the same default radius ambiguity policy as demux and counting.

DotMatch never marks a panel safe for a configured correction radius when any query inside the checked error sphere maps ambiguously. If ambiguity_policy = "best" is selected for compatibility, the report also includes silent assignment risk: possible errors from one barcode that would be assigned uniquely to another barcode.

The v1 certificate exhaustively enumerates configured error spheres up to k=2. Requests above k=2 are refused rather than downgraded to a partial proof.

For Hamming distance, a minimum pairwise distance d gives substitution correction up to floor((d - 1) / 2) and detection up to d - 1. The certificate still matters because DotMatch checks the exact assignment rules that will later be used by demux/counting.

Simulation is a stochastic stress test, not the certificate. The default source distribution is uniform across panel records and the simple error model uses explicit substitution, insertion, and deletion probabilities in [0, 1]. simulation_summary.json records the source distribution, the false-assignment confidence method, and a one-sided 95% upper bound; zero observed false assignments therefore still produce a positive upper bound rather than proving zero risk.

Outputs From panel design

panel design writes:

• barcodes.tsv

• design_report.json

• design_trace.tsv

• panel_check/

• assignment_safety.tsv

• collision_pairs.tsv

• ambiguous_error_spheres.tsv

• flanked_sequences.tsv

• plate_layout.tsv

• plate_layout.svg

• neighbor_distance.tsv

• lab_picklist.csv

• sample_sheet_templates/

• report.html

• README_FOR_LAB.md

The barcode table is intentionally auditable rather than a two-column list. It includes GC, homopolymer length, nearest-neighbor distances, reverse-complement collision flags, self-complement score, status, warnings, and the certified DotMatch command.

Presets

Preset	Intended use	Default length	Core guarantee
strict-24x12	small panels	12	high spacing
strict-96x16	general inline barcodes	16	safe one-edit correction target
strict-384x20	large panels	20	high capacity
illumina-inline-96	fixed-window inline demux	10	Hamming-first
illumina-dual-384	paired i7/i5 indexing	10+10	pair-aware safety
nanopore-indel-robust-24	noisy long-read contexts	18	Levenshtein/seqlev spacing
ont-rna004-signal-12	experimental raw-signal candidate narrowing	16	symbolic safety first

Signal-aware output is experimental and cannot override symbolic safety.