Detailed execution reference¶

A run reads the settings saved by setup or batch setup. Use your actual YAML path below; guided setup calls it config/run.yml, while batch setup uses config/illumina.auto.yml or config/ont.auto.yml.

oncotracer check --config /absolute/path/project/config/illumina.auto.yml
oncotracer run \
  --backend conda \
  --threads 16 \
  --config /absolute/path/project/config/illumina.auto.yml

The standard CNA YAML can be executed through Conda, Docker, Singularity/Apptainer, or Poetry. All backends use the same native stage graph. The caller stage is direct qDNAseq or direct HMMcopy/ichorCNA, followed by the same downstream refinement and reporting steps.

Optional ONT methylation uses separately installed tools and licensed models. Use host, Conda or Poetry for that branch; the published Docker and Singularity images do not include it.

For variants from existing alignments, use oncotracer variants --config FILE with a BAM manifest. That command uses configured local tools and does not accept --backend or repeat CNA. The explicit Docker alternative handles container execution of that standalone route.

Native stage graph¶

For Illumina:

FASTQ validation
  -> BWA alignment
  -> samtools/Picard processing
  -> direct independent qDNAseq for every selected sample
  -> BAM-supported boundary refinement
  -> CNA event and cytogenomic notation tables
  -> cohort and per-sample plots
  -> workflow summary, manifest, and checksums
  -> optional native classifier/GISTIC2/reports

For ONT:

optional modified-base BAMs (reuse calls) or POD5 (basecall signal)
  -> select barcode read IDs -> align -> Modkit -> Sturgeon or MARLIN
  -> methylation status (independent of CNA)

barcode FASTQ discovery and merge
  -> minimap2 alignment
  -> HMMcopy readCounter
  -> direct HMMcopy/ichorCNA
  -> BAM-supported boundary refinement
  -> CNA event and cytogenomic notation tables
  -> cohort and per-sample plots
  -> workflow summary, manifest, and checksums
  -> optional native classifier/GISTIC2/reports

When run_cna_classifier: true, stage 05_cna_classifier creates prepared matrices, cancer-context classifications, optional GISTIC2 results, knowledge/pathology concordance, HTML/PDF reports, and clinician summaries.

With run_variants: true, aligned BAMs also feed stage 08_variants:

aligned BAM + reference
  -> requested platform-compatible caller(s)
  -> caller-native filters -> normalization
  -> optional FFPERASE / Varlociraptor assessment
  -> optional local ANNOVAR annotation
  -> per-caller VCFs, evidence tables and status

The stage retains each caller's results separately. Fresh/FFPE, ONT profiles and explicit Strelka2 matched-normal assignments come from the saved configuration. See variant setup; variant resources are prepared only on Run when requested, while missing caller programs must be installed beforehand.

Choose a backend¶

Conda¶

oncotracer install --conda
oncotracer doctor --backend conda

oncotracer run --backend conda \
  --config "$PWD/project/config/illumina.auto.yml"

Docker¶

oncotracer install --docker
oncotracer doctor --backend docker

oncotracer run --backend docker \
  --config "$PWD/project/config/illumina.auto.yml"

The default Docker install above selects the stable CNA image. For a YAML with variants enabled, use the dated variant image and matching run command. A core doctor pass does not verify every optional caller/model.

Singularity or Apptainer¶

oncotracer install --singularity
oncotracer doctor --backend singularity

oncotracer run --backend singularity \
  --config "$PWD/project/config/illumina.auto.yml"

Poetry¶

./oncotracer install --poetry \
  --prefix /path/to/my/oncotracer-v2-dev-envs
/path/to/my/oncotracer-v2-dev-envs-poetry/poetry-runtime/bin/oncotracer doctor \
  --backend poetry

/path/to/my/oncotracer-v2-dev-envs-poetry/poetry-runtime/bin/oncotracer run \
  --backend poetry \
  --config "$PWD/project/config/illumina.auto.yml"

Automatic backend selection¶

When --backend is omitted, OncoTracer uses the backend saved by the most recent successful oncotracer install command:

oncotracer run --config "$PWD/project/config/illumina.auto.yml"

