Adapters (`habit.adapters`)

L1 adapters: the only layer (besides recipe writers) allowed to touch the filesystem.

Each adapter turns one external data convention – HABIT’s own directory layout, a DataFrame, in-memory arrays, or an nnU-Net dataset – into the L2 Cohort contract.

User guide: Data model (habit.contracts) · Python API guide (v2.0).

L1 adapters turn external layouts into contracts objects without pulling YAML or domain logic into the data layer.

Classes

`DirectoryDataSource`	Build a `Cohort` from HABIT's conventional directory layout.
`DirectoryResultWriter`	Write study artefacts into one directory, in the v0.1 layout.
`FileImageRef`	Lazy `ImageRef` backed by one image file.
`PreprocessingIOAdapter`	Discover legacy directory/manifest inputs and write NIfTI batch results.

Functions

`discover_habitat_map_paths`	Discover habitat map files and map them to subject ids.
`load_extract_cohort`	Build a cohort from `raw_img_folder/images/<subject>/<modality>/`.
`read_habitat_map`	Load one habitat label map from disk into a `HabitatMap`.
`resolve_n_habitats`	Resolve the habitat count for column alignment across the cohort.
`write_extract_feature_csvs`	Persist domain feature tables in the v0.1 `habit extract` CSV layout.

DirectoryDataSource

For on-disk studies. To explore the API without files, use make_synthetic_cohort() instead (see Python API guide (v2.0)).

from habit.adapters import DirectoryDataSource

source = DirectoryDataSource(
    "/path/to/processed_images",
    modalities=("T1", "T2"),
    roi="tumor",
    name="training",
)
cohort = source.load()  # habit.contracts.Cohort

cohort_from_directory(...) is a thin convenience over this source (see Data model (habit.contracts)).

FileImageRef

Lazy on-disk image reference implementing ImageRef:

from habit.adapters import FileImageRef
from habit.contracts import Geometry

# Usually produced by DirectoryDataSource.
# Constructing manually:
ref = FileImageRef(
    "data/subj001/T1.nii.gz",
    is_mask=False,
    role_name="T1",
)
volume = ref.load()  # ImageVolume with geometry from the file

DirectoryResultWriter

The write-side counterpart of DirectoryDataSource, implementing the ResultWriter protocol with the conventional directory layout:

from habit.adapters import DirectoryResultWriter

writer = DirectoryResultWriter("out/study")   # creates nothing yet; maps as .nrrd
result.write(writer)                          # a StudyResult from habit.recipes

# Prefer StudyResult.save for the common case (same layout + units table):
# result.save("out/study", map_format="nii.gz")

# out/study/<subject>_habitats.nrrd     habitat label maps (geometry preserved)
# out/study/habitat_model.habitatmodel  the population habitat definition
# out/study/habitat_features.csv        the cohort feature table
# out/study/run_manifest.json           provenance and methods text

map_format on DirectoryResultWriter (and on save()) selects the label-map container: nrrd (default), nii, nii.gz, mha, or mhd. The directory is created on the first write, so constructing a writer you end up not using leaves nothing behind. Implement the same four methods elsewhere to send results to an object store or an in-memory sink instead.

Adapters (habit.adapters)