Set up your own data¶

Install once. Explore the demo or SSH/headless guide.

1. Configure interactively (recommended)¶

Fresh or FFPE:

oncotracer --interactive --backend conda
nextflow run main.nf --interactive --backend conda

Keep the terminal open. Use its URL with the # session code; ports are selected automatically. See concurrent projects. Browse computer selects inputs. Empty input folders display No sequencing files found. Check your paths.

Choose Illumina or ONT, then Fresh or FFPE from your specimen records. Illumina accepts sample folders with paired lanes. ONT accepts named libraries, each with fastq_pass; legacy barcodes and single ligation libraries remain supported.
Assign samples to Normal or Cancer using cards or dropdowns. Rename them if needed. Unassigned samples are excluded. CNA controls are analyzed independently, without pooling or subtraction; custom tags require a study/control role.
Review settings. Choose resources and a caller. QDNAseq defaults to 100 kb; ONT ichorCNA uses 500 kb. Both support ONT normal/control labels. GISTIC needs at least two assigned samples.
Select tools and a new or existing project folder. Choose your installed Conda or Docker backend. Keep automatic reference download.
Click Save configuration and check, resolve any check errors, then Run analysis. Follow progress and open results here.

Settings use PROJECT/config/run.yml; Illumina also gets config/samplesheet.csv. Saving again overwrites settings and assignments, backing them up in config/backups/. Save/check detects tools and records their paths. Results and references stay. Stop analysis asks Delete incomplete run? Yes deletes the selected project; No keeps it. Both close the dialog and return to setup.

Terminal alternative:

oncotracer setup --terminal --backend conda --run

In terminal setup, add --variant-specimen-type fresh or ffpe to record preservation, including for CNA-only projects.

Optional analyses¶

Enable variants to choose compatible callers for the selected preservation. ONT methylation requires modBAMs or raw POD5 and classifier resources; FASTQs alone lack methylation calls. Docker methylation is unavailable. Reports and paper panels are optional.

Prefer terminal questions?

Add --terminal; Enter accepts the displayed default. Finish with save or run. Example:

CNA bin size (kb) (1/5/10/15/30/50/100/500/1000) [100]:

Use --manual for individual files or single-end Illumina. A project cannot mix single-end and paired-end Illumina libraries.

Illumina¶

oncotracer setup --terminal --project /work/illumina-study --mode illumina \
  --input-folder /data/illumina

ONT¶

oncotracer setup --terminal --project /work/ont-study --mode ont \
  --input-folder /data/run/fastq_pass

2. Check and run your platform¶

Already clicked Run analysis? Skip these commands. Otherwise, check and run your saved project below. Resolve check errors first.

Show terminal check/run commands

Illumina¶

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

ONT¶

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

These examples use Conda. Docker projects keep their saved image; use --backend docker. See execution backends for other options.

3. Review results and resume¶

Open results from the browser, or read the run status:

sed -n '1,100p' /absolute/path/to/my-study/results/06_workflow_summary/workflow_summary.txt

To resume:

oncotracer --interactive --project /absolute/path/to/my-study

Select the output project and Load saved settings and check. Choose the CPU/RAM budget and concurrent samples, then Apply resources and check before Run. Multi-sample processing · Docker recovery.

Optional: reuse prepared genome indexes¶

Run downloads prebuilt indexes under PROJECT/reference/: about 8.0 GiB for Illumina or 9.7 GiB for ONT. Completed downloads are reused. Choose Reuse a prepared OncoTracer reference to share an existing build.

Show setup commands using an existing reference

Use these for a new project. Replace /data/shared-reference with your prepared reference parent or its references/samurai_hg38 folder.

Illumina with an existing reference¶

oncotracer setup --project /work/illumina-reuse --mode illumina \
  --input-folder /data/illumina --hg38_build /data/shared-reference

ONT with an existing reference¶

oncotracer setup --project /work/ont-reuse --mode ont \
  --input-folder /data/run/fastq_pass --hg38_build /data/shared-reference

The browser prefills these paths; assign samples, save/check, then run. Illumina needs BWA indexes; ONT needs minimap2.

Terminal equivalents (questions followed by validation and execution):

oncotracer setup --terminal --run --backend conda \
  --project /work/illumina-reuse --mode illumina \
  --input-folder /data/illumina --hg38_build /data/shared-reference

oncotracer setup --terminal --run --backend conda \
  --project /work/ont-reuse --mode ont \
  --input-folder /data/run/fastq_pass --hg38_build /data/shared-reference

--hg38_build without a path selects automatic download. Replace it with --build_reference to build locally using more RAM, disk and time. See reference details.

Optional: scripted setup without prompts¶

--non-interactive uses supplied flags/defaults and stops on missing required answers. For browser setup, use the earlier browser commands; for folder-selection questions, use --terminal.

Show one-library Illumina and multi-barcode ONT examples

Illumina¶

oncotracer setup --non-interactive \
  --project /work/illumina-scripted --mode illumina --analysis cna --backend conda \
  --sample-name sampleA \
  --fastq-1 /data/illumina/sampleA_R1.fastq.gz \
  --fastq-2 /data/illumina/sampleA_R2.fastq.gz --threads 4
oncotracer check --config /work/illumina-scripted/config/run.yml
oncotracer run --backend conda --config /work/illumina-scripted/config/run.yml

Omit --fastq-2 for single-end reads.

ONT¶

oncotracer setup --non-interactive \
  --project /work/ont-scripted --mode ont --analysis cna --backend conda \
  --reads-folder /data/run/fastq_pass \
  --barcodes barcode01,barcode02 --sample-names sampleA,sampleB --threads 4
oncotracer check --config /work/ont-scripted/config/run.yml
oncotracer run --backend conda --config /work/ont-scripted/config/run.yml

Check and run the saved config/run.yml.

Illumina: multiple libraries¶

Open the mock example: two tumors and one normal. It includes a directory tree, sample table, CSV template, and browser/terminal commands.

The original two-library example follows. Replace paths; cat > overwrites its CSV.

mkdir -p "/data/illumina"
cat > "/data/illumina/samplesheet.csv" <<'CSV'
sample,fastq_1,fastq_2,status
sampleA,"/data/illumina/sampleA_R1.fastq.gz","/data/illumina/sampleA_R2.fastq.gz",tumor
sampleB,"/data/illumina/sampleB_R1.fastq.gz","/data/illumina/sampleB_R2.fastq.gz",tumor
CSV

Each row is one library; leave fastq_2 empty for single-end reads:

oncotracer setup --non-interactive --project /work/illumina-batch --mode illumina --analysis cna \
  --samplesheet /data/illumina/samplesheet.csv --threads 4 --backend conda
oncotracer check --config /work/illumina-batch/config/run.yml
oncotracer run --backend conda --config /work/illumina-batch/config/run.yml

Results stay separate per sample. Batch setup can generate CSVs from filenames and configure ONT tumor/normal groups.