Execution backends¶

All backends use the same native stage graph, flat YAML, result directory layout, and audit records. The backend changes how the scientific programs are supplied; it does not select a different analysis pipeline.

Use the YAML you already created with setup or batch setup. Choose one backend below. The examples assume batch setup's project/config/illumina.auto.yml; substitute my-study/config/run.yml if you used guided setup. Install once, run check, then use the matching run command. Every run example works from a terminal without a browser. For unattended setup and SSH access, see terminal and headless servers.

Backend	Install command	Primary use
Conda	`oncotracer install --conda`	Native workstation/server execution
Docker	`oncotracer install --docker`	Reproducible container execution
Singularity/Apptainer	`oncotracer install --singularity`	HPC execution with a reusable SIF
Poetry	`./oncotracer install --poetry`	Launcher development; scientific programs use isolated Conda prefixes, including verified variant tools

The five core Conda groups are core, qdnaseq, ichorcna, classifier, and gistic. Conda and Poetry installation also create and verify one managed Illumina variants environment. Variant-enabled images include isolated variants and ffperase environments plus the legacy strelka2 runtime.

Which analyses does each backend support?¶

Analysis	Conda / host / Poetry	Updated Docker image	Singularity / Apptainer backend
CNA and optional CNA reports	Yes	Yes	Yes
CNA plus small variants	With the requested optional tools	Yes, build the current variant image below	Not supported
ONT methylation	With separate compatible tools/models	Not supported	Not supported
Existing BAMs, variants only	Direct `oncotracer variants` command	Explicit container command in the variant reference	No integrated route

An existing caller-specific SIF can supply ClairS-TO or FFPERASE on the host. That is different from selecting Singularity for the complete OncoTracer pipeline. Installation and doctor verify the shared variant toolchain as well as CNA tools. Selected caller-specific resources and models also have their own preflight.

Conda¶

oncotracer install --conda
oncotracer doctor --backend conda
oncotracer check --config "$PWD/project/config/illumina.auto.yml"

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

The installer creates or updates isolated versioned prefixes. qDNAseq and ichorCNA are separated because their R stacks are incompatible. The classifier and GISTIC2 also remain isolated. A prefix parent must be absent, empty, or carry the exact OncoTracer ownership marker; populated unowned paths and unmarked fixed children are never adopted. Updates are journaled under an ownership-checked lock: the verified prior child is backed up and its replacement is created directly at the final prefix, then semantically probed and exactly inventoried. Unrelated siblings are preserved, and active managed prefixes are refused.

oncotracer doctor --backend conda uses exact prefix executables and semantic tool/package probes rather than relying on a login shell's PATH.

Use an alternate prefix parent when local policy requires it:

oncotracer install --conda \
  --prefix "/large/storage/oncotracer-v2-envs"

Docker¶

FASTQ to CNA and variants¶

The current Linux x86-64 image is carlosfarkas/oncotracer:terminal-progress-20261022. It includes the complete Illumina GLIMPSE2 workflow, FFPE repairs, integrated ONT callers and concurrent project support. oncotracer install --docker selects this image by default.

To build the current source checkout instead (older dated tags remain unchanged):

SOURCE_COMMIT="$(git rev-parse HEAD)"
SOURCE_SHA256="$(git -c tar.umask=0002 archive --format=tar "$SOURCE_COMMIT" | sha256sum | awk '{print $1}')"
docker build --build-arg SOURCE_COMMIT="$SOURCE_COMMIT" \
  --build-arg SOURCE_SHA256="$SOURCE_SHA256" -t oncotracer:glimpse2-repair .
oncotracer install --docker --image oncotracer:glimpse2-repair --no-pull
oncotracer setup --backend docker \
  --image oncotracer:glimpse2-repair --variants

--no-pull installs an existing local Docker image after checking it with doctor. Without that flag, installation pulls the selected registry image. Use a clean committed checkout when building the source-bound image.

Select Illumina or ONT, Fresh or FFPE, and the compatible callers. Save and check, then Run analysis, starts alignment, CNA analysis and the selected variant stages in one project. ANNOVAR uses an existing licensed installation and databases. Run can prepare the selected Clair3 model and missing FFPERASE source/models after explicit license acceptance. The image includes pinned Nextflow with a writable runtime cache for arbitrary container UIDs. Checks and dry runs download no variant resources; existing paths remain supported.

Terminal equivalent, using the same image and variant branch:

oncotracer setup --terminal --backend docker \
  --image oncotracer:glimpse2-repair --variants --run

Answer the platform, input, preservation, caller and resource questions. --run starts analysis after validation. To save first, omit --run and choose save; then use the project path you selected:

oncotracer check --config /absolute/path/to/my-study/config/run.yml
oncotracer run --backend docker \
  --image oncotracer:glimpse2-repair \
  --config /absolute/path/to/my-study/config/run.yml

Choose either setup route for a new project. For fully unattended FASTQ setup, use the explicit sample commands with --non-interactive.

See the resume and FFPE repair notes for validation scope, compatible resource requirements and the existing-output ownership boundary. The stable release below predates the complete GLIMPSE2 branch.

Stable CNA release¶

Stable native image:

ghcr.io/cfarkas/oncotracer:2.1.0

Install and run:

oncotracer install --docker
oncotracer doctor --backend docker
oncotracer check --config "$PWD/project/config/illumina.auto.yml"

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

For variant-enabled runs, the CLI reads the YAML and binds the configuration, FASTQs, reference and external resources at their existing absolute paths. Inputs and supplied resources are read-only; output and reference-cache locations are writable. Host tool environments are not mounted over the image environments.

