Output files¶

Start here¶

Click Open results in the setup browser, or open results/index.html.
Read the run status to see which samples completed.
Open the result tables and plots for those samples.

For a terminal review, set OUT to the outdir in your YAML:

OUT="/absolute/path/my-study/results"
cat "$OUT/06_workflow_summary/workflow_summary.txt"

If the file is missing, check the path and whether the run has finished. To continue an interrupted run, follow Resume.

Stage indexes use four sections: Primary results, Quality control, Supporting files, and Diagnostics. Open the primary tables/reports first; the remaining sections preserve QC, exports and troubleshooting files. The dashboard explicitly marks stage 05 as disabled when interpretation was not requested. To add it later, see reports for a completed run.

Completed and incomplete samples¶

The terminal, browser, results dashboard and final report show the same counts at the end of a finalized run. For example:

Samples: completed 6/8; incomplete 2/8.
CNA: completed 8/8; incomplete 0/8.
Small variants: completed 6/8; incomplete 2/8.
S7: Small variants (partial_failure)
S8: Small variants (not_started)

A sample is complete only when every requested analysis finishes. An aligned BAM alone does not make the sample complete. Incomplete includes failed, interrupted, pending and unavailable assessments, including missing CpG calls or classifier probes. Explicitly inapplicable work is counted separately. If all samples finish but a cohort output fails, that remaining cohort work is still listed and the run retains its failure status.

The saved workflow_summary.json, native_run_manifest.json and final_report.json include a completion object with counts, sample names and remaining branches. The existing completed_samples field still describes CNA; use completion for the whole analysis.

An early stop can happen before counts are finalized. The browser then says counts are unavailable for that attempt; it never presents an older run's totals as current. Continue the project to validate retained stages and finish the remaining work. Changing the parallel sample allocation does not mark work as complete or bypass those checks.

Which result is authoritative?¶

Stage	Main question	Status
`01_samurai_illumina/` or `01_samurai_ont/`	What did alignment and the initial CNA caller produce?	Upstream caller/QC output; important provenance, but refinement follows
`02_bam_refinement/`	Where are the final refined segment boundaries and bins?	Authoritative refined segmentation
`03_cna_codification/`	Which CNA events and cytogenomic descriptions does OncoTracer report?	Authoritative machine-readable OncoTracer CNA results
`04_cna_custom_plots/`	Where are CNA plots?	Derived presentation; use stage 03 for exact calls
`05_cna_classifier/`	Where are classifier, clinician and knowledge/LLM reports?	Optional research interpretation and its supporting evidence
`06_workflow_summary/`	What completed, and how do the saved findings compare?	Combined report, completion status and provenance; source results retain their own status
`07_methylation/`	What optional ONT modified-base/classifier result and provenance were produced?	Independent optional research result; review its status before predictions
`08_variants/`	Which SNV/indel candidates and annotations were produced?	Optional caller-specific VCFs and evidence; review calling, filtering and annotation status separately

Do not report temporary alignment/caller intermediates or .oncotracer-native/ ledger files as scientific results. Preserve the ledger and trace for audit, but use stage 02/03 for CNA values and stage 08 for variant calls.

Stage 01: alignment and initial caller¶

Illumina¶

find "$OUT/01_samurai_illumina" -maxdepth 2 -type f | sort | sed -n '1,80p' # inventory
sed -n '1,8p' "$OUT/01_samurai_illumina/qdnaseq/all_segments.seg"          # initial qDNAseq segments
find "$OUT/01_samurai_illumina/alignment" -maxdepth 1 -name '*.bam' -print # aligned BAMs

Review the duplicate metrics in markduplicates/, qdnaseq/qdnaseq_sample_status.json, and the qDNAseq plots before interpreting calls. A standalone FastQC or MultiQC HTML report is not generated by this workflow.

Independent tumor and normal outputs¶

Native qDNAseq writes one set of files for every QC-valid samplesheet row, including rows marked normal:

01_samurai_illumina/qdnaseq/
├── all_segments.seg
├── all_calls.seg
├── qdnaseq_sample_status.json
├── qdnaseq_summary_mqc.txt
├── bins/
│   └── <sample>_markdup_bins.bed
├── segments/
│   ├── <sample>_.seg
│   └── <sample>.calls.seg
└── plots/
    └── <sample>_markdup_segment_plot.pdf

The samplesheet preserves whether each input was submitted as tumor or normal. That status does not pool, average, or subtract samples: no local sample-derived panel is created. Audit independent completion as follows:

SHEET="/absolute/path/to/samplesheet.csv" # use illumina_samplesheet from your YAML
QDNA="$OUT/01_samurai_illumina/qdnaseq"

cat "$SHEET"
cat "$QDNA/qdnaseq_sample_status.json"
find "$QDNA/bins" "$QDNA/segments" "$QDNA/plots" -maxdepth 1 -type f -print | sort

