Canonical native YAML configuration¶

This is a settings reference, not a start-to-finish tutorial. Use setup or batch setup to create your first configuration. The examples below are alternatives: edit existing keys rather than appending duplicate keys.

Nested YAML is deliberately rejected by the standalone parser.

Minimal Illumina¶

Save this as /data/study/config/illumina.manual.yml, after replacing the example paths. The reference setting imports prebuilt hg38 assets on the first run, matching automatic setup.

mode: illumina
lpwgs_root: /data/study
hg38_auto_download: true
outdir: /data/study/results/illumina
illumina_samplesheet: /data/study/config/illumina.samplesheet.csv
illumina_analysis_type: solid_biopsy
illumina_caller: qdnaseq
illumina_binsize_kb: 100
run_cna_classifier: false
force: false

Create the four-column samplesheet. Replace /data/study and the filenames with yours before pasting; cat > replaces the named file if it exists.

mkdir -p "/data/study/config"
cat > "/data/study/config/illumina.samplesheet.csv" <<'CSV'
sample,fastq_1,fastq_2,status
Tumor_A,"/data/study/input/Tumor_A_R1.fastq.gz","/data/study/input/Tumor_A_R2.fastq.gz",tumor
Tumor_B,"/data/study/input/Tumor_B_R1.fastq.gz","/data/study/input/Tumor_B_R2.fastq.gz",tumor
CSV

For single-end data, keep the header and leave fastq_2 empty for every row. Do not mix single-end and paired-end libraries in one analysis.

Minimal ONT¶

Save this alternative as /data/study/config/ont.manual.yml with your own paths.

mode: ont
lpwgs_root: /data/study
hg38_auto_download: true
outdir: /data/study/results/ont
ont_folder: /data/study/input/fastq_pass
ont_barcodes: barcode01,barcode02
ont_sample_names: SAMPLE_01,SAMPLE_02
ont_analysis_type: liquid_biopsy
ont_caller: ichorcna
ont_binsize_kb: 500
ont_min_age_minutes: 0
run_cna_classifier: false
force: false

ont_barcodes and ont_sample_names are positional and must have the same number of entries.

Independent controls can be included with either caller using ont_normal_folder, ont_normal_barcodes and ont_normal_sample_names. Their Normal labels are retained; adding controls does not force QDNAseq or build a panel of normals.

The default above is the liquid-biopsy ichorCNA route. For a separate solid-biopsy qDNAseq analysis, use a new outdir and set ont_analysis_type: solid_biopsy, ont_caller: qdnaseq, and an explicit qDNAseq bin width. The engine rejects qDNAseq for other ONT analysis types.

ONT methylation is available with --methylation plus --sturgeon or --marlin. Supply raw signal with --pod5-dir or existing modified-base BAMs with --modbam. Use --methylation-only to skip CNA. The methylation guide explains the inputs, resources, and CPU options.

Run a YAML¶

Use the file you saved above. For Illumina:

oncotracer check --config /data/study/config/illumina.manual.yml
oncotracer run --backend conda --threads 16 --config /data/study/config/illumina.manual.yml

For ONT instead:

oncotracer check --config /data/study/config/ont.manual.yml
oncotracer run --backend conda --threads 16 --config /data/study/config/ont.manual.yml

Repeat the same command to reuse valid completed stages. Add --dry-run to preview the analysis commands, or --force only for a deliberate refresh.

Normal samples¶

In an Illumina samplesheet, status: normal is preserved metadata for an independently analyzed qDNAseq sample. Automatic Setup does not pool normal rows, create a sample-derived reference, or exclude them from per-sample CNA outputs. Review qdnaseq_sample_status.json for exact completion status.

Optional somatic Strelka2 uses an explicit tumor-to-normal mapping. Marking a sample normal does not assign it to a tumor automatically.

Optional native CNA classifier¶

The complete classifier/report branch runs through the native executable; it is not delegated to Nextflow.

run_cna_classifier: true
cna_classifier_sample_set: broad_cancer

# Optional matched pathology table.
pathology_csv: /data/study/input/pathology.csv
pathology_sample_col: illumina_sample_id
pathology_case_col: case_code
pathology_diagnosis_col: final_diagnosis
pathology_use_biomed_models: false
pathology_biomed_local_files_only: true

# GISTIC2 is optional and non-fatal unless explicitly required.
run_gistic: true
gistic_required: false
gistic_min_samples: 2

# Deterministic offline defaults.
knowledge_web: false
knowledge_literature_llm: false
knowledge_deep_literature: false

See all 24 study contexts and when to choose them for exact cna_classifier_sample_set values, including broad_cancer, brain_cns, leukemia and endometrial.

Classifier outputs are written under 05_cna_classifier/, including prepared matrices, classifications, optional recurrence results, knowledge/pathology tables, HTML/PDF reports, clinician summaries, and native_classifier_summary.json.

Keep defaults for an initial analysis. A controlled comparison may add:

fine_bin_kb_illumina: 20
search_radius_bins: 2
min_mapq: 30
min_local_log2_diff_illumina: 0.15
min_bic_gain: 8
permutations: 500
permutation_p: 0.05
accept_rule: p_and_bic

Use a new outdir and report every non-default setting. See Advanced refinement.

YAML rules¶

Use one top-level key: value per line.
Use true and false for booleans.
Use comma-separated text for positional sample/barcode lists.
Matched-normal maps use inline JSON: variant_matched_normals: {"TUMOR01":"NORMAL01"}. Indented nested YAML is unsupported.
Use absolute paths for Docker, Singularity/Apptainer, and shared systems.
Do not use tabs.
Do not embed shell variables such as $PWD; expand them while writing the file.
Use a dedicated outdir for each scientifically distinct configuration.