Native CLI and YAML parameter reference

Start with guided setup, or batch setup for many libraries. This page lists the commands and YAML fields.

Command structure

oncotracer install ...
oncotracer doctor ...
oncotracer setup --project PATH ...
oncotracer setup --terminal --project PATH ...
oncotracer setup --non-interactive --project PATH ...
oncotracer check --config FILE
oncotracer system --path PATH
oncotracer reference install ...
oncotracer uninstall ...
oncotracer auto ...
oncotracer run ...
oncotracer variants --config FILE ...
oncotracer provenance --json

Run oncotracer <subcommand> --help to inspect the executable installed on the system.

oncotracer install

Choose one command below. Conda/Poetry install the core CNA tools and verified shared Illumina variant environment; caller-specific resources are covered in the variant installation guide. Docker below explicitly selects the current variant-capable image.

oncotracer install --conda
oncotracer install --docker --image carlosfarkas/oncotracer:terminal-progress-20261022
oncotracer install --singularity
./oncotracer install --poetry

Option	Accepted with	Meaning
--conda	exactly one backend	Create/update core Conda prefixes and the verified variant prefix
--docker	exactly one backend	Validate Docker, pull the native image, and run its host doctor
--singularity	exactly one backend	Pull/reuse a SIF through Apptainer or Singularity
--poetry	exactly one backend	Install an isolated source-development launcher, core Conda tools and verified variant tools
--prefix PATH	Conda, Poetry	Dedicated owned parent for fixed managed children
--image IMAGE	Docker, Singularity	Override the default native container image
--sif PATH	Singularity	Override the managed Singularity/Apptainer image path
--force	Conda, Poetry, Singularity	Transactionally replace intact, owned assets only
--dry-run	every backend	Print installation commands without executing them or writing state
--no-launcher	every backend	Skip the owned ~/.local/bin/oncotracer command
--root PATH	Conda, Poetry	Explicit source or extracted payload root

Backend-irrelevant options are errors; they are never silently ignored. Conda and Poetry prefixes must be absent, empty, or have exact root and child ownership markers. A SIF destination must be absent on first installation or form an intact file/sidecar pair already owned by OncoTracer. --force cannot adopt, unlink, or recursively remove an unowned target.

oncotracer doctor

oncotracer doctor --backend conda
oncotracer doctor --backend docker
oncotracer doctor --backend singularity
oncotracer doctor --backend poetry

Add --json for machine-readable output. The command exits nonzero when required source identity, prefixes, packages, or semantic executable probes fail.

oncotracer setup and oncotracer check

Plain setup opens the browser form. setup --terminal asks terminal questions for folder discovery, sample selection/types, analysis and hardware settings. Both save the same YAML used by ordinary runs. The terminal wizard's final save choice finishes without analysis; run starts it.

--non-interactive uses explicit sample flags and defaults without questions; it cannot be combined with --input-folder. Use --samplesheet or the single-library flags for Illumina, and --reads-folder plus --barcodes for ONT. See terminal and headless servers for complete scripted and SSH examples. --no-browser still starts the local web server; it only suppresses automatic browser launch.

Choose one setup interface for this project:

oncotracer setup --project /work/my-study --backend conda

Terminal equivalent:

oncotracer setup --terminal --project /work/my-study --backend conda

Save the configuration, then run these terminal commands. Skip the run command if you already selected Run in setup:

oncotracer check --config /work/my-study/config/run.yml
oncotracer run --backend conda --config /work/my-study/config/run.yml