qdnaseq_sample_status.json is authoritative for caller completeness. A failed or mathematically invalid sample is recorded there and excluded from aggregate tables without being repurposed as a reference for the remaining samples.

ONT¶

find "$OUT/01_samurai_ont" -maxdepth 3 -type f | sort | sed -n '1,100p' # inventory
if test -s "$OUT/01_samurai_ont/results/ichorcna/ichorcna_sample_status.json"; then
  cat "$OUT/01_samurai_ont/results/ichorcna/ichorcna_sample_status.json" # ichorCNA status
  sed -n '1,8p' "$OUT/01_samurai_ont/results/ichorcna/segments_logR_corrected_gistic.seg"
fi
if test -s "$OUT/01_samurai_ont/qdnaseq/all_segments.seg"; then
  cat "$OUT/01_samurai_ont/qdnaseq/qdnaseq_sample_status.json"        # qDNAseq status
  sed -n '1,8p' "$OUT/01_samurai_ont/qdnaseq/all_segments.seg"          # qDNAseq segments
fi
find "$OUT/01_samurai_ont/bam" -maxdepth 1 -name '*.bam' -print        # aligned BAMs

For ichorCNA, ichorcna_sample_status.json is authoritative for caller completeness. For qDNAseq, the equivalent record is qdnaseq_sample_status.json. A failed or mathematically invalid sample is recorded there and excluded from aggregate caller tables and downstream reports; later viable samples continue. workflow_summary.json reports partial_failure and lists both completed and failed samples. Nested partial caller files remain available for diagnosis but are not published as complete top-level inputs. For solid-biopsy qDNAseq, use a separate outdir; its initial caller output is 01_samurai_ont/qdnaseq/.

Use 06_workflow_summary/workflow_summary.json for the selected, completed and failed sample lists. Use .oncotracer-native/trace.tsv and stage logs to investigate a failure. Do not assume an absent sample is normal or successfully analyzed.

Stage 02: refined segmentation¶

The dataset subdirectory is normally illumina_qdnaseq_100kb, ONT_ichorcna_500kb, or an explicit ONT qDNAseq name such as ONT_qdnaseq_100kb, depending on the YAML. List it rather than guessing:

find "$OUT/02_bam_refinement" -mindepth 1 -maxdepth 1 -type d -print
sed -n '1,8p' "$OUT"/02_bam_refinement/*/04_final_results/final_segments.tsv
sed -n '1,8p' "$OUT"/02_bam_refinement/*/01_tables/boundary_refinement_statistics.csv

Use 04_final_results/final_segments.tsv as the primary refined segment table. 01_tables/ and 03_consolidated/ preserve detailed calculations and comparisons for audit. 02_samurai_compatible/ is an interoperability representation, not a second independent call set.

Refinement uses zero-based, half-open intervals internally: [100, 200) contains 100 bases. Final segment TSV/BED files, refined bins, and boundary statistics use this convention. Compatibility SEG files use one-based, closed intervals: the same region is 101–200. Each new dataset includes coordinate_system.json documenting its inputs and outputs.

Gaps between prior segments retain both original endpoints and are excluded from refinement. A retained boundary leaves the original segments unchanged. Accepted shifts must remain inside the adjoining segments and cannot collapse or reorder them. Rejected proposals and gap widths appear in the boundary statistics. Search windows stay within the two adjoining segments.

Older outputs without this metadata may contain gaps filled at their midpoint and mixed start-coordinate conventions. Rerun into a new output directory with this corrected version; keep earlier results separately for comparison. Do not mix older and corrected downstream CNA tables or reports.

Key files:

File	Use
`04_final_results/final_segments.tsv`	Refined segment coordinates and values
`04_final_results/final_segments.bed`	BED representation for genome tools
`04_final_results/refined_bins_boundary_bp_difference.csv`	Per-bin boundary difference audit
`01_tables/sample_refinement_summary.csv`	Per-sample refinement counts/status
`critical_outputs_manifest.csv`	Inventory of required outputs

Stage 03: final CNA tables¶

sed -n '1,12p' "$OUT/03_cna_codification/cna_events.tsv"
sed -n '1,12p' "$OUT/03_cna_codification/cna_cytogenomic_notation.tsv"
wc -l "$OUT/03_cna_codification/cna_events.tsv" "$OUT/03_cna_codification/cna_cytogenomic_notation.tsv"

cna_events.tsv is the main event-level result for downstream analysis.
cna_cytogenomic_notation.tsv provides the corresponding cytoband-oriented descriptions.
input_bed_files.tsv and input_cna_files.tsv record the exact inputs used by codification.

A table containing only a header can be a valid CNA-flat result; confirm the sample in the notation/QC outputs rather than assuming the workflow failed.

Stage 04: CNA plots¶

