SubjectPipeline

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 SubjectPipeline(voxel_feature_extractor: VoxelFeatureExtractor, supervoxelizer: Supervoxelizer | None, habitat_assigner: HabitatAssigner | None, supervoxel_feature_extractor: SupervoxelFeatureExtractor | None = None, voxel_feature_preprocessor: SubjectFeaturePreprocessor | None = None, supervoxel_feature_preprocessor: SubjectFeaturePreprocessor | None = None, cohort_feature_preprocessor: CohortFeaturePreprocessor | None = None, on_geometry_mismatch: str = 'resample_mask', postprocess_supervoxel: ConnectedComponentPostprocess | None = None, postprocess_habitat: ConnectedComponentPostprocess | None = None, observer: StepObserver | None = None)

Bases: object

The subject-level chain composed into a single callable.

HABIT’s answer to monai.transforms.Compose. A generic Compose cannot be reused directly because HABIT’s steps are heterogeneously typed – Subject -> VoxelFeatureField -> Supervoxelization -> HabitatMap – and erasing those types would discard exactly the contracts that make the design checkable.

A fitted HabitatModel plus a SubjectPipeline is precisely the pair a study publishes for external validation: the definition, and the procedure that applies it.

Parameters:

• voxel_feature_extractor – Step producing per-voxel features.

• supervoxelizer – Step producing supervoxels. None clusters voxels directly, which is what the one-step and direct-pooling designs do.

• habitat_assigner – Step assigning habitat labels, already bound to a fitted model. None builds a FIT-TIME pipeline: units() works, __call__() does not. Cohort-level fitting needs exactly that, and sharing this class rather than reimplementing the stages is what guarantees a model is applied to units produced the same way it was fitted on.

• supervoxel_feature_extractor – Optional step describing the supervoxels. None keeps the feature means the supervoxelizer attached, which is the v0.1 default; a supervoxel_radiomics extractor replaces them with texture features. Ignored when supervoxelizer is None, since a single voxel has no region to describe – mirroring v0.1, where the one-step design ignores the supervoxel_level block.

• voxel_feature_preprocessor – Optional stateless preprocessing of the voxel features, applied BEFORE supervoxelisation. This is v0.1’s preprocessing_for_subject_level, and its position matters: normalising each subject before its ROI is partitioned is what keeps supervoxel boundaries from tracking scanner intensity scale.

• supervoxel_feature_preprocessor – Optional stateless preprocessing of the supervoxel features. The slot v0.1 lacked entirely – per supervoxel radiomics had no way to be normalised within a subject before cohort pooling. Requires a supervoxelizer, for the same reason as supervoxel_feature_extractor.

• cohort_feature_preprocessor – Optional FITTED cohort-level chain, applied last, immediately before assignment. Required whenever the habitat model was fitted on cohort-preprocessed units: omitting it would feed the assigner a feature space different from the one the model was defined in, and it would still return plausible-looking labels.

• on_geometry_mismatch – How to handle image/mask grid disagreements before Stage-1. "resample_mask" (default) nearest-neighbour resamples each ROI onto the first image modality; "strict" raises GeometryError.

• postprocess_supervoxel – Optional connected-component cleanup applied immediately after supervoxelization and before supervoxel feature extraction. Ignored when supervoxelizer is None.

• postprocess_habitat – Optional connected-component cleanup applied immediately after habitat assignment and before habitat features.

• observer – Optional step observer for debugging / QA. Never part of spec or fingerprints; None (default) is zero-cost.

__init__(voxel_feature_extractor: VoxelFeatureExtractor, supervoxelizer: Supervoxelizer | None, habitat_assigner: HabitatAssigner | None, supervoxel_feature_extractor: SupervoxelFeatureExtractor | None = None, voxel_feature_preprocessor: SubjectFeaturePreprocessor | None = None, supervoxel_feature_preprocessor: SubjectFeaturePreprocessor | None = None, cohort_feature_preprocessor: CohortFeaturePreprocessor | None = None, on_geometry_mismatch: str = 'resample_mask', postprocess_supervoxel: ConnectedComponentPostprocess | None = None, postprocess_habitat: ConnectedComponentPostprocess | None = None, observer: StepObserver | None = None) → None

property spec: Spec

Return the composed specification of every stage.

units(subject: Subject) → Supervoxelization

Run every stage up to (but excluding) habitat assignment.

Exposed separately because cohort-level fitting needs exactly this: the clustering units of each training subject, pooled and then used to DEFINE the habitats. Sharing one implementation with __call__() is what guarantees a model is applied to units produced the same way they were fitted on.

Parameters:

subject – The subject to process.

Returns:

The subject’s clustering units. Every ROI voxel is its own unit when no supervoxelizer is configured.

assign(units: Supervoxelization) → Tuple[HabitatMap, Supervoxelization]

Assign habitats from clustering units already produced by units().

This is the train-path reuse hook: cohort-level fit recipes and sklearn adapters compute Stage-1 units once, then call this instead of __call__() (which would re-extract voxel / supervoxel features). Predict / apply paths keep calling __call__() so held-out subjects are still derived from images.

Parameters:

units – Precomputed clustering units for one subject (before cohort-level preprocessing).

Returns:

(habitat_map, units_after_cohort_prep). The post-prep units feed the v0.1 habitats.parquet unit table at the writer.

Raises:

HABITAPIError – If this is a fit-time pipeline (no assigner).

__call__(subject: Subject) → HabitatMap

Run voxel features, supervoxelisation and assignment for one subject.

Parameters:

subject – The subject to label.

Returns:

The subject’s habitat label image.

Raises:

HABITAPIError – If this is a fit-time pipeline (no assigner).

label_and_describe(subject: Subject, units: Supervoxelization, extractors: Sequence[HabitatFeatureExtractor]) → Tuple[HabitatMap, FeatureTable | None, Supervoxelization]

Assign habitats from precomputed units, then extract habitat features.

Parameters:

• subject – Subject providing images for habitat-level descriptors.

• units – Clustering units from an earlier Stage-1 pass.

• extractors – Habitat feature families; may be empty when only the label map is needed.

Returns:

(habitat_map, feature_table_or_none, units_after_cohort_prep).

extract_features(subject: Subject, extractors: Sequence[HabitatFeatureExtractor]) → FeatureTable

Run the pipeline and then the requested habitat feature families.

Named extract_features (an action) rather than the bare noun features, which would read as an attribute on a callable object. Recomputes Stage-1 from subject (predict-path semantics). When units are already in memory, call label_and_describe() instead.

Parameters:

• subject – The subject to process.

• extractors – Habitat feature families to compute.

Returns:

One feature table for that subject, joined across families.

Raises:

HABITAPIError – If extractors is empty.

Examples using habit.pipeline.SubjectPipeline

Feature preprocessing

Feature preprocessing