Option	Meaning
--terminal	Ask terminal questions instead of starting the browser form
--no-browser	Start the loopback server without opening a browser; not a terminal workflow
--port N	Browser server port, default 8888; bind address is fixed to 127.0.0.1
--backend NAME	Select host, conda, poetry, docker or singularity; optional branches have backend restrictions
--image IMAGE	Docker image saved in project YAML; requires --backend docker
--project PATH	New project containing config/run.yml and future results
--mode illumina or --mode ont	Sequencing platform
--input-folder PATH	Folder for browser or terminal discovery; incompatible with --non-interactive and explicit sample flags
--manual	Use individual file/barcode prompts instead of folder discovery
--ont-named-samples	Interpret an ONT cohort as named library folders, including a cohort with only one library
--analysis cna, methylation or both	Requested analysis; methylation requires ONT
--fastq-1 FILE, --fastq-2 FILE, --sample-name NAME	One Illumina library; omit R2 for single-end
--samplesheet FILE	Multiple Illumina libraries in a sample/R1/R2/status CSV
--reads-folder PATH	ONT fastq_pass directory
--barcodes LIST, --sample-names LIST	Matching comma-separated barcode folders and sample names
--hg38_build [PATH]	Reuse prepared hg38; no path selects the default prebuilt download into PROJECT/reference when run starts
--build_reference	Build missing hg38 indexes locally on CPU when run starts; cannot be combined with --hg38_build
--threads NUMBER	Total CPU budget, checked against available workers
--parallel-samples auto or N	Maximum concurrent alignment/variant samples; default auto
--variant-memory auto or 64GB	Total RAM budget for alignment and variants at setup
--non-interactive	Skip questions; missing required inputs are errors, defaults still apply
--run	Validate, prepare tools and run after setup; with --terminal, questions remain but the final save/run choice is skipped
--variant-config FILE	Existing-BAM browser form; terminal equivalent is oncotracer variants --config FILE

setup --terminal --run configures and runs through terminal questions. setup --non-interactive ... --run configures and runs without prompts when all required inputs and resources are supplied. setup --project PROJECT --run resumes an existing project using its saved backend and image. Setup has no --dry-run; save first, then use run --dry-run.

Optional variant flags belong to setup, or to YAML when using run or variants. See variant flags and terminal examples. setup --variant-config cannot be combined with --terminal, --non-interactive or --run; use the standalone variants command instead.

These options save lpwgs_root and hg38_auto_download in YAML. The default is true: download a missing prebuilt reference at run time. --build_reference sets it to false: reuse existing references or build missing indexes locally. Supplying an existing --hg38_build PATH also sets it to false. Choosing save, or using manual/scripted setup without --run, starts no genome downloads or builds. Check and dry-run also leave genomes untouched. Supplied references are validated before use; shared references are not overwritten.

The wizard saves config/sample_metadata.csv and its sample_metadata YAML path. This records each sample's type label, explicit tumor/normal analysis role and selected FASTQ files. other labels require an explicit study/control mapping. CNA controls are analyzed independently; ONT controls support ichorCNA or solid-biopsy qDNAseq. Somatic Strelka2 additionally requires explicit tumor-to-normal pairing.

oncotracer check --config FILE reports missing paths/settings and the planned samples without running analysis. See setup examples, QuickStart 1, and QuickStart 2 for complete commands. Reference installation is optional when compatible indexes are already present.

oncotracer auto

oncotracer auto \
  --mode illumina \
  --reads-folder "$PWD/project/input/fastq" \
  --sample-table "$PWD/project/input/samples.csv" \
  --config-dir "$PWD/project/config" \
  --outdir "$PWD/project/results"
oncotracer check --config "$PWD/project/config/illumina.auto.yml"
oncotracer run --backend conda --config "$PWD/project/config/illumina.auto.yml"

Option	Required	Meaning
--mode MODE	yes	illumina or ont; select input discovery and YAML route
--reads-folder PATH	yes	Illumina FASTQ folder or ONT barcode parent
--sample-table FILE	yes	Illumina sample_name,status or ONT barcode,sample_name,status CSV
--config-dir PATH	no	Generated YAML/manifest/samplesheet destination
--outdir PATH	no	Result directory written into the YAML
--threads N	no	CPU worker threads saved in YAML; default 8
--hg38_build [PATH]	no	Reuse a prepared reference; no path means automatic download at run time
--build_reference	no	Build missing indexes on CPU at run time; cannot combine with --hg38_build
--run-cna-classifier	no	Write run_cna_classifier: true
--cna-classifier-sample-set NAME	no	Study context, e.g. sarcoma; requires classifier flag
--no-pathology-models	no	Disable biomedical models in reports; requires classifier flag
--dry-run	no	Print the generator command; no files, gzip checks or analysis

