phenotypic.sdk_.BundleLayout

class phenotypic.sdk_.BundleLayout(deliverables_base: Path, output_root: Path | None)

Bases: object

Resolved on-disk topology of a run output or a standalone deliverables bundle.

Separates the deliverables base (the folder directly holding master_measurements.parquet) from the optional output root (the parent that also holds results/ and .phenotypic/). A standalone bundle has output_root is None; deliverables-internal artefacts always resolve from deliverables_base so the bundle is portable.

Parameters:

• deliverables_base (Path)

• output_root (Path | None)

deliverables_base

Folder containing master_measurements.parquet.

Type:

pathlib.Path

output_root

Parent run directory holding results/ + machine state, or None for a standalone (deliverables-only) bundle.

Type:

pathlib.Path | None

Methods

__init__
detect	Classify path as a run output dir or a standalone deliverables bundle.
error_category_parquet	Return path to errors/<category>.parquet.
hdf_path	Full-res per-image HDF for (dataset, stem), or None if unavailable.
overlay_path	Return path to overlays/<dataset>/<stem>.png.
overlays_dir	Return path to overlays/<dataset>/.

Attributes

analysis_csv	Return path to analysis.csv in the deliverables base.
analysis_parquet	Return path to analysis.parquet in the deliverables base.
curation_labels_parquet	Return path to deliverables/qc/curation_labels.parquet (durable labels store).
custom_categories_json	Return path to deliverables/qc/custom_categories.json (custom-category registry).
error_analysis_csv	Return path to error_analysis.csv in the deliverables base.
error_analysis_html	Return path to error_analysis.html in the deliverables base.
error_analysis_parquet	Return path to error_analysis.parquet in the deliverables base.
errors_dir	Return path to the errors/ directory under the deliverables base.
has_results	Return True when a results/ directory exists under the output root.
master_csv	Return path to master_measurements.csv in the deliverables base.
master_parquet	Return path to master_measurements.parquet in the deliverables base.
mirror_csv	Return path to measurements.csv (post-applied mirror).
mirror_parquet	Return path to measurements.parquet (post-applied mirror).
pipeline_config_path	Return path to pipeline.json in the deliverables base.
qc_dir	Return the QC directory, resolving legacy <output>/qc/ layouts.
qc_duckdb	Return path to qc/qc.duckdb (the QC analysis database).
qc_review_state_path	Return path to deliverables/qc/review_state.json (GUI-owned review progress).
resolved_pipeline_config_path	Return the best existing pipeline config path inside the bundle.
results_dir	Return the results/ directory, or None for a standalone bundle.
verified_parquet	Return path to verified.parquet (GUI-written verified-good archive).
deliverables_base
output_root

deliverables_base: Path

output_root: Path | None

classmethod detect(path: Path) → BundleLayout

Classify path as a run output dir or a standalone deliverables bundle.

Case 1 — path directly holds master_measurements.parquet: treat it as the deliverables base. Promote path.parent to output_root ONLY when path is literally named deliverables AND a sibling results/ exists (the “pointed at the deliverables subdir of a full run” case); this guard stops a renamed standalone bundle from adopting an unrelated sibling results/.

Case 2 — path contains deliverables/master_measurements.parquet: deliverables_base = path/deliverables and output_root = path.

Parameters:

path (Path) – Either a run output directory (containing a deliverables/ subdirectory) or a standalone deliverables folder (directly containing master_measurements.parquet).

Returns:

A BundleLayout with resolved deliverables_base and output_root.

Raises:

FileNotFoundError – path is neither a run output directory nor a deliverables bundle.

Return type:

BundleLayout

property has_results: bool

Return True when a results/ directory exists under the output root.

property results_dir: Path | None

Return the results/ directory, or None for a standalone bundle.

hdf_path(dataset: str, stem: str) → Path | None

Full-res per-image HDF for (dataset, stem), or None if unavailable.

Parameters:

• dataset (str) – Dataset name (subdirectory under results/).

• stem (str) – Image stem (filename without extension).

Returns:

Resolved .h5 path if the file exists, otherwise None.

Return type:

Path | None

property master_parquet: Path

Return path to master_measurements.parquet in the deliverables base.

property master_csv: Path

Return path to master_measurements.csv in the deliverables base.

property mirror_parquet: Path

Return path to measurements.parquet (post-applied mirror).

property mirror_csv: Path

Return path to measurements.csv (post-applied mirror).

property pipeline_config_path: Path

Return path to pipeline.json in the deliverables base.

property resolved_pipeline_config_path: Path

Return the best existing pipeline config path inside the bundle.

Mirrors resolve_pipeline_config_path()’s precedence but anchored on deliverables_base (so a standalone bundle resolves inside itself without double-joining deliverables/): the canonical typed config when present, else the legacy plain pipeline.json when present, else the canonical path (so writers naturally create typed config files).

property qc_dir: Path

Return the QC directory, resolving legacy <output>/qc/ layouts.

Prefers deliverables/qc/ when it exists. Falls back to the legacy root <output>/qc/ when only that exists (pre-relocation runs). Returns the canonical deliverables/qc/ path for fresh writes when neither is present.

property qc_duckdb: Path

Return path to qc/qc.duckdb (the QC analysis database).

property qc_review_state_path: Path

Return path to deliverables/qc/review_state.json (GUI-owned review progress).

property curation_labels_parquet: Path

Return path to deliverables/qc/curation_labels.parquet (durable labels store).

property custom_categories_json: Path

Return path to deliverables/qc/custom_categories.json (custom-category registry).

property errors_dir: Path

Return path to the errors/ directory under the deliverables base.

property error_analysis_parquet: Path

Return path to error_analysis.parquet in the deliverables base.

property error_analysis_csv: Path

Return path to error_analysis.csv in the deliverables base.

property error_analysis_html: Path

Return path to error_analysis.html in the deliverables base.

property verified_parquet: Path

Return path to verified.parquet (GUI-written verified-good archive).

property analysis_parquet: Path

Return path to analysis.parquet in the deliverables base.

property analysis_csv: Path

Return path to analysis.csv in the deliverables base.

error_category_parquet(category: str) → Path

Return path to errors/<category>.parquet.

Parameters:

category (str) – Bare, already-sanitized category token (e.g. "background_noise").

Returns:

Path to the per-category error parquet file.

Return type:

Path

overlays_dir(dataset: str) → Path

Return path to overlays/<dataset>/.

Parameters:

dataset (str) – Dataset name.

Returns:

Directory path for overlay PNGs of the given dataset.

Return type:

Path

overlay_path(dataset: str, stem: str) → Path

Return path to overlays/<dataset>/<stem>.png.

Parameters:

• dataset (str) – Dataset name.

• stem (str) – Image stem (filename without extension).

Returns:

Path to the overlay PNG for the given image.

Return type:

Path