StudyResult

Note

This page is a reference documentation. It only explains the class signature, and not how to use it. Please refer to the Habitat Guide and Python API guide (v2.0) for usage.

class StudyResult(habitat_model: ~habit.contracts.habitat.HabitatModel | None, pipeline: ~typing.Any, features: ~habit.contracts.table.FeatureTable, habitat_maps: ~typing.Tuple[~habit.contracts.habitat.HabitatMap, ...], manifest: ~habit.contracts.manifest.RunManifest, subject_models: ~typing.Mapping[str, ~habit.contracts.habitat.HabitatModel] = <factory>, units: ~typing.Tuple[~habit.contracts.habitat.Supervoxelization, ...] = (), units_rows: ~typing.Tuple[~pandas.core.frame.DataFrame, ...] = (), maps_persisted: bool = False, inspection: ~typing.Any | None = None)[source]

Bases: object

What a fitted study hands back, entirely in memory.

Nothing here has touched the filesystem. Writing is a separate, explicit act via write() (any ResultWriter) or save() (the conventional directory layout), which is what allows the identical code to run inside someone else’s service where there is no output directory at all.

habitat_model

The population-level habitat definition. Named in full rather than model because model already means a trained classifier elsewhere in HABIT. None for designs that define habitats per subject rather than across the cohort – the one-step design in particular, where “the definition” is not one object (see subject_models).

Type:

habit.contracts.habitat.HabitatModel | None

pipeline

The subject-level procedure that applies that definition, so that model and procedure can be shipped together for external validation. None when no single procedure applies.

Type:

Any

features

Habitat-level features for the fitted cohort.

Type:

habit.contracts.table.FeatureTable

habitat_maps

Per-subject habitat label images, in cohort order.

Type:

Tuple[habit.contracts.habitat.HabitatMap, …]

manifest

Provenance and reporting for this run.

Type:

habit.contracts.manifest.RunManifest

subject_models

Per-subject habitat definitions, for designs that cluster each subject independently. Empty for cohort-level designs. Held in memory only: the writer protocol persists one habitat model per study, and inventing a per-subject file naming convention here would fix a layout no caller has asked for yet.

Type:

Mapping[str, habit.contracts.habitat.HabitatModel]

units

Per-subject clustering units the habitat maps were labelled from, in cohort order, aligned with habitat_maps. This is a REPORTING payload, not part of the scientific result: the v0.1 habitats.parquet unit table and *_supervoxel.nrrd maps are derived views of it, assembled by the directory writer. Empty when the caller only needs the label maps. A design with no supervoxel step stores one-voxel units (see voxel_units()), so the field has one uniform type regardless of design. Streaming retention modes (retain="maps" / "tables") drop this memory-dominant payload and keep units_rows instead.

Type:

Tuple[habit.contracts.habitat.Supervoxelization, …]

units_rows

Pre-aggregated per-subject rows of the v0.1 units table, produced inside the workers by streaming runs. When present, save() writes the units table from these frames instead of deriving it from units.

Type:

Tuple[pandas.core.frame.DataFrame, …]

maps_persisted

True when a streaming writer already persisted every habitat map during the fit; save() then skips map writing (and the map overwrite probe) entirely.

Type:

bool

inspection

Optional step observer / recorder passed as inspect= to a recipe. Default None. Writers ignore this field; it is for in-memory debugging only and is never part of fingerprints.

Type:

Any | None

See also

habit.recipes.Study

Produces this result via fit_predict.

habit.contracts.HabitatModel

Cohort-level definition on habitat_model.

habit.spec.HabitatSpec

Analysis declaration recorded in the manifest.

write(writer: ResultWriter) → None[source]

Hand every artefact to a writer.

The result decides WHAT is persisted; the writer decides WHERE and in what format. That split is what makes an S3 writer, a DICOM-SEG writer or a no-op writer possible without touching this class.

Parameters:

writer – Destination implementing ResultWriter.

save(out_dir: str | Path, *, table_format: str = 'parquet', map_format: str = 'nrrd', write_maps: bool = True, write_units_table: bool = True, write_cluster_plots: bool = False, write_cluster_plots_3d: bool = False, write_interactive_cluster_plots: bool = False) → Path[source]

Write the artefacts of this study to a directory.

Convenience sugar over write() with the conventional directory writer; the layout itself belongs to DirectoryResultWriter. Unlike write(), which hands over everything unconditionally (the protocol semantics), this entry point honours the two v0.1 reporting switches so the CLI can keep them meaningful: write_maps=False skips every label map (v0.1 save_images: false) and write_units_table=False skips the units table (v0.1 save_results_csv: false).

Beyond the protocol artefacts, when the study collected its clustering units this also persists the derived v0.1 reporting views of them: the habitats.parquet/habitats.csv unit table (row granularity follows the recipe design) and, for the two-step training design, one <subject_id>_supervoxel.<ext> per subject. v0.1 wrote supervoxel maps during training only – its predict path read them back rather than rewriting them – so the apply design writes none either.

When write_cluster_plots=True and a cohort-level habitat_model is present, a population-level 2D PCA habitat scatter is written under visualizations/habitat_clustering/, mirroring the v0.1 ClusteringService.visualize_habitat_clustering layout for the static PNG only (interactive 3D HTML remains in the legacy stack).

When the fit ran with a streaming writer (maps_persisted), the habitat maps are already on disk and are neither probed nor rewritten here; save then persists only the cohort-level artefacts (feature table, manifest, units table from the retained per-subject rows).

Parameters:

  • out_dir – Destination directory, created when missing.

  • table_format – On-disk format of the units table, "parquet" (v0.1 default) or "csv".

  • map_format – On-disk format of habitat / supervoxel label maps. "nrrd" (v0.1 default), "nii", "nii.gz", "mha", or "mhd".

  • write_maps – Write habitat maps (and, for the two-step design, supervoxel maps) using map_format.

  • write_units_table – Write the habitats units table.

  • write_cluster_plots – Write the population-level 2D PCA clustering scatter when cohort-level units and a habitat model exist.

  • write_cluster_plots_3d – Also write a static 3D PCA scatter PNG.

  • write_interactive_cluster_plots – Also write a rotatable plotly HTML file when plotly is installed.

Returns:

The directory written to.

__init__(habitat_model: ~habit.contracts.habitat.HabitatModel | None, pipeline: ~typing.Any, features: ~habit.contracts.table.FeatureTable, habitat_maps: ~typing.Tuple[~habit.contracts.habitat.HabitatMap, ...], manifest: ~habit.contracts.manifest.RunManifest, subject_models: ~typing.Mapping[str, ~habit.contracts.habitat.HabitatModel] = <factory>, units: ~typing.Tuple[~habit.contracts.habitat.Supervoxelization, ...] = (), units_rows: ~typing.Tuple[~pandas.core.frame.DataFrame, ...] = (), maps_persisted: bool = False, inspection: ~typing.Any | None = None) → None

Examples using habit.recipes.StudyResult

Quickstart: Python API

Quickstart: Python API

Quickstart: YAML

Quickstart: YAML