Illumina configuration¶

Use this page for Illumina settings. For a first run, follow batch setup or explicit FASTQ paths. Each library gets its own copy-number analysis and outputs.

Terminal / headless versions: both the automatic and manual examples below include runnable commands; neither opens browser setup.

Recommended: Automatic Setup¶

Browser setup with sample folders¶

oncotracer setup also accepts a parent directory with FASTQs inside immediate sample subfolders:

01.RawData/
├── SAMPLE_A/
│   ├── SAMPLE_A_flowcell1_L1_1.fq.gz
│   ├── SAMPLE_A_flowcell1_L1_2.fq.gz
│   ├── SAMPLE_A_flowcell2_L4_1.fq.gz
│   └── SAMPLE_A_flowcell2_L4_2.fq.gz
└── SAMPLE_B/
    ├── SAMPLE_B_R1.fastq.gz
    └── SAMPLE_B_R2.fastq.gz

Select 01.RawData and confirm with OK in the system chooser. Setup shows two samples, named after their folders, with all six FASTQs. Keep one library per folder. Each lane must have a matching R1/R2 pair; missing or duplicate mates require correction. Assign Normal/Cancer roles yourself.

Discovery and configuration leave the original files unchanged. The generated samplesheet stores multiple paths as ordered JSON arrays in its fastq_1 and fastq_2 cells. Analysis aligns each lane separately, combines that sample's alignments, and runs its usual QC and downstream analysis once. Single-path samplesheets continue to work.

Arrange the FASTQs¶

Paired-end example:

project/input/illumina_fastq/
├── Patient_A_R1.fastq.gz
├── Patient_A_R2.fastq.gz
├── Patient_B_R1.fastq.gz
├── Patient_B_R2.fastq.gz
├── Control_A_R1.fastq.gz
├── Control_A_R2.fastq.gz
├── Control_B_R1.fastq.gz
└── Control_B_R2.fastq.gz

Single-end files may be named <sample>.fastq.gz. Do not mix layouts in one run.

Create the sample table¶

PROJECT_DIR="$PWD/project"
mkdir -p "$PROJECT_DIR/input/illumina_fastq"

cat > "$PROJECT_DIR/input/illumina_samples.csv" <<'CSV'
sample_name,status
Patient_A,TUMOR
Patient_B,TUMOR
Control_A,NORMAL
Control_B,NORMAL
CSV

sample_name must match the name before _R1/_R2 exactly. The example needs all eight files above. Paste the whole cat block through CSV; it replaces the named CSV if it exists.

Generate the YAML and samplesheet¶

PROJECT_DIR="$PWD/project"

oncotracer auto \
  --mode illumina \
  --reads-folder "$PROJECT_DIR/input/illumina_fastq" \
  --sample-table "$PROJECT_DIR/input/illumina_samples.csv" \
  --config-dir "$PROJECT_DIR/config/illumina" \
  --outdir "$PROJECT_DIR/results/illumina"

Automatic Setup validates every gzip file and writes:

project/config/illumina/
├── auto_params_manifest.tsv
├── illumina.auto.yml
└── illumina.samplesheet.csv

It does not start the analysis. Both auto and setup accept optional --hg38_build PATH or --build_reference; see genome indexes.

Inspect and run¶

PROJECT_DIR="$PWD/project"

sed -n '1,180p' "$PROJECT_DIR/config/illumina/illumina.auto.yml"
sed -n '1,30p' "$PROJECT_DIR/config/illumina/illumina.samplesheet.csv"
oncotracer check --config "$PROJECT_DIR/config/illumina/illumina.auto.yml"

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

cat "$PROJECT_DIR/results/illumina/06_workflow_summary/workflow_summary.txt"

Normal rows are independent samples¶

The status column records the submitted role of each library. It does not select samples for a local reference. Automatic Setup preserves every NORMAL row in the generated samplesheet, and native qDNAseq processes it through the same independent per-sample analysis as every TUMOR row.

