Output directory and file schema¶

The names below come from the current worker, aggregation code, and workflow fixtures. Optional outputs are marked.

OUTPUT/
├── START_HERE.html                         # generated by report
├── tumorquantai_report.json                # machine-readable report
├── RUN_SUMMARY.txt                         # compact human-readable status
├── workflow_aggregation_manifest.csv
├── workflow_metadata/
│   ├── slides.tsv
│   ├── slides.json
│   ├── tumorquantai_run.json               # main command/provenance
│   ├── nextflow.log                         # canonical local execution log
│   ├── nextflow_report_<run>.html
│   ├── nextflow_trace_<run>.tsv
│   └── nextflow_timeline_<run>.html
├── <sample>/
│   ├── slide.log
│   ├── cell_types/
│   │   ├── class_counts.csv
│   │   ├── cell_type_coordinates.csv       # or .csv.gz
│   │   ├── cell_type_coordinates.npy
│   │   ├── cell_type_coordinates.json      # optional
│   │   └── cell_types_qupath.json           # optional
│   ├── overlays/
│   │   ├── overview_with_zoom_box.png
│   │   ├── zoom_overlay_celltypes.png
│   │   ├── celltypes_overview_and_zoom.png
│   │   └── celltypes_overview_and_zoom.pdf
│   ├── paper_figures/
│   │   ├── celltypes_paper_figure.png
│   │   ├── celltypes_paper_figure.pdf
│   │   ├── celltypes_paper_figure_legend.txt
│   │   ├── celltype_counts_barplot.png
│   │   └── celltype_counts_barplot.pdf
│   ├── plotting_metadata/
│   │   ├── detected_cell_types.csv
│   │   ├── detected_cell_types.json
│   │   └── cell_type_palette.json
│   └── summary/
│       ├── run_metadata.json
│       └── summary.json                    # completion marker; written last
└── aggregated_celltypes/
    ├── celltype_counts_by_sample.csv
    ├── celltype_fractions_by_sample.csv
    ├── celltype_counts_long.csv
    ├── sample_aggregation_audit.csv
    └── aggregation_summary.json

The public one-slide quickstart stores this ordinary run layout beneath OUTPUT/smoke-results/. Its top-level START_HERE.html links into that nested run.

class_counts.csv columns are class_id, class_name, and count. Coordinate CSV columns are cell_id, class_id, class_name, centroid_x, centroid_y, bbox_x0, bbox_y0, bbox_x1, and bbox_y1. Coordinates are level-0 pixels.

Count/fraction matrices use cell types as rows and completed samples as columns. Failed/incomplete samples have no numeric column and remain in sample_aggregation_audit.csv. Fractions for a nonempty sample sum to one. Sampled counts are not whole-slide estimates.

Optional sampled-patch, QC-patch, pyramidal-input, and JSON exports have their own manifests/integrity records. summary.json is not published until required core and requested optional artifacts pass validation. For a completion summary that records the current paper-figure layout version, the per-sample celltypes_paper_figure_legend.txt is required and missing or empty text prevents completion/resume reuse. The layout version remains separate from the scientific worker processing signature, so direct reuse of the same persistent worker output retains the earlier contract for a legacy completed summary without a layout version. Nextflow cache reuse is a separate layer: staged worker code and configuration also enter the task key, and a software upgrade can invalidate PROCESS_SLIDE and re-enter HistoPLUS inference. Inspect the top-level --resume --dry-run plan for Nextflow -resume and the original work directory; preserve the exact software/work cache or select --cpu if reuse is uncertain. Use a new output directory or a deliberate rerun to generate the redesigned figure from a legacy result.

Raw TIFF patch and paper-figure outputs¶

The tumorquantai --patches ... --paper-figures --output ... route keeps the same completion and failure semantics as the ordinary workflow. Each completed TIFF patch input has a per-sample directory. Full patch processing means that 100% of the discovered TIFF patch inputs are scheduled; it does not turn patch counts into patient-level, tumor-level, or whole-slide estimates.

The main paper figure preserves its established filename and uses a compact full-width layout inspired by the visual grammar of STTT 2026 Figure 6 and Figure 7: a, all detected HistoPLUS cell-type counts and within-input percentages; b, the scale-calibrated overview and selected ROI; and c, the enlarged QC inset with the configured cell-type overlay and its own scale bar. The artwork contains no sample title or explanatory paragraph. Those details are written to the adjacent text legend. Layout inspiration is not evidence of equivalent methods, performance, or biological findings.

