DotMatch AssaySpec v1

AssaySpec is a TOML workflow layer for fixed-window known-target assays. It does not replace the native matching/counting code; it validates a declarative spec, writes reproducible run files, prints the native commands it will execute, and records an assay_manifest.json beside the outputs.

AssaySpec is part of the Python package surface. PyPI/source installs and the Python-enabled Bioconda recipe expose dotmatch assay ... through the standard dotmatch console script.

Commands

dotmatch assay new crispr --library guides.csv --reads-dir fastqs/ --out crispr_screen/
dotmatch assay start assay.toml
dotmatch assay check assay.toml
dotmatch assay optimize assay.toml
dotmatch assay plan assay.toml
dotmatch assay run assay.toml
dotmatch assay init --template crispr --out assay.toml
dotmatch assay infer --mode count --assay-type crispr --targets guides.csv --reads sample.fastq.gz --out assay.toml --report inference_report.json
dotmatch assay autopsy assay.toml --out-dir autopsy/

start is the default production entrypoint: it runs check, then run, and prints the reliability verdict plus paths to reliability_report.html and assay_fixes.tsv. Exit codes follow the verdict: 0 for passed, 1 for needs_review, and 2 for failed or blocked.

Templates are:

  • crispr

  • feature-barcode

  • inline-barcode-count

  • inline-barcode-demux

  • amplicon-panel

  • oligo-adapter

  • pair-count

optimize reads the spec and writes a benchmark-informed CPU/GPU backend recommendation without changing the assignment authority. plan is a dry run: it prints deterministic native commands and does not create the output directory. The plan also lists the reliability artifacts that a run or check will write. check validates the spec and writes preflight reliability artifacts without running read assignment. run creates the output directory, writes generated files, runs target audit first, runs the compiled native workflow, and records command exit codes and warnings in assay_manifest.json. It also writes assay_report.html as the primary workflow report and assay_manifest.summary.tsv for workflow systems and MultiQC custom content. Production runs also write methods.md, CITATION.bib, and software_versions.yml for lab notebooks, workflow submissions, and report handoff.

new scaffolds a reviewable project directory from a target or barcode table and a directory of FASTQ files. It stages inputs under inputs/ and reads/, infers the extract window from the first sample, writes assay.toml, inference_report.json, samples.generated.tsv, README.md, and run.sh. Low-confidence inference writes status = "draft" until a scientist promotes the spec to ready.

infer samples FASTQ reads, scores fixed-window candidates against the supplied target table, writes a candidate AssaySpec, and writes inference_report.json plus inference_candidates.tsv. Low-confidence inference writes status = "draft". Production runs refuse draft specs by default until a user reviews the report and changes the status to ready; this can be explicitly relaxed with [reliability] fail_on_draft_inference = false.

autopsy helps diagnose suspicious runs by wrapping native target audit and inspect-unmatched. It writes autopsy_summary.json, findings.tsv, and top_unmatched.*.tsv files. run also triggers autopsy automatically when sample QC crosses conservative thresholds.

Count Example

schema_version = 1
status = "ready"
mode = "count"
assay_type = "crispr"
targets = "guides.csv"

[[samples]]
id = "control"
fastq = "control.fastq.gz"

[[samples]]
id = "treated"
fastq = "treated.fastq.gz"

[run]
out_dir = "dotmatch_assay_out"
threads = 1

[extract]
start = 23
length = 19

[assignment]
k = 1
metric = "hamming"
ambiguity_policy = "radius"
ambiguous = "discard"

[reliability]
profile = "production"
fail_on_unsafe_targets = true
fail_on_draft_inference = true
min_assignment_rate = 0.80
max_ambiguous_rate = 0.05
max_unmatched_rate = 0.15
max_invalid_rate = 0.02
require_public_evidence_boundary = true

[backend]
mode = "auto"
allow_gpu = true

[outputs]
format = "mageck"
assignments = true
ambiguous = true
unmatched = true

Count mode writes counts.mageck.tsv for CRISPR/MAGeCK output or counts.tsv for DotMatch output, plus target_counts.long.tsv, sample_qc.tsv, summary.json, native report.html, assay_report.html, assay_manifest.json, assay_manifest.summary.tsv, methods.md, CITATION.bib, software_versions.yml, audit/, and optional row-level diagnostics. CRISPR count runs also write crispr_qc.json, crispr_qc.summary.tsv, and crispr_qc.html.

Reliability Artifacts

AssaySpec writes closed-loop reliability artifacts for check and run:

  • reliability_summary.json

  • reliability_findings.tsv

  • reliability_report.html

  • reliability_manifest.summary.tsv

reliability_summary.json records the profile, thresholds, backend authority, GPU eligibility, evidence boundary, artifact paths, and normalized findings. Findings use info, warning, error, and blocked severity. check records read-dependent QC as unavailable because no assignment has run yet. run aggregates target audit results, sample QC thresholds, autopsy findings, command failures, and assay evidence metadata.

profile = "production" fails fast after target audit if fail_on_unsafe_targets = true and the target set is unsafe at the configured radius. Runtime threshold failures are written after assignment and leave output artifacts in place for diagnosis. profile = "exploratory" records the same conditions as findings without using unsafe preflight status to stop the run.

[backend] mode = "auto" keeps CPU assignment as the production authority and records whether the assay is eligible for the experimental Metal GPU path. gpu-metal-experimental remains advisory unless an assay-specific real-workload gate validates it; DotMatch does not silently switch production assignment to GPU.

Demux And Pair Modes

Demux mode uses mode = "demux", barcodes, reads, [extract], and writes demuxed/, summary.json, optional assignments.tsv, ambiguous.fastq, and unmatched.fastq.

Pair mode uses mode = "pair-count", left_targets, right_targets, reads, [left], and [right]. It writes pair_counts.tsv, pair_summary.json, and optional pair_assignments.tsv.

Safety Policy

AssaySpec always runs native target audit before assignment. If the audit says the target set is unsafe at the configured k, the reliability profile decides whether to stop before assignment or record the risk and continue. It never changes k, target sequences, or ambiguity policy automatically; DotMatch’s explicit unique/ambiguous/none semantics remain the authority.

Templates and inferred specs default to ambiguity_policy = "radius", which keeps any read with more than one target inside the configured radius out of forced assignments. Use ambiguity_policy = "best" only when best-distance compatibility is deliberate.

Automatic autopsy uses the configured reliability thresholds for assignment, ambiguous, no-match, and invalid rates. These thresholds are recorded in assay_manifest.json.