# Barcode Troubleshooting Report

DotMatch reports how fixed-window barcode reads were assigned, rejected, or flagged for review.

Speed is reported only after the comparator settings are documented.

## Decision Summary

- Inference status: `review`
- Assignment rate: `0.72492000`
- Top finding: `low_confidence_offset`
- Primary report: `report.html`

## Comparator check

Use this section with recorded comparator settings for the same barcode window, length, and correction policy.

## Offset check

Highest-scoring sampled barcode window: start=0, length=4.
Exact assignment rate at that window: 0.11283. Inference status: review.
Warning: best scanned window has a low exact assignment rate; review the barcode sheet, read orientation, and window before treating the offset as ready.

## Barcode safety audit

The audit output reports duplicate and nearby barcode pairs before one-edit correction is trusted.

## Assignment summary

Run assignment rate: 0.72492000.
Exact assignments: 11283. Corrected assignments: 61209.
Ambiguous reads: 13911 (0.13911000). Unmatched reads: 13597 (0.13597000). Invalid windows: 0.
Top failure reason: ambiguous_collision. Top unmatched sequences are written to `top_unmatched.tsv`.

### What this means

The sampled fixed-window scan found a best window, but the evidence is weak enough that the assay specification should be reviewed before production use.

### Next action

Check the barcode sheet, read side, offset, barcode length, and expected orientation; rerun inference after correcting the assay specification.

Do not rescue ambiguous reads into either sample without changing the barcode design or assignment policy.

## Findings

- review: low_confidence_offset - The sampled scan has a weak best window; the assay specification may be wrong or incomplete. Next action: Review read side, barcode start, barcode length, target sheet, and orientation before production use.
- review: low_assignment_rate - Fewer than 80% of reads were uniquely assigned under the selected fixed-window semantics. Next action: Inspect offset_scan.tsv, top_unmatched.tsv, and the barcode sheet before trusting rescued reads.
- review: high_ambiguity_rate - A material fraction of reads is compatible with more than one barcode. Next action: Do not rescue ambiguous reads into either sample without changing the barcode design or assignment policy.
- review: unsafe_one_edit_correction - At least one barcode is not safe for one-edit correction. Next action: Use k=0 or redesign/fix colliding barcodes before enabling one-edit rescue.

## Workflow handoff

Artifacts are written as stable TSV, JSON, FASTQ, HTML, and MultiQC custom-content inputs.

## QC Checklist

- Exact command provenance is recorded in `provenance.json`.
- Offset evidence is recorded in `offset_scan.tsv`.
- Barcode collision safety is recorded under `audit/` and summarized in `correction_safety.tsv`.
- Ambiguous and unmatched reads are retained when requested instead of being silently assigned.
- Benchmark notes stay tied to documented comparator settings.

## Commands

- `dotmatch audit --targets examples/barcode_demux/data/barcodes.tsv --k 1 --audit-mode auto --out-dir examples/barcode_autopsy/results/audit`
- `dotmatch demux --barcodes examples/barcode_demux/data/barcodes.tsv --reads examples/barcode_demux/data/SRR391079.subsample100000.fastq.gz --barcode-start 0 --barcode-length auto --k 1 --metric hamming --out-dir examples/barcode_autopsy/results/demuxed --summary examples/barcode_autopsy/results/summary.json --assignments examples/barcode_autopsy/results/assignments.tsv --ambiguous-out examples/barcode_autopsy/results/ambiguous.fastq --unmatched-out examples/barcode_autopsy/results/unmatched.fastq`
- `dotmatch inspect-unmatched --targets examples/barcode_demux/data/barcodes.tsv --reads examples/barcode_demux/data/SRR391079.subsample100000.fastq.gz --target-start 0 --target-length 4 --k 1 --top 100 --out examples/barcode_autopsy/results/top_unmatched.tsv`

## Artifacts

- `offset_scan.tsv`
- `audit/`
- `collision_graph.tsv`
- `correction_safety.tsv`
- `demuxed/`
- `summary.json`
- `assignments.tsv`
- `ambiguous.fastq`
- `unmatched.fastq`
- `top_unmatched.tsv`
- `sample_qc.tsv`
- `barcode_counts.tsv`
- `findings.tsv`
- `provenance.json`
- `multiqc_dotmatch_barcode_mqc.yaml`