Create the sample table using the complete batch examples. Existing generated files are never overwritten. Defaults are READS/oncotracer_config and READS/oncotracer_results; pass both folder flags to keep settings and results separate from the reads. Automatic reference downloads go to CONFIG_DIR/reference only when run starts. auto does not create the results directory and has no --run flag. Run its saved configuration with oncotracer run. Web/LLM report enrichment is off by default.

oncotracer run

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

Option	Meaning
--config FILE	Required flat native YAML
--backend NAME	host, conda, docker, singularity, or poetry; the global installation backend is used when omitted (fallback: host)
--threads N	Thread limit passed to supported native stages
--parallel-samples auto or N	Override saved concurrency for alignment and variants
--force	Deliberate stage refresh
--dry-run	Validate and print native commands without launching tools
--image IMAGE	Docker image override
--sif PATH	Singularity/Apptainer image override
--root PATH	Explicit payload/source root
--methylation	Add ONT methylation analysis to the copy-number workflow
--sturgeon	Select the supported CNS-tumor research classifier; mutually exclusive with --marlin
--marlin	Select the supported leukemia research classifier; mutually exclusive with --sturgeon
--pod5-dir PATH	Raw POD5 input for methylation basecalling; choose this or --modbam
--modbam PATH	reuse calls from an existing modified-base BAM or directory of BAMs; CPU alignment
--methylation-only	request methylation and skip copy-number analysis
--cpu	keep methylation on CPU, overriding GPU YAML settings
--gpu	Use cuda:all for Dorado and expose the GPU to MARLIN; requires --methylation

Repeating the same command reuses valid content-matched stages automatically. Give --backend explicitly for reproducible scripts: ordinary run does not select the backend from YAML execution_backend. To reuse that project setting, use setup --project PROJECT --run instead.

Optional methylation is ONT-only and supports the host, conda, and poetry backends with explicit user-installed resources. The stable container does not redistribute the licensed tools/models, so Docker and Singularity/Apptainer reject this branch.

Common YAML fields

Field	Type/default	Meaning
mode	required illumina or ont	Sequencing route
lpwgs_root	required absolute directory	Project/reference/cache root visible to the backend
outdir	required absolute directory	Dedicated absent, empty, or exact-runtime-owned native result tree
parallel_samples	auto or positive integer	Alignment sample slots within the detected CPU/RAM budget
analysis_memory	auto or e.g. 64GB	Total alignment RAM budget, divided among slots
variant_parallel_samples	auto or positive integer	Variant sample slots; applies to Illumina and ONT
variant_memory	auto or e.g. 64GB	Total variant RAM budget; minimum 32 GiB per complete Illumina sample
force	Boolean, false	Scientific refresh request; normally keep false
run_cna_classifier	Boolean, false	Add stage 05_cna_classifier

Illumina YAML fields

Field	Typical/default	Meaning
illumina_samplesheet	required path	Four columns: sample,fastq_1,fastq_2,status
illumina_analysis_type	solid_biopsy	Compatibility metadata; native Illumina always uses qDNAseq
illumina_caller	qdnaseq	Native Illumina CNA caller
illumina_binsize_kb	100	Coarse qDNAseq bin width

The samplesheet status column preserves tumor or normal metadata. Every row is analyzed independently by qDNAseq; normal rows do not create a CNA reference. For somatic variants, Strelka2 requires explicit pairs.

ONT YAML fields

