DirectoryResultWriter

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 DirectoryResultWriter(root: str | Path, *, map_format: str = 'nrrd')[source]

Bases: object

Write study artefacts into one directory, in the v0.1 layout.

The layout is fixed here and nowhere else:

<root>/<subject_id>_habitats.<ext>
<root>/habitat_model.habitatmodel
<root>/<name>.csv
<root>/run_manifest.json

<ext> defaults to nrrd (v0.1). Pass map_format to write NIfTI or MetaImage instead; SimpleITK chooses the encoder from the destination suffix.

Parameters:

root – Destination directory. Created on first write rather than in __init__, so constructing a writer has no side effect – a caller may build one, decide not to use it, and leave no empty directory behind. Named root to match DirectoryDataSource: a destination is a filesystem fact here, not a configuration setting.
map_format – On-disk format for habitat and supervoxel label maps. One of "nrrd" (default), "nii", "nii.gz", "mha", "mhd". Leading dots are accepted (".nii.gz").

__init__(root: str | Path, *, map_format: str = 'nrrd') → None[source]

probe_write_access(*, existing_paths: Sequence[str | Path] | None = None) → Path[source]

Fail fast if root (or listed overwrite targets) is not writable.

Safe to call more than once; constructing the writer still has no side effect until this method or a write runs.

Parameters:: existing_paths – Optional files that will be overwritten.
Returns:: The destination directory after a successful probe.

write_habitat_map(habitat_map: HabitatMap) → str | None[source]

Write one subject’s habitat label image.

Parameters:: habitat_map – Labels plus the grid they refer to.
Returns:: The path written (extension follows map_extension).

write_feature_table(table: FeatureTable, name: str) → str | None[source]

Write one feature table as CSV.

Parameters:

table – The table to persist.
name – File stem, e.g. "habitat_features".

Returns:

The path written.

write_supervoxel_map(units: Supervoxelization) → str | None[source]

Write one subject’s supervoxel partition.

Not part of the ResultWriter protocol: the partition map is a v0.1 reporting artefact (two-step training wrote <subject_id>_supervoxel.nrrd during clustering), derived from the study’s clustering units rather than produced by the algorithms. Keeping it off the protocol lets third-party writers ignore it without structurally breaking the contract. The on-disk extension follows the writer’s map_extension.

Parameters:: units – The subject’s supervoxel partition.
Returns:: The path written.

write_units_table(units: Sequence[Supervoxelization], habitat_maps: Sequence[HabitatMap], *, granularity: str, table_format: str = 'parquet') → str | None[source]

Write the v0.1 habitats unit table derived from a study’s clustering units and habitat maps.

Like write_supervoxel_map() this is a v0.1-layout extra beyond the writer protocol. Row granularity follows the recipe design:

"supervoxel" – one row per clustering unit (two-step): subject, supervoxel, habitats, count, <features...>.
"habitat" – one row per assigned habitat within each subject (one-step, where units are single voxels and each defined cluster IS a habitat): same columns, aggregated per habitat.
"voxel" – one row per ROI voxel (direct pooling): subject, habitats, <features...>.

Parameters:

units – Per-subject clustering units, in cohort order.
habitat_maps – Per-subject habitat label images, aligned with units.
granularity – "supervoxel", "habitat" or "voxel".
table_format – "parquet" (v0.1 default) or "csv".

Returns:

The path written.

Raises:

HABITAPIError – On unknown granularity, length mismatch, or a units/map pair belonging to different subjects.

write_habitat_model(model: HabitatModel) → str | None[source]

Write the fitted habitat definition in its versioned archive format.

Parameters:: model – The population-level habitat definition.
Returns:: The path written.

write_subject_model(model: HabitatModel, subject_id: str) → str | None[source]

Write one subject’s own habitat definition (one-step design).

Deliberately NOT part of the ResultWriter protocol – the protocol persists one model per study, while the one-step design fits one definition per subject. Keeping this a directory-writer extra lets third-party writers ignore it without structurally breaking the contract (same rationale as write_supervoxel_map()).

Parameters:

model – The subject’s fitted habitat definition.
subject_id – Owning subject id; the file is named <subject_id>.habitatmodel.

Returns:

The path written.

write_units_frames(frames: Sequence[DataFrame], *, granularity: str, table_format: str = 'parquet') → str | None[source]

Write the units table from pre-aggregated per-subject rows.

Streaming runs aggregate each subject’s units-table rows inside the worker (via subject_units_frame()) so voxel-level arrays never cross the process boundary; this persists their concatenation in exactly the v0.1 layout write_units_table() produces.

Parameters:

frames – Per-subject units-table rows, in cohort order.
granularity – "supervoxel", "habitat" or "voxel" – only used for the header when frames is empty.
table_format – "parquet" (v0.1 default) or "csv".

Returns:

The path written.

Raises:

HABITAPIError – On unknown granularity.

write_manifest(manifest: RunManifest) → str | None[source]

Write the run manifest as JSON.

Parameters:: manifest – Provenance and reporting record for the run.
Returns:: The path written.