For auditable production commands, specify --backend explicitly. Direct run does not automatically adopt the YAML's execution_backend; the browser and setup --project PROJECT --run pass that saved selection when launching. If no backend has been installed/saved, direct run falls back to host tools.

Threads¶

oncotracer run \
  --backend conda \
  --threads 8 \
  --config "$PWD/project/config/illumina.auto.yml"

The selected thread count is passed to supported native stages. External tool behavior and memory requirements still depend on the specific stage.

For optional methylation, --gpu accelerates Dorado modified-base basecalling and exposes the GPU to MARLIN. Modkit and Sturgeon remain CPU-threaded. Read Optional ONT methylation before enabling it.

Dry-run¶

oncotracer run \
  --backend conda \
  --config "$PWD/project/config/illumina.auto.yml" \
  --dry-run

The dry-run validates paths and shows planned analysis commands without starting them. It does not download references or variant models, run callers, or test biological data quality.

Resume behavior¶

Repeat the same command:

oncotracer run --backend conda \
  --config "$PWD/project/config/illumina.auto.yml"

The native ledger records:

the exact stage argument array;
relevant input paths, sizes, and modification times;
expected output paths and sizes;
SHA-256 values for small outputs;
completion time and stage status.

A stage is reused only when its recorded inputs and settings still match. There is no separate -resume option and no external workflow work directory.

Force¶

oncotracer run \
  --backend conda \
  --config "$PWD/project/config/illumina.auto.yml" \
  --force

Use --force only when deliberately invalidating reusable stages. For a scientifically different analysis, prefer a new YAML and a new outdir.

Native audit records¶

Open these first:

<outdir>/.oncotracer-native/trace.tsv
<outdir>/.oncotracer-native/state.json
<outdir>/06_workflow_summary/workflow_summary.txt
<outdir>/06_workflow_summary/workflow_summary.json
<outdir>/06_workflow_summary/native_run_manifest.json
<outdir>/05_cna_classifier/native_classifier_summary.json  # when enabled
<outdir>/07_methylation/methylation_status.json             # when enabled
<outdir>/07_methylation/methylation_provenance.json         # when enabled
<outdir>/08_variants/variant_status.json                   # when enabled
<outdir>/08_variants/variant_provenance.json               # when enabled

The trace is generated from argument arrays rather than shell strings. The engine checks the final trace and fails if a Nextflow invocation appears.

Inspect the run identity:

OUTDIR="$PWD/project/results"

grep -E '^(mode|dataset|engine|nextflow_used)=' \
  "$OUTDIR/06_workflow_summary/workflow_summary.txt"

sed -n '1,40p' "$OUTDIR/.oncotracer-native/trace.tsv"

Expected native identity:

engine=native
nextflow_used=false

Completion and partial failures¶

Use workflow_status in 06_workflow_summary/workflow_summary.json and the branch-specific status files above to decide what completed.

Status	Meaning
`complete`	All requested applicable steps completed. A caller may legitimately return zero records.
`partial_failure`	Some requested work completed and was retained; inspect the incomplete branch and reason.
`failed`	The current run did not produce a successful applicable analysis branch.

For example, FFPERASE can report not_assessed at insufficient depth while caller VCFs, Varlociraptor and annotation remain available. ANNOVAR skipped for missing optional resources is also distinct from calling failure. Both partial and failed runs can exit with code 2; a scheduler exit code alone cannot tell these outcomes apart. Correct the recorded cause and resume as appropriate; --force does not resolve unsuitable depth, models or specimen choices.

Output ownership and container mounts¶

Docker runs as the invoking numeric user/group. The CLI derives mounts from the standard CNA YAML paths, including lpwgs_root, outdir, samplesheet, FASTQ roots, and pathology table. Use absolute paths and keep related data below a small number of project roots. Optional methylation is rejected for the v2.1.0 container backends.

Stopping and restarting¶

Interrupting a run does not mark an incomplete stage as valid. Correct the cause and repeat the same command. OncoTracer reuses earlier valid stages and reruns the incomplete stage.

Do not manually edit .oncotracer-native/state.json. Preserve it with the result tree for audit and resume.