Field	Typical/default	Meaning
ont_folder	required path	Named-library parent or legacy barcode FASTQ parent
ont_named_samples	false	Use named library directories, each containing one fastq_pass directly or under one run directory
ont_barcodes	required comma-separated names	Selected named libraries when ont_named_samples: true; otherwise tumor barcodes
ont_sample_names	barcode names when omitted	Positional biological sample names
ont_normal_folder	optional path	Parent containing independent NORMAL library/barcode directories; supported with ichorCNA or solid-biopsy qDNAseq
ont_normal_barcodes	required with ont_normal_folder	NORMAL library/barcode selection; each is analyzed independently
ont_normal_sample_names	NORMAL barcode names when omitted	Positional NORMAL sample names; never pooled into a panel
ont_analysis_type	liquid_biopsy	Analysis preset
ont_caller	ichorcna	ichorcna, or qdnaseq only with explicit ont_analysis_type: solid_biopsy
ont_binsize_kb	500	Coarse caller bin width; set explicitly for qDNAseq solid-biopsy runs
ont_min_age_minutes	0	Exclude very new FASTQs in active run folders

Older ont_ref and ont_force_realign keys are ignored by the native engine. Use the reference setup options for hg38 assets. Use run --force only to deliberately rerun all analysis stages, not just alignment.

ont_barcodes and ont_sample_names must have equal lengths and order. The corresponding NORMAL lists must also match, sample names and resolved barcode directories must be unique across both groups, and a mixed TUMOR/NORMAL run uses native qDNAseq rather than the frozen Nextflow comparator.

Optional ONT methylation YAML fields

CLI values override methylation, classifier, input, and GPU YAML values. Choose one explicit methylation input: POD5 or modified-base BAM. Conflicting input types in flags and YAML are rejected.

Field	Typical/default	Meaning
methylation	false	Enable optional ONT methylation when not using --methylation
methylation_classifier	required when enabled	Exactly sturgeon or marlin
methylation_pod5_dir	one input required	Explicit directory containing non-empty .pod5 files
methylation_modbam	one input required	existing modified-base BAM file or directory; replaces POD5 input
methylation_only	false	skip CNA; enabled by setup --analysis methylation
threads	up to 16 if not set	CPU worker threads; --threads overrides this value
methylation_gpu	false	Dorado cuda:all; MARLIN GPU visibility; Modkit/Sturgeon remain CPU
methylation_reference_build	hg38	Only supported methylation reference build in v2.1.0
methylation_dorado_executable	required local executable	Dorado binary; no download or installation
methylation_modkit_executable	required local executable	Modkit binary; no download or installation
methylation_samtools_executable	samtools	Explicit or PATH-resolved SAMtools binary
methylation_dorado_model	required for POD5	Explicit compatible Dorado basecalling model
methylation_dorado_model_sha256	optional expected digest	OncoTracer directory-tree digest; always recorded
methylation_dorado_modbase_model	required for POD5	Explicit compatible 5mCG/5hmCG model
methylation_dorado_modbase_model_sha256	optional expected digest	OncoTracer directory-tree digest; always recorded
sturgeon_interface_contract_commit	fixed supported upstream interface commit; does not authenticate the installed package	4c742ddea49b0077a8f8ff3d99daafb238d00706
sturgeon_license_acknowledged	required true	User attests to separately obtaining/accepting the Sturgeon license
sturgeon_executable	required	User-installed Sturgeon executable
sturgeon_model, sturgeon_model_sha256	required pair	Explicit model and exact file SHA-256
sturgeon_probes, sturgeon_probes_sha256	required pair	Explicit hg38 probes and exact file SHA-256
marlin_interface_contract_commit	fixed supported upstream interface commit; does not authenticate an external runtime	37c9836cc325ff2edccbdff06736604163db2c15
marlin_rscript	required	Rscript from the user-prepared MARLIN environment
marlin_python	required	Exact Python with h5py, NumPy, and TensorFlow; automatic environments are forbidden
marlin_model, marlin_model_sha256	required pair	Explicit MARLIN model and exact file SHA-256
marlin_features, marlin_features_sha256	required pair	Explicit feature RData and exact file SHA-256
marlin_class_annotations, marlin_class_annotations_sha256	required pair	Explicit class workbook and exact file SHA-256
marlin_probe_bed, marlin_probe_bed_sha256	required pair	Explicit hg38 probe BED and exact file SHA-256

