Cohort

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 Cohort(subjects: Sequence[Subject], *, name: str | None = None, metadata: Mapping[str, Any] | None = None)[source]

Bases: Sequence[Subject]

Ordered collection of subjects.

Order is part of the contract, not an implementation detail: population-level clustering can be sensitive to subject order, so a reproducible cohort must have a defined, recorded ordering.

Parameters:

  • subjects – Subjects in canonical order.

  • name – Human-readable cohort name used in reports, e.g. "training".

  • metadata – Cohort-level attributes such as centre, scanner, or study.

Raises:

HABITAPIError – If subject_id values are missing, blank, or duplicated.

__init__(subjects: Sequence[Subject], *, name: str | None = None, metadata: Mapping[str, Any] | None = None) → None[source]
__getitem__(index: int) → Subject[source]
__getitem__(index: slice) → Cohort

Index one subject, or slice to a new cohort preserving metadata.

__repr__() → str[source]

Return a short English summary (ids and optional name).

property subject_ids: Tuple[str, ...]

Return the subject identifiers in canonical cohort order.

classmethod from_directory(root: str | Path, *, modalities: Sequence[str], roi: str, name: str | None = None, images_folder: str = 'images', masks_folder: str = 'masks') → Cohort[source]

Build a cohort from HABIT’s conventional directory layout.

A thin shortcut over DirectoryDataSource(...).load(), provided because reading a folder is the overwhelmingly common first line of a notebook session and should not require learning the adapter layer. The adapter import is lazy so that the contracts layer never depends on the filesystem-touching adapter layer at import time.

Parameters:

  • root – Directory root holding images_folder and masks_folder with one subdirectory per subject.

  • modalities – Modality keys to load, in the order the analysis needs.

  • roi – Mask key identifying the region of interest.

  • name – Human-readable cohort name used in reports.

  • images_folder – Name of the images subdirectory under root.

  • masks_folder – Name of the masks subdirectory under root.

Returns:

A cohort with a defined, reproducible subject order (sorted subject ids).

filter(predicate: Callable[[Subject], bool]) → Cohort[source]

Return a new cohort containing subjects satisfying predicate.

Parameters:

predicate – Callable receiving a Subject and returning bool.

Returns:

A new cohort preserving the relative order of retained subjects.

map(op: Callable[[Subject], Any], *, backend: 'ExecutionBackend' | None = None, checkpoint: 'CheckpointStore' | None = None, raise_on_failure: Literal[True] = True) → Sequence[Any][source]
map(op: Callable[[Subject], Any], *, backend: 'ExecutionBackend' | None = None, checkpoint: 'CheckpointStore' | None = None, raise_on_failure: Literal[False]) → Sequence['SubjectResult[Any]']

Apply a subject-level operator to every subject, in cohort order.

This is the middle rung of a deliberate three-step ladder: op(subject) for one subject, cohort.map(op) for all of them, and cohort.map(op, backend=...) only when parallelism, per-subject timeouts or resume are actually wanted. Because backend defaults to a serial one, a researcher can complete an entire study without ever learning that execution backends exist.

Parameters:

  • op – Any subject-level operator, i.e. any of the subject-level domain protocols or a SubjectPipeline.

  • backend – Execution strategy. Serial when omitted.

  • checkpoint – Store enabling resume. Disabled when omitted.

  • raise_on_failure – When True (default), aggregate failed subjects into ProcessingError. When False, return SubjectResult slots in cohort order so callers (recipes / CLI) can proceed with successes — matching v0.1 on_subject_failure: continue.

Returns:

When raise_on_failure is True, unwrapped values in cohort order. When False, SubjectResult slots in cohort order (failed slots carry .error).

Raises:

ProcessingError – If raise_on_failure is True and any subject failed; the message lists every failed subject id and its error. Also raised when the backend omits a subject.

summarize(description: str | None = None) → CohortFingerprint[source]

Summarise the cohort for provenance and model cards.

Named summarize rather than fingerprint because it returns a rich summary object, whereas Spec.fingerprint() returns a hash string; the returned type keeps the name CohortFingerprint (nnU-Net’s term for a dataset summary).

Parameters:

description – Optional free-text description for a model card.

Returns:

A fingerprint safe to embed in a shared HabitatModel, i.e. containing no identifiable patient information.

Examples using habit.contracts.Cohort

Quickstart: Python API

Quickstart: Python API

Quickstart: YAML

Quickstart: YAML