Use the Nature Research figure specifications as a separate submission-preparation checklist; the generated files are not a guarantee of compliance with a journal's production requirements.

Review these visual exports for every completed patch:

Path	Purpose
`<sample>/overlays/celltypes_overview_and_zoom.png`	Whole-input overview, connected QC zoom, configured cell-type overlay, and scale bars
`<sample>/overlays/celltypes_overview_and_zoom.pdf`	PDF form of the overview/QC figure
`<sample>/paper_figures/celltypes_paper_figure.png`	Compact raster figure: cell-type statistics at left, overview/QC stacked at right
`<sample>/paper_figures/celltypes_paper_figure.pdf`	Vector-text PDF form of the same compact layout
`<sample>/paper_figures/celltypes_paper_figure_legend.txt`	Sample ID, panel descriptions, count source/denominator, scale/ROI/model provenance, and caveats
`<sample>/paper_figures/celltype_counts_barplot.png`	Standalone detected-cell count chart
`<sample>/paper_figures/celltype_counts_barplot.pdf`	PDF form of the count chart
`<sample>/plotting_metadata/detected_cell_types.csv`	Figure source values
`<sample>/plotting_metadata/cell_type_palette.json`	Class-to-color provenance
`<sample>/summary/run_metadata.json`	Resolved MPP/model/device plus paper-layout version and portable figure/legend paths
`<sample>/summary/summary.json`	Validated completion record, written last

When QC-patch export is enabled, <sample>/qc_patches/patch_manifest.csv maps each QC region to its rgb.png, overlay.png, class_counts.csv, and metadata.json. The ordinary cell_types/ coordinates and counts and the cohort aggregation audit remain authoritative numeric outputs.

For mixed-scale TIFF collections, status JSON preserves the distinct per-input scales in source_mpp_values and records source_mpp_provenance. The human-readable tumorquantai status output, START_HERE.html, and the text run summary display those MPP values and their per-input embedded TIFF metadata provenance.

Paper figures report HistoPLUS cell-type predictions. They do not score breast markers, infer receptor status, or establish co-expression across separate stains, and they do not establish biological or clinical validity. Review scale, overlay alignment, tissue content, artifacts, class plausibility, completion, and the aggregation audit before using any numeric table. If breast IHC cases are arranged into categories, name them computational receptor-profile pre-score groups. Do not present them as diagnoses, histologic or intrinsic subtypes, treatment recommendations, or independent pathologist results.

The public raw-only breast-IHC example dataset is available under CC BY 4.0 at Zenodo record 21797920, with dataset DOI 10.5281/zenodo.21797920. Its 55 files comprise 51 case archives containing 1,901 TIFF patches plus four auxiliary files: one manifest bundle, one packaging report, and two checksum rosters (74,958,557,152 bytes total). Paper and QC figures are local workflow outputs and are not part of the deposit. This DOI identifies the breast-IHC dataset, not the TumorQuantAI software or the lymphoma dataset.

Package-native breast IHC outputs¶

tumorquantai ihc quantify creates a self-contained research result:

<ihc-result>/
├── START_HERE.html
├── case_reports/<case_alias>.html
├── tables/
│   ├── tumorquantai_marker_values.csv
│   ├── case_marker_measurements.csv
│   ├── patch_measurements.csv
│   └── unavailable_patches.csv
├── patches/<case_alias>/<patch_alias>/
│   ├── measurement.json
│   ├── qc_overlay.png
│   └── cell_measurements.csv.gz
└── workflow_metadata/ihc_run.json

tumorquantai_marker_values.csv is the clearest case-level export: one row per public alias with color-checked ER, PR, and Ki-67 percentages, applicable H-scores, the HER2 membrane-proxy pre-score, segmented-object counts, and QC status. Each nuclear marker also has an unconstrained_dab_percent audit column that exposes what the inverse HED matrix would have reported before the expected-brown color check. It is not a second prediction. A missing marker is blank with unavailable QC status, not zero.

IHC schema v2 adds dab_color_model, unconstrained DAB counts/percentages and H-score, and unconstrained_mean_dab_od in optional cell tables. See the IHC v1-to-v2 migration note.

The private identity resolution happens before comparison. Neither the direct release-to-workbook mapping nor its source identifiers are copied into an IHC result or agreement report. See breast-IHC case linkage and privacy for the complete chain and access classification.

tumorquantai ihc compare adds a controlled agreement directory:

<agreement>/
├── AGREEMENT_REPORT.html
├── concordance_metrics.csv
├── dab_color_check_impact.csv
├── kappa_summary.csv
├── contingency_tables.json
├── case_concordance_values_pseudonymized.csv
├── case_comparison_pseudonymized.csv
└── agreement_summary.json

concordance_metrics.csv is aggregate and contains kappa plus bootstrap intervals, observed and expected agreement, positive/negative specific agreement, error and bias metrics, Pearson and Spearman correlations, Lin's CCC, and both category margins. The two case-level comparison CSVs remain pseudonymized health data even though their direct identifiers were removed; keep the whole agreement directory under controlled access unless a reviewed aggregate-only file is copied out.

When v2 unconstrained audit columns are present, dab_color_check_impact.csv adds aggregate ER/PR checked-versus-unconstrained kappa and intervals, confusion counts, sensitivity, specificity, predictive values, balanced accuracy, ROC AUC, MAE/RMSE, and rank/concordance correlations. It contains no case aliases. It is a method sensitivity analysis, not an independent validation.

Package-native colon CD3/CD8/CK20 outputs¶

tumorquantai --inmunoscore and tumorquantai ihc immunoscore create the same public-alias research result:

The reproducible public input and frozen reference outputs are Zenodo record 22177196, dataset DOI 10.5281/zenodo.22177196. Use --public-slide-catalog to preserve its published case/slide identities.

<colon-ihc-result>/
├── START_HERE.html
├── PATHOLOGIST_REVIEW.html
├── cases/<case_alias>/
│   ├── measurement.json
│   ├── registration_qc.png              # omitted with --no-qc
│   └── paper_figures/                    # when registration QC exists
│       ├── case_summary_paper_figure.{png,pdf}
│       ├── case_summary_paper_figure_legend.txt
│       └── <slide_alias>_<marker>_paper_figure.{png,pdf}
├── tables/
│   ├── public_slide_inventory.csv
│   ├── tumorquantai_immunoscore_values.csv
│   ├── cohort_density_summary.csv
│   ├── case_compartment_densities.csv
│   ├── registration_qc.csv
│   ├── paper_figure_manifest.csv
│   ├── pathologist_review_template.csv
│   ├── pathologist_review_codebook.csv
│   └── unavailable_cases.csv
└── workflow_metadata/
    ├── immunoscore_run.json
    └── failures.json                    # only when a case failed

tumorquantai_immunoscore_values.csv is the clearest case-level table. It has one row for every discovered non-semantic case alias and four TumorQuantAI density values: CD3 and CD8 positive cells/mm² in the CK20 epithelial and stromal proxy compartments. Automatic-QC-pass cases define four deterministic within-cohort mid-rank reference distributions. Every numerically available pass/review case receives four percentiles, their mean, an internal rank group, and a provisional pI0-pI4 analogue. Review cases are scored against but never enter the reference. Failed and incomplete cases are unscored.

cohort_density_summary.csv makes the cohort denominator explicit. It reports descriptive statistics once for automatic-QC-pass cases and once for all numerically available pass/review cases; failed and incomplete cases are excluded from both.

case_compartment_densities.csv is the quantitative audit table. For each available marker and compartment it records the positive-cell count, segmented-nucleus count, analysed area in mm², density, mapped-positive-cell fraction, actual analysis MPP, registration Dice, and QC. The denominator is the registered tissue footprint of every valid streamed block, including valid tissue blocks in which no nucleus was detected.

registration_qc.csv records the selected transform, feature/inlier counts, tissue Dice, registered-tissue fraction, affine coefficients, and automated status. The PNG places the CK20 overview, both registered immune sections, the CK20 proxy masks, and registration evidence together for visual review. Automated pass is not pathologist approval.

Each complete case also has one 300-dpi case sheet and three marker-specific review sheets in PNG and PDF, with external legends. They show overview-scale registration/compartment evidence, exact densities, physical scale bars, the provisional-score gauge, and QC; they are not cell-outline overlays. PATHOLOGIST_REVIEW.html lets an expert export accept, flag, or exclude plus structured reasons, notes, reviewer code, and timestamp. Decisions remain separate from the immutable prediction and automatic-QC fields.

Each case measurement.json records how CK20 was streamed and projected, including its selected level and MPP, block and positive-pixel counts, projected-fraction threshold and range, raw/final compartment fractions, and effective morphology. It also records the selected-level dimensions needed to audit scale-based coordinates independently of MDS tile padding.

