build_habitat_document

Note

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

build_habitat_document(spec: HabitatSpec, *, data_source: str | Path, out_dir: str | Path, policy: RunPolicy | None = None, mode: str = 'train', pipeline: str | Path | None = None, save_images: bool = True, save_results_csv: bool = True, habitats_results_format: str = 'parquet', plot_curves: bool = True) → Dict[str, Any][source]

Assemble a native v1 habitat document with expanded defaults.

The spec section uses HabitatSpec.to_effective_dict() so omitted fingerprint-stable defaults (geometry policy, empty postprocess slots) appear explicitly. The policy section always emits every RunPolicy field (caller policy or library defaults).

Parameters:

  • spec – Analysis declaration (what to compute).

  • data_source – Cohort root directory or input-manifest YAML path.

  • out_dir – Destination directory for CLI / run_from_yaml(..., save=True).

  • policy – Execution policy; None expands to RunPolicy defaults.

  • mode – "train" or "predict".

  • pipeline – Fitted .habitatmodel path for predict mode.

  • save_images – Persist NRRD habitat (and supervoxel) maps.

  • save_results_csv – Persist the habitats unit table.

  • habitats_results_format – "parquet" or "csv".

  • plot_curves – Persist clustering visualisation artefacts.

Returns:

A v1 document mapping ready for YAML serialisation.

Raises:

HABITAPIError – When the assembled document fails structural validation.