OncoTracer does not pool normal rows, subtract their signal from tumor rows, or create a sample-derived panel. Audit qdnaseq_sample_status.json and the per-sample files under 01_samurai_illumina/qdnaseq/ to confirm that every expected tumor and normal completed.

Manual samplesheet¶

This is an alternative to automatic setup. Use it for unusual filenames; retain the exact existing FASTQ paths in the table:

PROJECT_DIR="$PWD/project"
mkdir -p "$PROJECT_DIR/config"

cat > "$PROJECT_DIR/config/illumina.samplesheet.csv" <<CSV
sample,fastq_1,fastq_2,status
Patient_A,"$PROJECT_DIR/input/illumina_fastq/Patient_A_R1.fastq.gz","$PROJECT_DIR/input/illumina_fastq/Patient_A_R2.fastq.gz",tumor
Patient_B,"$PROJECT_DIR/input/illumina_fastq/Patient_B_R1.fastq.gz","$PROJECT_DIR/input/illumina_fastq/Patient_B_R2.fastq.gz",tumor
Control_A,"$PROJECT_DIR/input/illumina_fastq/Control_A_R1.fastq.gz","$PROJECT_DIR/input/illumina_fastq/Control_A_R2.fastq.gz",normal
Control_B,"$PROJECT_DIR/input/illumina_fastq/Control_B_R1.fastq.gz","$PROJECT_DIR/input/illumina_fastq/Control_B_R2.fastq.gz",normal
CSV

For single-end data, retain the four-column header and leave fastq_2 empty for every row.

Manual YAML¶

After creating the manual samplesheet above, save this configuration. It explicitly selects prebuilt hg38 download at run time, matching the automatic route. To build indexes locally instead, set hg38_auto_download: false; see reference choices.

PROJECT_DIR="$PWD/project"
mkdir -p "$PROJECT_DIR/config"

cat > "$PROJECT_DIR/config/illumina.manual.yml" <<YAML
mode: illumina
lpwgs_root: "$PROJECT_DIR/reference"
hg38_auto_download: true
outdir: "$PROJECT_DIR/results/manual_illumina"
illumina_samplesheet: "$PROJECT_DIR/config/illumina.samplesheet.csv"
illumina_analysis_type: solid_biopsy
illumina_caller: qdnaseq
illumina_binsize_kb: 100
run_cna_classifier: false
force: false
YAML

oncotracer check --config "$PROJECT_DIR/config/illumina.manual.yml"
oncotracer run \
  --backend conda \
  --config "$PROJECT_DIR/config/illumina.manual.yml" \
  --dry-run

oncotracer run \
  --backend conda \
  --config "$PROJECT_DIR/config/illumina.manual.yml"

Main Illumina settings¶

Setting	Typical value	Purpose
`illumina_samplesheet`	absolute CSV path	Exact list of FASTQ files, sample names, and tumor/normal status
`illumina_analysis_type`	`solid_biopsy`	Compatibility metadata; native Illumina analysis uses qDNAseq
`illumina_caller`	`qdnaseq`	Illumina CNA caller
`illumina_binsize_kb`	`100`	Initial qDNAseq bin width
`run_cna_classifier`	`false`	Add native cancer-context reports
`force`	`false`	Preserve reusable stages

Pre-run checks¶

This block inspects the automatically generated samplesheet. For the manual route, set SHEET="$PROJECT_DIR/config/illumina.samplesheet.csv" instead.

PROJECT_DIR="$PWD/project"
SHEET="$PROJECT_DIR/config/illumina/illumina.samplesheet.csv"

test -s "$SHEET"
sed -n '1,30p' "$SHEET"
gzip -t "$PROJECT_DIR/input/illumina_fastq/Patient_A_R1.fastq.gz"
gzip -t "$PROJECT_DIR/input/illumina_fastq/Patient_A_R2.fastq.gz"

Use a new YAML and outdir when changing bin size, sample membership, or other scientific settings.