SeqTrainer plasmid annotation

The annotation command slides a fixed-size window across a plasmid, scores each window, and writes predicted features separately from known features. These are model predictions, not experimentally confirmed promoters.

• You want to annotate an existing GenBank plasmid with predicted promoter features.
• You have a completed benchmark checkpoint and the matching benchmark manifest.
• You want a quick dummy smoke test before doing a heavier real scan.

• You only have a BenchLab plan and no trained checkpoint yet.
• You need dummy output to represent biological evidence.
• You need SBOL export from the annotation-mvp branch; use the SBOL export branch for that workflow.

• A GenBank plasmid file
• A compatible trained model checkpoint
• The benchmark manifest.json
• Python with SeqTrainer installed
• Biopython
• PyTorch and Transformers for DNABERT2
• Enough local, Colab, or HPC compute for the selected scan

SeqTrainer runs in Python on your machine, in Colab, or on HPC. A CPU smoke check can confirm the command path, but dense DNABERT2 scans are slow on Windows CPU and are better suited to GPU or HPC environments.

Dummy mode checks only whether the GenBank reading and output-writing workflow works. It is not a biological model.

seqtrainer annotate promoters input.gb \
  --model-family dummy \
  --threshold 0.80 \
  --window-size 300 \
  --step-size 25 \
  --scan-both-strands \
  --output outputs/annotations/dummy_annotated.gb \
  --predictions-csv outputs/annotations/dummy_predictions.csv \
  --manifest outputs/annotations/dummy_manifest.json

seqtrainer annotate promoters input.gb `
  --model-family dummy `
  --threshold 0.80 `
  --window-size 300 `
  --step-size 25 `
  --scan-both-strands `
  --output outputs\annotations\dummy_annotated.gb `
  --predictions-csv outputs\annotations\dummy_predictions.csv `
  --manifest outputs\annotations\dummy_manifest.json

Expected files: dummy_annotated.gb, dummy_predictions.csv, and dummy_manifest.json.

Use a real checkpoint and manifest from a completed benchmark. The manifest's validation-selected threshold is the default provenance source.

seqtrainer annotate promoters input.gb \
  --model-family dnabert2 \
  --checkpoint outputs/benchmarks/dnabert2/checkpoints/best_model.pt \
  --benchmark-manifest outputs/benchmarks/dnabert2/manifest.json \
  --step-size 25 \
  --scan-both-strands \
  --output outputs/annotations/annotated_plasmid.gb \
  --predictions-csv outputs/annotations/predictions.csv \
  --manifest outputs/annotations/annotation_manifest.json

input.gb

The plasmid input.

--model-family

The selected predictor.

--checkpoint

The trained weights.

--benchmark-manifest

Benchmark settings and threshold provenance.

--step-size

The distance between scanned windows.

--scan-both-strands

Scan forward and reverse strands.

--output

The annotated GenBank result.

--predictions-csv

All scored windows and their coordinates.

--manifest

Annotation provenance and warnings.

The annotation-mvp branch documents the core GenBank/CSV/manifest annotation workflow. The annotation-sbol3-labeled-promoters branch documents validated SBOL export.

git checkout annotation-sbol3-labeled-promoters

seqtrainer annotate promoters input.gb \
  --model-family dnabert2 \
  --checkpoint outputs/benchmarks/dnabert2/checkpoints/best_model.pt \
  --benchmark-manifest outputs/benchmarks/dnabert2/manifest.json \
  --output outputs/annotations/annotated_plasmid.gb \
  --predictions-csv outputs/annotations/predictions.csv \
  --manifest outputs/annotations/annotation_manifest.json \
  --sbol-output outputs/annotations/annotated.nt \
  --sbol2-output outputs/annotations/annotated_sbol2.rdf

• annotated.nt: canonical SBOL3 N-Triples machine-exchange output.
• annotated_sbol2.rdf: optional SBOL2 RDF/XML compatibility output intended for SBOL Canvas.
• sbol_validation.json: saved validation diagnostics for the SBOL export.

• Annotated GenBank: original features plus predicted promoter features.
• Predictions CSV: coordinates, strand, sequence window, score, threshold result, and overlap information.
• Annotation manifest: model, checkpoint, threshold source, input, output, settings, timestamp, warnings, and provenance.

• The annotated GenBank file still contains the original plasmid features.
• The predictions CSV contains scored windows, coordinates, strand, score, and threshold result.
• The manifest records the checkpoint, benchmark manifest, threshold source, warnings, and command settings.
• For SBOL export, validation diagnostics are written and invalid SBOL fails locally.

• A checkpoint without its matching manifest is not enough for a trustworthy annotation run.
• Dummy mode can create files but does not produce scientific predictions.
• A coarse CPU smoke scan is not the same as a dense scientific scan.
• Canvas compatibility requires the optional SBOL2 .rdf output, not only the SBOL3 .nt file.

Review the GenBank and CSV outputs first. If SBOL output was created, validate the .nt or .rdf file with SBOL Validator. Use the .rdf compatibility file when moving to SBOL Canvas.