`habit.contracts`: in-memory data model

L2 domain data contracts: the vocabulary every HABIT layer speaks.

The guiding rule is that each type must be explainable in the language of habitat imaging research – an abstraction that can only be justified in software terms does not belong here. Nothing in this package knows about YAML, output directories, run modes, CLI, or logging.

User guide: Data model (habit.contracts) · Habitat Guide Load from directory. Adapters that load these objects from disk: Adapters (habit.adapters).

Contracts are plain value objects with no IO and no YAML knowledge.

Classes

Imaging

`Geometry`	Spatial definition shared by every volumetric object of one subject.
`ImageRef`	Lazy handle to volumetric data.
`ArrayImageRef`	In-memory `ImageRef` backed by a NumPy array.
`ImageVolume`	An image array with explicit physical-space metadata.
`MaskVolume`	An image-space segmentation mask with explicit label semantics.
`Subject`	One imaging subject.
`Cohort`	Ordered collection of subjects.
`CohortFingerprint`	Non-identifiable description of the cohort behind a fitted model.

Provenance

`Provenance`	Immutable record answering "how was this object produced?".
`RunManifest`	Everything needed to describe and audit one completed analysis.
`StepRecord`	One observed pipeline boundary for one subject.
`StepObserver`	Optional sink for `StepRecord` events.

Habitat artefacts

`VoxelFeatureField`	Per-voxel feature vectors inside one subject's ROI.
`Supervoxelization`	Within-subject partition of the ROI into supervoxels, plus their features.
`HabitatMap`	Habitat label image for one subject.
`HabitatModel`	Population-level habitat definition -- HABIT's primary scientific artefact.

Tables and outcomes

`FeatureTable`	Feature table with explicit column semantics.
`Outcome`	A declared study endpoint.
`BinaryOutcome`	Two-class endpoint, e.g. treatment response or 2-year recurrence.
`MulticlassOutcome`	Endpoint with three or more mutually exclusive classes.
`ContinuousOutcome`	Continuous endpoint for regression, e.g. tumour volume change or a score.
`SurvivalOutcome`	Right-censored time-to-event endpoint, e.g. overall or progression-free survival.

Operator protocols

`SubjectOperator`	A computation that touches exactly one subject.
`CohortOperator`	A computation that must observe the whole cohort at once.
`SubjectResult`	Result slot for one subject, distinguishing success from isolated failure.
`ExecutionBackend`	Strategy for executing subject-level work.
`DataSource`	Anything that can produce a cohort.
`ResultWriter`	Anything that can persist HABIT outputs.

Functions

`cohort_from_directory`	Build a cohort from HABIT's conventional directory layout.
`software_fingerprint`	Capture HABIT and scientifically relevant dependency versions.
`outcome_from_dict`	Rebuild an endpoint declaration from its serialised mapping.
`outcome_to_dict`	Serialise an endpoint declaration to a plain mapping for YAML/JSON.