find "$OUT/04_cna_custom_plots" -maxdepth 2 -type f | sort
xdg-open "$OUT/04_cna_custom_plots/cna_per_sample_pages.pdf"                  # one page per sample
xdg-open "$OUT/04_cna_custom_plots/cna_log2_ratio_profiles_all_samples.pdf"   # cohort profiles

On a headless server, copy PDFs to your workstation. Common outputs include genome overview, event burden/counts, recurrent cytobands, gene-panel frequency, per-sample pages, and log2-ratio profiles. PNG/SVG files are convenient for slides; the TSV tables remain the source for exact values.

Stage 05: classifier reports and supporting evidence¶

This directory is produced by run_cna_classifier: true or the public oncotracer reports command for a completed native CNA run.

sed -n '1,8p' "$OUT/05_cna_classifier/tables/classification/cna_patient_classification.tsv"
sed -n '1,8p' "$OUT/05_cna_classifier/evidence/sample_knowledge_summary.tsv"
sed -n '1,8p' "$OUT/05_cna_classifier/diagnostics/pathology/pathology_concordance.tsv"

Open 05_cna_classifier/final_report.pdf or final_report.html for the complete CNA interpretation, and clinician_report.pdf or clinician_report.html for the short summary. With one sample, these are the only sample report copies. With multiple samples, the root PDFs combine the cohort and individual reports are under samples/<sample>/; the root HTML pages list those samples.

Path beneath `05_cna_classifier/`	Contents
`cohort_report.html`	Cohort plots and classifier overview
`figures/{summary,drivers,cohort}/{png,pdf}/`	Grouped plots and export formats
`tables/classification/`	Classification results and related tables
`tables/report_index.tsv`	One sample-to-report mapping
`evidence/`	Literature text, references, generation metrics and model trials
`diagnostics/`	Prepared inputs, GISTIC/pathology internals, caches and other supporting files
`layout_manifest.json`	Original-to-canonical paths and artifact checksums
`.reports/`	Report invocation history and separate resume ledger

The evidence labels distinguish accepted model drafts, retrieved-text fallbacks and built-in catalog text. See LLM-assisted reports. The analysis-wide report in 06_workflow_summary/final_report.html also includes available methylation results and each branch's completion status.

To physically organize reports from an older release without running models, retrieval, or analysis:

oncotracer reports --config /absolute/path/project/config/run.yml --organize-only

This requires the unchanged original config and an authenticated completed CNA run. Existing report histories and the original native manifest are preserved; layout_manifest.json records moves and redundant copies. oncotracer results refreshes navigation for both old and new layouts without moving report files.

Stage 07: optional ONT methylation¶

This directory exists when methylation was requested, using POD5 or existing modified-base BAMs:

cat "$OUT/07_methylation/methylation_status.json"
cat "$OUT/07_methylation/methylation_provenance.json"
find "$OUT/07_methylation" -maxdepth 3 -type f | sort | sed -n '1,120p'

Start with methylation_status.json. Each sample is complete, no_cpg_modifications, no_classifier_probes (MARLIN), or failed. A zero-call sample is not sent to the classifier. For MARLIN, covered_classifier_probes counts the supplied probes with data; zero means no prediction was made. methylation_provenance.json records input inventories, tools, models, and device choice. See the resource reference for exact provenance fields.

With methylation_only: true, cna_status is not_requested; absence of CNA outputs is expected.

Methylation and CNA are independent branches: stage 07 remains valid when CNA fails, and stages 01–06 may remain valid when methylation is incomplete. In either partial case, the final command exits nonzero and workflow_summary.json records cna_status, methylation_status, and the relevant sample lists. Do not present a missing classifier output as a negative classification.

Stage 08: optional variants¶

Open 08 · Small variants in the dashboard. Start with the status file:

python3 -m json.tool "$OUT/08_variants/variant_status.json"

Each sample/caller has its own VCF and evidence table under 08_variants/samples/. Successful calling, zero calls, skipped annotation and failed calling are different outcomes. See the variant output table for filenames and meanings.

For a CNA run, inspect these files. They are not expected for a variants-only or methylation-only run. File existence alone does not establish success; check the summary first.

test -s "$OUT/06_workflow_summary/workflow_summary.txt"                # summary exists
test -s "$OUT/03_cna_codification/cna_events.tsv"                     # event table exists
test -s "$OUT/03_cna_codification/cna_cytogenomic_notation.tsv"       # notation table exists
test -s "$OUT/04_cna_custom_plots/cna_per_sample_pages.pdf"           # plots exist
find "$OUT" -type f -name '*.command.err' -size +0c -print             # review any non-empty task stderr files

Non-empty standard error is not automatically a failure--many tools write progress there--but it must be reviewed. Preserve the YAML, samplesheet, oncotracer provenance --json, input/reference checksums, container digest or explicit package specifications for every environment used, and workflow summary with any released result.