Skip to content

Guide to Results Interpretation

The pipeline produces a rich hierarchy of artefacts for each patient course. This document explains where to find them, how to interpret key columns, and which sanity checks you should perform before downstream analyses.

1. Course Directory Overview

Each course lives under Data_Snakemake/<patient>/<course>/ and contains:

DICOM/CT/…                          # planning CT slices
DICOM/MR/…                          # MR slices copied directly under the course
MR/<SeriesInstanceUID>/
    DICOM/…                         # MR source series
    NIFTI/<name>.nii.gz             # compressed NIfTI + metadata JSON
    Segmentation_TotalSegmentator/
        total_mr--<roi>.nii.gz      # MR binary masks
        <name>--total_mr.dcm        # MR RTSTRUCT
Segmentation_TotalSegmentator/…     # CT TotalSegmentator outputs
Segmentation_CustomModels/<model>/… # nnUNet masks (e.g. cardiac_STOPSTORM, HN_lymph_nodes)
Segmentation_Original/…             # manual RTSTRUCT converted to masks (if available)
RS.dcm / RS_auto.dcm / RS_custom.dcm
radiomics_ct.xlsx
MR/radiomics_mr.xlsx
dvh_metrics.xlsx
fractions.xlsx
metadata/case_metadata.xlsx
qc_reports/*.json

RTSTRUCT quick reference

File Origin What it represents Primary consumers
RS.dcm Copied verbatim during the organize stage. Untouched physician RTSTRUCT (manual contours + beam associations). Regulatory archive, DVH/radiomics comparisons against manual ROIs.
RS_auto.dcm Generated from TotalSegmentator CT masks. Auto contours aligned to the full CT grid. Auto-contour import, DVH/radiomics when automation is acceptable.
RS_auto_cropped.dcm Created by anatomical_cropping.py when ct_cropping.enabled: true; clamp extents live in cropping_metadata.json. Same ROIs as RS_auto.dcm, but intersected with the systematic cropping box so voxel counts match trimmed images. Radiomics/DVH/QC when ct_cropping.use_cropped_for_* toggles are enabled (cropped ROIs marked as INFO in QC reports).
RS_custom.dcm Built by structure_merger.py by combining manual, auto, and Boolean definitions from custom_structures*.yaml. Clean superset with derived ROIs (bowel bag, merged bones, etc.) plus provenance tags. Default source for DVH, CT/MR radiomics (Custom source), robustness perturbations.

Aggregated artefacts reside in Data_Snakemake/_RESULTS/:

  • dvh_metrics.xlsx
  • radiomics_ct.xlsx, radiomics_mr.xlsx
  • fractions.xlsx
  • case_metadata.xlsx
  • qc_reports.xlsx

2. Radiotherapy Metrics (DVH)

File: dvh_metrics.xlsx

Key columns:

Column Meaning
ROI_Name Clean display name (cropped structures append __partial).
ROI_OriginalName Raw name from RTSTRUCT / segmentation output.
Segmentation_Source Provenance: Manual, AutoRTS_total, AutoRTS_total_mr, Merged, Custom, CustomModel:<name>.
structure_cropped True when the mask touches the image boundary (quality flag).
DmeanGy, DmaxGy, … Standard DVH metrics.
dose_summary_basis RTSTRUCT mean and maximum: binned, or unbinned_subcentigray when the histogram has at most one bin or its maximum is zero. The latter uses supported samples in the same raster mask and working dose grid. NIfTI-mask mean and maximum already use unbinned samples; this field is empty for those rows.
row_status, dvh_nonmeasurement_class not_computed for declared empty, nonvolumetric, degenerate or nonmeasurable automatic sliver geometry. These rows have no dose measurement.
D0.03ccGy, D2ccGy Dose received by the hottest 0.03 cm³ or 2 cm³, respectively, in Gy. Values are bounded by Dmin and Dmax.
D0.03cc_status, D2cc_status available when computable; roi_below_0.03cc or roi_below_2cc when measured volume is too small. Incomplete dose-grid coverage propagates its coverage status and leaves the whole-ROI dose empty.

An automatic ROI whose closed contour items each have fewer than three distinct points has dvh_nonmeasurement_class = nonmeasurable_auto_sliver. This is expected nonmeasurement. Automatic-source evidence is bound to the RTSTRUCT bytes. AutoRTS uses metadata/rs_auto_origin.json; selected custom model outputs record their producer source and file hash. dvh_nonmeasurement_evidence records the contour count, each distinct-point count, source, origin and file hash. Manual or unverified area-less geometry remains degenerate_contours. An ROI with an area-bearing polygon and stray area-less items is assessed using its area-bearing polygons. Malformed coordinates and mixed open/closed geometry remain unresolved.

Sub-centigray mean and maximum retain positive sample values below 0.01 Gy. An unbinned maximum of zero means every supported in-mask sample is zero. Samples are dose-grid values inside the raster mask; they do not establish a continuous-dose maximum between samples. Histograms with more than one bin and a positive maximum retain the binned metrics. Dose-volume quantiles and DVH curves remain histogram-derived.

Recommended checks

  1. Filter out __partial structures unless your analysis explicitly handles cropped contours.
  2. Cross-check Segmentation_Source to ensure you understand which model produced each ROI.
  3. Review _RESULTS/qc_reports.xlsx for courses marked WARNING or FAIL.

3. Radiomics Outputs

CT (radiomics_ct.xlsx)

  • Parameters from rtpipeline/radiomics_params.yaml.
  • Includes manual, TotalSegmentator, custom structures, and nnUNet outputs.
  • Important columns: roi_name, segmentation_source, structure_cropped, feature columns (GLCM, GLRLM, etc.).

MR (MR/radiomics_mr.xlsx)

  • Parameters from rtpipeline/radiomics_params_mr.yaml.
  • Rows correspond to masks produced by TotalSegmentator total_mr.
  • Columns: roi_name, series_uid, segmentation_source (AutoTS_total_mr), feature columns.

Aggregated copies are in _RESULTS/radiomics_ct.xlsx and _RESULTS/radiomics_mr.xlsx with additional patient_id / course_id context.

Usage tips * Drop or flag rows where structure_cropped == True. * When merging CT and MR features, include modality and segmentation_source to avoid mixing sources inadvertently.

4. Segmentation Manifests

  • Segmentation_TotalSegmentator/<base>/manifest.json – CT segmentation manifest listing models and masks.
  • MR/<series>/Segmentation_TotalSegmentator/manifest.json – MR counterpart for total_mr.
  • Segmentation_CustomModels/<model>/manifest.json – nnUNet model manifest (structures + originating networks).

These files are useful when auditing which masks exist, the order they were combined in, or updating post-processing pipelines.

5. MR-Specific Layout

For every referenced MR series:

MR/<SeriesInstanceUID>/DICOM/…                     # original slices
MR/<SeriesInstanceUID>/NIFTI/<name>.nii.gz         # compressed volume
MR/<SeriesInstanceUID>/NIFTI/<name>.metadata.json  # modality + linkage
MR/<SeriesInstanceUID>/Segmentation_TotalSegmentator/
    total_mr--<ROI>.nii.gz
    <name>--total_mr.dcm

The metadata JSON contains:

  • modality: "MR"
  • series_instance_uid
  • nifti_path/source_directory
  • Timestamp of conversion

Radiomics results for the whole course are consolidated into MR/radiomics_mr.xlsx.

6. Quality Control

  • qc_reports/*.json – per-course, structured QC results (overall_status, checks.structure_cropping, etc.).
  • _RESULTS/qc_reports.xlsx – flattened version for cohort summaries.
  • metadata/custom_structure_warnings.json – lists composite structures built from missing sources or cropped inputs (look for __partial suffixes).

Recommended practice * Investigate any course with overall_status != PASS. * When structure_cropping lists critical OARs or targets, consider excluding them or regenerating masks with manual corrections.

7. Anonymisation Footprint

If you run scripts/anonymize_pipeline_results.py, the anonymised tree mirrors the structure above with remapped identifiers. Keep the generated key file secure; it restores patient/course mappings if needed.

8. Quick Checklist Before Analysis

  1. Course completeness – verify expected CT/MR series and check QC status.
  2. Segmentation provenance – filter by Segmentation_Source to separate manual vs automated contours.
  3. Partial structures – remove or flag __partial entries in DVH and radiomics tables.
  4. MR availability – confirm MR/<series>/Segmentation_TotalSegmentator/ exists before using MR radiomics.
  5. Custom models – inspect Segmentation_CustomModels/<model>/manifest.json to confirm network and label names.

With these checks you can confidently use the pipeline outputs for statistical modelling, quality monitoring, or downstream AI experiments.