The classifier is not invoked for a sample with zero usable modified-CpG calls. CNA continues, and the final status reports the two branches independently. See Optional ONT methylation for the complete setup, dry-run, resume, license, and outputs.

Native classifier and pathology fields

Field	Typical/default	Meaning
cna_classifier_sample_set	broad_cancer	Study-defined cancer context
cna_classifier_samples	optional IDs	Optional subset of sequencing samples
run_pdf_reports	true	Publish matched knowledge HTML/PDF reports and indexes in 05_cna_classifier/
pathology_csv	optional path	De-identified matched pathology table
pathology_sample_col	illumina_sample_id	Column matching sequencing sample IDs
pathology_case_col	case_code	De-identified case/accession column
pathology_diagnosis_col	final_diagnosis	Diagnosis text column
pathology_use_biomed_models	false recommended initially	Optional biomedical model assistance
pathology_biomed_local_files_only	true recommended initially	Restrict models to local cache
run_gistic	false unless enabled	Optional cohort recurrence branch
gistic_required	false	Make GISTIC2 failure fatal only when justified
gistic_min_samples	2	Minimum cohort size for requested recurrence analysis
knowledge_web	false recommended	Optional network enrichment
knowledge_literature_llm	false recommended	Optional model-assisted literature synthesis
knowledge_literature_llm_models	model IDs or absolute model paths	Comma-separated generation fallbacks; Hub IDs accept @commit
knowledge_literature_llm_local_files_only	false	Set true to forbid generation-model downloads
knowledge_llm_threads	4	CPU threads for report generation and reference ranking
knowledge_literature_llm_max_features	24	Maximum features to synthesize
knowledge_literature_llm_max_input_chars	2800	Prompt character cap; model token limits also apply
knowledge_literature_llm_max_new_tokens	96	Generation token cap; 192 allows more room for structured citations
knowledge_literature_reference_llm_selection	true	Optional per-feature ranking when synthesis is enabled
knowledge_deep_enable_llm_ranker	true	Separate sample-wide LLM paper selection
knowledge_deep_llm_ranker_models	model IDs or absolute model paths	Models for sample-wide ranking
knowledge_deep_llm_ranker_local_files_only	false	Set true to forbid ranker-model downloads
knowledge_deep_llm_ranker_max_candidates_per_sample	18	Maximum papers submitted to the sample-wide ranker
knowledge_deep_literature	false recommended	Optional expanded literature workflow

See LLM-assisted reports for a short working configuration and the difference between local generation and public literature retrieval.

Nested YAML is deliberately rejected. Keep this section flat.

Boundary-refinement fields

Field	Default	Meaning
fine_bin_kb_illumina	10	Local Illumina depth bin
fine_bin_kb_ont	25	Local ONT depth bin
search_radius_bins	2	Coarse-bin search distance
min_mapq	20	Minimum BAM mapping quality
min_local_log2_diff_illumina	0.10	Minimum Illumina local step
min_local_log2_diff_ont	0.12	Minimum ONT local step
min_adjacent_seg_delta	0.10	Minimum adjacent coarse difference
min_bic_gain	6	Minimum model-fit improvement
permutations	300	Empirical permutations
permutation_p	0.05	Empirical threshold
accept_rule	p_and_bic	Boundary acceptance rule
max_ci_fraction_of_coarse	1.0	Maximum CI width relative to coarse bin
zipcnv_mode	adapted	ZIPcnv comparison mode
zipcnv_window_bins	5	Adapted comparison window
zipcnv_k	0.05	Adapted tuning constant
zipcnv_min_segment_bins	3	Minimum retained segment length
zipcnv_min_abs_log2	0.25	Minimum retained absolute signal
zipcnv_compare_min_overlap	0.50	Minimum comparison overlap

Keep defaults for an initial analysis. Use a new YAML and new outdir for methods comparisons.

Provenance command

oncotracer provenance --json

The record includes version, source commit, deterministic source digest definition/value, source-tree cleanliness, and copied-binary SHA-256 when bound into a release build.