Call small variants¶
Add single-base changes and short insertions/deletions to a CNA project, or analyze existing BAMs separately. Each caller produces its own variant call format (VCF) file and evidence table. You can configure CNA and variants in one browser session.
Try the controls in the synthetic setup demo, then install OncoTracer to analyze your data. Low-pass variant calls are research candidates: a successful run does not establish clinical sensitivity or prove that a tumor-only candidate is somatic.
For a remote server, use the SSH browser instructions, or choose
one of the Terminal only alternatives below. --no-browser keeps the web
interface running; --non-interactive creates a configuration without a web
server or questions. Replace /data and /resources examples with your paths.
Choose where to start¶
| Your inputs | Start here |
|---|---|
| Illumina or ONT FASTQs | Add variants during CNA setup. |
| Existing aligned BAMs | Use the standalone BAM route. |
| A tumor and its matched normal | Strelka2 somatic example. |
| Completed VCFs to inspect | Read the results. |
Choose one route per project. Fresh/FFPE is the specimen's preservation; Normal/Cancer is the sample's biological role. These are separate settings.
Add calling during setup¶
oncotracer setup --variants
- Choose Illumina or Oxford Nanopore, then Fresh or FFPE from specimen records, before selecting inputs. Discover FASTQs and assign Normal or Cancer; unassigned samples are excluded.
- Keep Copy-number analysis (CNA) selected and enable Add small-variant calling.
- Review the four variant sections below. Confirm preservation and callers, then choose matching ONT profiles or review FFPE resources.
- Optionally enable Varlociraptor and local ANNOVAR annotation.
- Review any missing resources or model candidates before continuing.
- Choose a new or existing project folder, click Save configuration and check, then Run analysis. Review CNA and variant results from the same page.
Terminal only: Illumina Fresh, Conda, Mutect2
This is an alternative to the browser steps, using one tumor library. Install
the managed toolchain with
oncotracer install --conda first. Its verified variant prefix is selected
automatically. Use a new project folder.
oncotracer setup --non-interactive --project "$PWD/variant-study" \
--mode illumina --analysis cna --backend conda --threads 4 \
--sample-name TUMOR01 --status tumor \
--fastq-1 /data/illumina/TUMOR01_R1.fastq.gz \
--fastq-2 /data/illumina/TUMOR01_R2.fastq.gz \
--hg38_build --variants \
--variant-specimen-type fresh --variant-callers mutect2 \
--variant-ffperase off --variant-varlociraptor off --variant-annovar auto
oncotracer check --config "$PWD/variant-study/config/run.yml"
oncotracer run --backend conda --config "$PWD/variant-study/config/run.yml"
The reference downloads when the run starts. For FFPE
or ONT, use the corresponding
complete terminal example. For several Illumina libraries, replace the
single-library flags with --samplesheet /data/illumina/samplesheet.csv using
the documented CSV layout.
Missing caller programs stop preflight. Selected Clair3 models and approved FFPERASE resources can be prepared when Run analysis starts; saving, checking and dry runs download no variant resources. ANNOVAR remains separately supplied. CNA plus methylation can also include variants on supported host backends; methylation-only analysis cannot, and Docker methylation is unavailable.
Configure variants in four sections¶
The FASTQ setup and existing-BAM forms use the same order:
| Section | Choose here |
|---|---|
| 1 · Specimen and callers | Fresh or FFPE, and the callers available for your platform. |
| 2 · Caller tools and models | Caller resources, including a compatible ONT model or preset. |
| 3 · Variant filtering / FFPE damage and filtering | Optional Varlociraptor and, for Illumina FFPE, FFPERASE. |
| 4 · Annotation | Optional ANNOVAR software and databases. |
Choose Fresh or FFPE first; the remaining sections then appear. Controls adapt to your platform, callers and backend. Open advanced paths only to inspect or change an installation.
Find resources¶
Click the glowing detect_tools button to check resources for your selected settings, or use Autodetect beside an individual path. Discovery checks the computer running the setup server. Managed Illumina setup selects the installation-verified variant environment and reports replacement of stale tool prefixes. Other resource fields keep paths you entered. If several candidates are found, review them and choose the one to use. Review every ONT model against your actual chemistry/basecaller; a detected directory does not establish compatibility.
The compact resource summary opens detailed results and installation help.
Missing tools show official download or installation links beside their status.
Missing ANNOVAR software includes a Register and download ANNOVAR link and a
registration notice. FFPERASE source and models link to their upstream license.
Use Choose tools folder to search a particular installation directory.
Repair a missing managed Illumina environment with oncotracer install --conda
or oncotracer install --poetry. For additional caller runtimes, detection offers
Install with Conda or Install with Docker where supported. Review the steps
before starting installation. The choices disappear when all selected tools are
found, or when you change resource settings and need to detect again. A live log
and step counter follow installation while the setup server stays open. Conda
creates fresh optional environments; Docker pulls and checks the selected image.
When installation succeeds, the form selects the installed paths if your settings
have not changed. Otherwise, review them and click Use installed tools.
Save and check your configuration after installation finishes. You can save to
the same project: previous settings are backed up under config/backups/, and
the new configuration records the selected caller environment for Run.
Conda/Mamba/Micromamba or Docker must already be available on the host. The existing-BAM form supports native installation; Docker is offered in FASTQ CNA setup. ClairS-TO's native route needs Apptainer/Singularity for its tested SIF. Models, FFPERASE license acknowledgment, and registered ANNOVAR resources remain separate choices. Discovery itself stays read-only. The expandable Copy commands guides remain available for other installation routes.
Failed or stopped installations retain their log and partial files. Retry creates a new environment. Only completed installations are suggested by discovery. Keep the terminal open during installation; closing the setup server stops its installer. An independently running analysis uses its existing tools.
A target BED and a custom Varlociraptor scenario describe your intended analysis. Select these files explicitly; resource discovery does not choose them.
Conda recipes create separate user-owned optional environments and leave existing folders unchanged. Docker uses the image's caller runtimes. Choose automatic model preparation or existing resource paths. Container tools marked Not verified are verified when the analysis starts. ANNOVAR remains optional and requires separately obtained software and matching databases.
Choose a platform and specimen type¶
Caller choices are grouped as Tumor-only (unpaired), Matched tumor–normal (Illumina), and Germline / independent samples in both FASTQ and existing-BAM setup. With no matched normal, select Mutect2 for Illumina or ClairS-TO for ONT. Strelka2 somatic has no tumor-only mode; leave it deselected for unpaired analysis. Strelka2 germline runs without a matched normal but produces germline-style calls. Tumor–normal matching is separate from paired-end R1/R2 sequencing reads.
| Platform | Caller | What it produces |
|---|---|---|
| Illumina | Mutect2 (default) | Tumor-only candidates with a learned read-orientation artifact model. |
| Illumina | FreeBayes, bcftools | Independent germline-style calls. |
| Illumina | Strelka2 germline | Single-sample germline calling on paired-end reads; no matched normal needed. |
| Illumina | Strelka2 somatic | Paired-end tumor/normal calling with an explicit matched-normal assignment. |
| ONT | Clair3 (default) | Germline-style calls; select a matching basecaller profile for automatic preparation, or an existing model. |
| ONT | ClairS-TO | Tumor-only candidates; choose a compatible platform/model preset. |
Normal/Cancer labels do not create tumor–normal pairs. Strelka2 somatic requires you to select the corresponding normal for each study sample; use a biologically matched normal, not an unrelated cohort control. Other callers keep their existing independent or tumor-only behavior. Samples labeled Normal are skipped by tumor-only/somatic callers (Mutect2, ClairS-TO and Strelka2 somatic); select a germline caller as well if you need their independent variant calls. Caller outputs remain separate. See Strelka2 setup and terminal examples.
Fresh/FFPE describes preservation, not sequencing platform. Use one preservation type per project. Illumina FFPE selects FFPERASE by default; review its preparation and license choices below, or explicitly select Skip FFPERASE. FFPERASE is not supported for Fresh or ONT inputs.
ONT models: select the sequencing profile¶
For Clair3, keep Automatic and select the flow cell/basecaller profile used for the reads. Run downloads the corresponding approximately 75 MB model, checks its pinned size and SHA-256, and reuses the verified cache on resume. Select Use an existing model folder for an installation or profile outside the catalog. Preservation does not identify the sequencing chemistry.
For ClairS-TO, select the readable sequencing/basecaller preset. Its models come from the installed caller or container. Other installed preset (advanced) accepts the exact preset name supported by your installation. See the profile table and paired terminal examples.
Illumina FFPE: review FFPERASE preparation¶
Prepare missing FFPERASE source and models when the run starts can fetch the pinned resources after you explicitly accept their license. Existing paths are reused. A compatible FFPERASE runtime must already be installed; Docker includes it.
The pinned FFPERASE license limits use to personal, academic and noncommercial purposes, excludes clinical use, and requires MSK's express written permission to publish research results. The checkbox acknowledges these terms; it does not grant publication permission. You can instead supply existing licensed resources or skip FFPERASE. See the automatic and local terminal examples.
Conda and Docker¶
The installation guide covers the launcher and core tools. For Conda, add the separate variant and FFPERASE environments using the complete environment commands. The browser's environment field selects the folder containing the caller executables.
Run CNA and variants with Docker¶
Select Docker and this image in browser settings, or prefill them:
oncotracer setup --backend docker \
--image carlosfarkas/oncotracer:terminal-progress-20261022 --variants
Terminal only: the same Docker workflow
This example selects one Fresh Illumina tumor library and Mutect2. The same image runs alignment, CNA and variants; no host Conda environment is needed.
oncotracer setup --non-interactive --project "$PWD/docker-variant-study" \
--mode illumina --analysis cna --backend docker --threads 4 \
--image carlosfarkas/oncotracer:terminal-progress-20261022 \
--sample-name TUMOR01 --status tumor \
--fastq-1 /data/illumina/TUMOR01_R1.fastq.gz \
--fastq-2 /data/illumina/TUMOR01_R2.fastq.gz \
--hg38_build --variants \
--variant-specimen-type fresh --variant-callers mutect2 \
--variant-ffperase off --variant-varlociraptor off --variant-annovar auto
oncotracer check --config "$PWD/docker-variant-study/config/run.yml"
oncotracer run --backend docker \
--image carlosfarkas/oncotracer:terminal-progress-20261022 \
--config "$PWD/docker-variant-study/config/run.yml"
The image supplies native callers and the FFPERASE runtime. The 20260922 image also supports verified model preparation on Run. Existing resource folders and licensed ANNOVAR resources use host paths; OncoTracer mounts them for analysis. Save and check checks paths/settings; Run analysis checks the image tools before alignment. The saved project retains its backend and image. The older 20260921 image requires preexisting model/source paths.
What filtering is applied?¶
| Step | Behavior |
|---|---|
| Caller filters | Mutect2 uses FilterMutectCalls and orientation-model priors. Illumina mapping/base-quality defaults are 20; FreeBayes also requires at least two alternate reads and 5% alternate fraction. ONT callers retain their native filtering. |
| Normalization | Splits multiallelic records, normalizes alleles against the reference, sorts and indexes VCFs. |
| FFPE review | Flags C>T/G>A changes for review; this flag alone does not reject them. |
| FFPERASE | Adds an independent artifact assessment for Illumina FFPE when selected and assessable. |
| Varlociraptor | Optional evidence assessment and local false-discovery-rate filtering; default threshold 0.05 when enabled. |
There is no universal post-calling QUAL/DP cutoff applied across every caller. Assessment steps retain candidates and add FILTER/evidence fields; they do not rescue an existing caller failure. The default Varlociraptor model assesses presence, not somatic origin: enabling it requires no scenario YAML or sample key. Custom models remain under Advanced evidence settings. See the filtering reference for exact behavior and low-depth FFPERASE limitations.
Optional local ANNOVAR¶
Choose Use ANNOVAR when available, or Skip ANNOVAR annotation. Automatic discovery uses existing scripts and matching databases; it downloads nothing. Annotation adds gene/database descriptions after filtering. Follow ANNOVAR setup and output guidance.
Call from existing BAMs without rerunning CNA¶
Prepare the BAM manifest and configuration, then open:
oncotracer setup --variant-config /data/variants.yml
Replace /data/variants.yml with your configuration. The Call variants from
existing BAMs link in initial setup opens the same form. Review samples,
Fresh/FFPE, callers and resources; save to a new project and run. This standalone
browser route uses host tools and existing alignments; it does not repeat CNA.
Container and terminal alternatives remain available.
Terminal only, with that same existing-BAM configuration:
oncotracer variants --config /data/variants.yml --dry-run
oncotracer variants --config /data/variants.yml --threads 4
variants uses local tools from the configuration/environment and has no
--backend argument. The explicit Docker command
is the container alternative. setup --variant-config always opens the browser;
it cannot be combined with --non-interactive or --terminal.
Read the results¶
Open the dashboard and select 08 · Small variants. Inspect each caller's
VCF, evidence.tsv, assessment tables, annotation outputs and logs. The dashboard
separates zero calls, skipped annotation, partial failure and failed calls.
For example, insufficient FFPE depth can leave FFPERASE not_assessed while
retaining completed caller, Varlociraptor and ANNOVAR outputs. Read the recorded
reason and available evidence. A nonzero terminal exit code can mean partial
failure or failure; inspect workflow_status and the per-caller status rather
than treating every nonzero return as loss of all results. Output paths and
status details explain what was produced.