1. Compare counts
Exact and Radius k=1 both assign three reads. Their guide counts disagree.
Assignment sensitivity
Compare exact, radius-one Hamming and best-distance Hamming assignments on a nine-read synthetic dataset.
The report uses results computed by the native matcher. The viewer is available in the source repository; published CLI 0.5.0 still writes the static report.
Using the example report
2. Select guide_A
Its counts are 1, 0 and 1. Inspect how the matching rules account for the difference.
3. Load read decisions
From the downloaded example, attach bundle/read_changes.tsv. Its identity is checked locally before any records appear.
The report stays on your machine. A matching checksum is not biological validation.
Example results
This synthetic fixture contains close target sequences, a duplicate sequence with a distinct ID, substitutions, a literal N, an unmatched read and a short read. The values below are generated with DotMatch’s native Hamming matcher and checked in the test suite.
| Policy | Unique | Ambiguous | Unmatched | Invalid |
|---|---|---|---|---|
| Exact | 3 | 1 | 4 | 1 |
| Radius one | 3 | 4 | 1 | 1 |
| Best distance, k=1 | 5 | 2 | 1 | 1 |
Exact and radius-one each produce three unique assignments. But 5 reads change outcome somewhere across the three policies. Equal totals do not establish equivalent count matrices—or equivalent read assignments.
| Read | Exact | Radius one | Best distance, k=1 |
|---|---|---|---|
| exact_near_a | guide_A | ambiguous | guide_A |
| exact_near_b | guide_B | ambiguous | guide_B |
| two_candidates | none | ambiguous | ambiguous |
| exact_isolated | guide_C | guide_C | guide_C |
| one_mismatch | none | guide_C | guide_C |
| unmatched | none | none | none |
| short | invalid | invalid | invalid |
| duplicate_target | ambiguous | ambiguous | ambiguous |
| literal_n | none | guide_C | guide_C |
Matching rules
Exact
Count a read only when exactly one target has the same sequence. Duplicate sequences under distinct IDs remain ambiguous.
Radius one
Count only when one target is within one substitution. An exact read can become ambiguous when another target is a single substitution away.
Best distance, k=1
Count when one target is nearest, allowing at most one substitution. Exact matches beat one-mismatch alternatives; equal-distance ties remain ambiguous.
None of these rules establishes a read’s true biological origin. This is a software and method-selection example, not an accuracy benchmark or an automatic recommendation to use a more permissive policy.
Run on local data
dotmatch sensitivity is included in published 0.5.0. It produces the count tables and a static report. The interactive viewer shown above is an unreleased upgrade, not a feature of that published wheel.
python3 -m pip install dotmatch==0.5.0
dotmatch sensitivity \
--targets guides.tsv \
--reads sample.fastq.gz \
--target-start 23 \
--target-length 20 \
--sample-label sample_1 \
--out-dir sensitivity/Open sensitivity/report.html. The bundle contains three raw count tables, per-guide deltas, state transitions, sample QC, input and artifact checksums, and a machine-readable summary. Add --write-read-changes to record changed read IDs and calls without copying raw sequences.
Open an existing run in the interactive viewer
From a current source checkout, the standard-library renderer opens a completed v1 bundle without installing the native engine or rerunning your reads. The destination must be a new file; your original analysis is unchanged.
python3 python/dotmatch/sensitivity_review.py --bundle sensitivity/ --out review.htmlThe implementation reuses one native index and reads the FASTQ once. It compares the same fixed windows and does not change your baseline analysis, infer offsets or select an assignment policy.
Evaluating this on a real workflow? Share a de-identified result or reproducible discrepancy. Do not post private reads, sample identifiers or unpublished libraries.