public_slide_inventory.csv contains only non-semantic aliases, marker, format, and physical scale. In public mode, the published catalog separately records the public filename, byte size, and checksums; no private ID or source path is used. In private mode, the exact source case/slide IDs, paths, sizes, and hashes remain only in the separate mode-0600 linkage. Incomplete marker sets appear in unavailable_cases.csv; missing or failed values are blank and are never converted to biological zero.

The output never claims the consensus clinical Immunoscore. Its consensus_immunoscore field is blank, and consensus_immunoscore_status states that pathologist-validated tumour-core and invasive-margin regions plus an external validated reference are required. See the colon IHC output reference. The separately named ck20_guided_provisional_immunoscore is an exploratory within-cohort review aid and must not be renamed or interpreted as that consensus score.

Offline sanitized draft outputs¶

The separate bin/prepare_breast_ihc_patch_release.py utility creates a new local draft directory; it does not write into an inference result. After a mandatory successful dry run, the release-side output is:

<public-draft>/
├── patches/<case_alias>/<patch_alias>_<MARKER>.tif
├── patch_manifest.csv
├── case_marker_counts.csv
├── validation_report.json
├── SHA256SUMS
└── MD5SUMS

The separately requested private linkage contains the original identifiers, source paths, and alias mapping. It is created with mode 0600 outside the repository and public draft and is never a public output. The source-selection manifest and mode-0600 alias secret are private inputs and stay outside those locations as well. The private manifest requires both microns_per_pixel and mpp_provenance for every selected image.

Each sanitized TIFF is fully decoded and compared with the decoded source RGB pixels. Non-allowlisted descriptions, dates, software, vendor, OME, and shaped metadata are removed. The verified per-image microns_per_pixel value from the private manifest is embedded into TIFF resolution tags and read back for physical-scale verification, so mixed-MPP selections preserve image-specific scale. Visible-pixel and privacy review is still required.

The manifest value is an externally audited calibration, not a claim that the source TIFF's possibly missing or incorrect resolution tags were trustworthy. The sanitizer restricts provenance to canonical safe English categories for measured scale-bar calibration, documented magnification extrapolation, or externally verified calibration. It publishes canonical mpp_provenance and decoded_rgb_sha256 values in patch_manifest.csv.

Source TIFFs with a non-default Orientation tag are rejected before re-encoding; an absent tag has the default top-left interpretation.

validation_report.json identifies the directory as a local draft and records that no network, upload, or publication action occurred. The sanitizer cannot upload or publish.

Deterministic local package outputs¶

After a mandatory successful packager dry run, bin/package_breast_ihc_patch_release.py writes a new directory while retaining the sanitized source unchanged:

<upload-package>/
├── TQA_BC_<case-alias>.zip
├── TQA_BreastIHC_manifest_bundle.zip
├── packaging_report.json
├── SHA256SUMS
└── MD5SUMS

There is one forced-ZIP64 case archive per HMAC case alias. For this cohort, 51 cases and 1,901 sanitized TIFFs produce 51 case archives plus the four listed auxiliary files, for an exact total of 55 top-level upload files. The manifest bundle contains the sanitizer's five metadata/checksum files plus archive_manifest.csv. The outer checksum files cover every case archive, the manifest bundle, and packaging_report.json.

Archives use ZIP_STORED, fixed member timestamps, canonical member order, and fixed file modes. The packager verifies the exact source and output rosters, source manifests and checksums, TIFF header and scale constraints, and each archive member's stored size, CRC32, SHA-256, and MD5 after writing. It also rejects noncanonical MPP provenance, fully decodes each sanitized TIFF to recompute its domain-separated RGB SHA-256, recomputes and verifies the final upload checksums, and confirms that the source draft roster is unchanged.

Exact archive bytes are guaranteed for identical validated inputs under the same supported packager tool/runtime. Fixed archive metadata removes dependence on source filesystem timestamps and modes; byte identity across arbitrary Python versions or ZIP implementations is not claimed.

ZIP_STORED avoids TIFF recompression but duplicates the retained source TIFF bytes. packaging_report.json records the conservative additional-disk estimate, case/archive counts, total upload-file count, compression choice, and verification statement.

The packager has no network, deposit, upload, or publication capability. Zenodo's default limits are 50 GB and 100 files per record. This published cohort's 55 files fit the default count limit and total 74,958,557,152 bytes, so additional record storage was required. New releases still require their own size and quota checks plus independent privacy, governance, and publication review.