Study

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 Study(spec: HabitatSpec, design: str | None = None)

Bases: object

A habitat analysis declared independently of any cohort.

The lifecycle mirrors a sklearn estimator: fit() learns the cohort-level habitat definition and returns self; predict() projects that definition onto a new cohort; fit_predict() fits and hands back the full StudyResult in one call. Fitted state is exposed through the trailing-underscore attributes model_ and fit_result_.

spec

The analysis to run.

Type:

habit.spec.specs.HabitatSpec

design

Optional declared intent ("two_step", "one_step" or "direct_pooling"). When set, fit validates the spec against the design’s guards before running, so a mismatched spec fails loudly instead of silently running a different dataflow. When None, the dataflow declared by the spec itself (pooling / stage list) decides what runs.

Type:

str | None

model_

The fitted HabitatModel; None until fitted, and None after fitting a one_step study (that design defines habitats per subject, so there is no cohort-level model to publish).

Type:

habit.contracts.habitat.HabitatModel | None

fit_result_

The StudyResult produced by the latest fit(); None until fitted.

Type:

habit.recipes.result.StudyResult | None

See also

habit.spec.HabitatSpec

Frozen analysis declaration used by this study.

habit.contracts.HabitatModel

Fitted cohort habitat definition.

habit.recipes.StudyResult

In-memory artefacts from fit_predict.

habit.recipes.two_step_habitat

Factory for the classical two-step design.

__post_init__() → None

Validate the declared design before any compute happens.

fit(cohort: Cohort, *, backend: ExecutionBackend | None = None, checkpoint: CheckpointStore | None = None, seed: int | None = None, inspect: StepObserver | None = None, report: Any | None = None, writer: ResultWriter | None = None, retain: str = 'all', on_subject_complete: Callable[[Subject, HabitatMap, HabitatModel], None] | None = None, persist_subject_models: bool = True) → Study

Learn the habitat definition on a cohort; return self.

Parameters:

• cohort – Subjects to analyse.

• backend – Optional execution backend (parallelism, resume policy).

• checkpoint – Optional checkpoint store forwarded to per-subject stages.

• seed – Optional override of spec.random_seed.

• inspect – Optional step observer for in-memory debugging / QA. Unsupported with the process backend.

• report – Optional Report declaring what to persist and draw as each subject completes. This is the primary streaming API. writer / retain / on_subject_complete remain as shorthands that fill an implicit report.

• writer – Optional streaming writer (one_step design only): each subject’s habitat map is persisted the moment the backend yields it, so a crashed run keeps completed subjects.

• retain – "all" (default) keeps every artefact in memory; "maps" drops voxel-level clustering units (the memory-dominant payload of voxel-level designs); "tables" additionally drops habitat maps and requires writer.

• on_subject_complete – Optional parent-process callback (subject, habitat_map, model) fired once per completed subject – including checkpoint-resumed ones – before retention stripping. Prefer a figure atom on report.

• persist_subject_models – With a streaming writer and no explicit report.persist, also write <subject_id>.habitatmodel for each subject.

Returns:

model_ holds the cohort-level definition (except for the one_step design) and fit_result_ the full study result.

Return type:

self, fitted

predict(cohort: Cohort, *, backend: ExecutionBackend | None = None, checkpoint: CheckpointStore | None = None, seed: int | None = None, inspect: StepObserver | None = None) → StudyResult

Apply the fitted habitat definition to a (new) cohort.

The model’s own cohort-level preprocessing state is restored and re-applied, because centroids only mean something in the feature space they were computed in.

Parameters:

• cohort – Subjects to label.

• backend – Optional execution backend. Serial when omitted.

• checkpoint – Optional store enabling per-subject resume; keys scope on model_.model_id.

• seed – Optional override of spec.random_seed.

• inspect – Optional step observer for in-memory debugging / QA. Unsupported with the process backend.

Returns:

habitat maps, the habitat feature table and the run manifest, all in memory.

Return type:

The study result for the projected cohort

Raises:

• NotFittedError – If the study has no fitted model yet.

• HABITAPIError – If the study ran a one_step fit, which defines habitats per subject and therefore has no cohort-level model to apply.

fit_predict(cohort: Cohort, *, backend: ExecutionBackend | None = None, checkpoint: CheckpointStore | None = None, seed: int | None = None, inspect: StepObserver | None = None, report: Any | None = None, writer: ResultWriter | None = None, retain: str = 'all', on_subject_complete: Callable[[Subject, HabitatMap, HabitatModel], None] | None = None, persist_subject_models: bool = True) → StudyResult

Fit on a cohort and return the full study result.

Equivalent to fit(cohort).fit_result_, provided for the common case where the training-cohort artefacts (maps, features, manifest) are wanted immediately.

Parameters:

• cohort – Subjects to analyse.

• backend – Optional execution backend (parallelism, resume policy).

• checkpoint – Optional checkpoint store forwarded to per-subject stages.

• seed – Optional override of spec.random_seed.

• inspect – Optional step observer for in-memory debugging / QA.

• report – Optional Report; see fit().

• writer – Optional streaming writer (one_step design only); see fit().

• retain – In-memory retention mode; see fit().

• on_subject_complete – Optional per-subject completion callback; see fit().

• persist_subject_models – Write per-subject models when streaming; see fit().

Returns:

The completed study result.

classmethod from_model(model: HabitatModel | str | Path, spec: HabitatSpec | None = None) → Study

Build a fitted study from a published habitat model.

This is the external-validation entry point: load a .habitatmodel artefact (or pass an in-memory HabitatModel) and call predict() on the new cohort.

Parameters:

• model – A fitted model, or a path to a .habitatmodel archive.

• spec – The analysis declaration whose upstream stages must match the model’s training spec. When None, the spec embedded in the model archive is used.

Returns:

A study whose model_ is already fitted, ready for predict().

__init__(spec: HabitatSpec, design: str | None = None) → None

Examples using habit.recipes.Study

Quickstart: Python API

Quickstart: Python API