Docker runs as the invoking UID:GID so result ownership remains with the user. Docker daemon access is privileged; follow institutional policy instead of adding undocumented administrator workarounds.

Select a local image tag or immutable registry digest:

oncotracer run \
  --backend docker \
  --image ghcr.io/cfarkas/oncotracer:2.1.0 \
  --config "$PWD/project/config/illumina.auto.yml"

The browser's Docker image tag or digest field and setup --image save the selection as docker_image in the project YAML. setup --project PROJECT --run also reuses the saved execution_backend. For run --backend docker, an explicit --image takes precedence over docker_image, then the installed/default image. A local tag can therefore be tested without replacing the configured release.

Docker supports CNA with optional small-variant calling from Illumina or ONT FASTQs. The updated Dockerfile bundles native Clair3 v1.2.0 and ClairS-TO v0.4.4 alongside the Illumina callers. Requested callers must be native tools in the chosen image; a container preflight checks them before alignment. Docker does not nest ClairS-TO or FFPERASE SIF execution. External source/model folders and existing ANNOVAR databases remain host resources and are mounted read-only. Browser setup hides host prefix and SIF fields when Docker is selected. Docker methylation and the full Singularity backend with small variants remain unsupported.

For direct Compose inspection:

ONCOTRACER_PROJECT_DIR="$PWD/project" \
  docker compose run --rm oncotracer --version

The ordinary CLI route is preferred for analyses because it derives mounts from the YAML.

Singularity or Apptainer¶

oncotracer install --singularity
oncotracer doctor --backend singularity
oncotracer check --config "$PWD/project/config/illumina.auto.yml"

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

Apptainer is preferred when both executables are present. The installer pulls the same native image into a local SIF and records its path in the OncoTracer configuration. The runner uses --cleanenv and explicit binds derived from YAML paths.

The SIF and its strict .oncotracer.json ownership sidecar form one managed pair. Reuse verifies the canonical path, image reference, source identity, file SHA-256, container provenance, and native host doctor. --force never unlinks an existing file first: it stages and verifies a sibling candidate, then atomically publishes it with a rollback journal. Unowned, malformed, symlinked, hard-linked, or active destinations are preserved and rejected.

Choose an explicit SIF location:

oncotracer install --singularity \
  --sif "/large/storage/containers/oncotracer-2.1.0.sif"

To install a source-built image already present in your local Docker daemon, use an explicit local transport. This builds the SIF without publishing an image:

oncotracer install --singularity \
  --image docker-daemon:oncotracer:glimpse2-repair \
  --sif "/large/storage/containers/oncotracer-glimpse2.sif"

This route retains the same ownership, provenance and container health checks. The complete Singularity backend supports CNA; integrated small variants remain unsupported as shown in the backend table above.

Or override it for one run:

oncotracer run \
  --backend singularity \
  --sif "/large/storage/containers/oncotracer-2.1.0.sif" \
  --config "$PWD/project/config/illumina.auto.yml"

Poetry development route¶

./oncotracer install --poetry \
  --prefix /path/to/my/oncotracer-v2-dev-envs

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

Poetry 2.0 or newer is required. OncoTracer builds a wheel in isolated transaction state from the exact clean checkout, then installs it using only the explicit owned poetry-runtime child's Python and pip. It does not mutate a global Poetry environment, ambient site-packages, or a checkout-local .venv. It does not replace BWA, SAMtools, Picard, qDNAseq, HMMcopy, ichorCNA, the classifier stack, or GISTIC2; those are still resolved from the exact managed prefixes.

Paths and mounts¶

Use absolute paths in YAML, especially for Docker and HPC systems:

lpwgs_root: /data/studies/cohort_a
outdir: /data/studies/cohort_a/results/run_01
illumina_samplesheet: /data/studies/cohort_a/config/illumina.samplesheet.csv
pathology_csv: /data/studies/cohort_a/input/pathology.csv

Keep all configured files under storage visible to the backend. Avoid symlinks whose targets are outside mounted roots.

Image and source identity¶

oncotracer provenance --json
oncotracer doctor --backend docker

For a locally built variant image, inspect that exact image as well; the host launcher and container can come from different commits:

docker run --rm oncotracer:glimpse2-repair provenance --json
oncotracer doctor --backend docker \
  --image oncotracer:glimpse2-repair
docker image inspect --format '{{json .RepoDigests}}' \
  oncotracer:glimpse2-repair

Record the digest you used with the study. doctor here checks core tools; variant setup/preflight checks the requested caller resources separately.

Stable release records contain the exact source commit, deterministic source-tree SHA-256, copied-executable SHA-256, container digest, and successful native-CI and parity workflow identities. Prefer the immutable digest from release-provenance.json when recording a formal analysis.

Backend-independent QuickStarts¶

Download the reads and create the configurations using the ordinary setup commands in QuickStart 1 or QuickStart 2. After check succeeds, select your installed backend with --backend:

cd /path/to/my/analyses_dir/

oncotracer run --backend docker \
  --config "$PWD/oncotracer-quickstart1/illumina/config/run.yml"
oncotracer run --backend docker \
  --config "$PWD/oncotracer-quickstart1/ont/config/run.yml"

oncotracer run --backend singularity \
  --config "$PWD/oncotracer-quickstart2/analysis/config/run.yml"

The scientific settings remain the same across supported backends. Setup also records the selected execution backend and optional Docker image. All absolute input paths must remain available; use the tool and container options supported by the selected backend.