Combiner

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 Combiner(*args, **kwargs)[source]

Bases: Protocol

Merge the feature blocks produced by sibling nodes of a feature tree.

A combiner is the internal node of a feature composition tree: it never touches images, subjects, or the filesystem – only the column blocks its child nodes already produced. This is what keeps the multi-modality matrix open-ended: extractors answer “how do I describe ONE modality’s signal”, combiners answer “how do I merge SIBLING descriptions”, and new combination strategies (weighting, ratios, kinetic slopes, formulas) plug in through the habit.combiner entry point without changing any extractor.

The same protocol serves every granularity: at voxel level the blocks are the children VoxelFeatureField.feature_frame() matrices (rows are ROI voxels in C order); at supervoxel level they are the children Supervoxelization.feature_frame() matrices (rows are supervoxels); at habitat level they are one-row-per-subject frames. Rows are always aligned positionally across siblings, because the tree wrapper guarantees every child describes the same units.

property spec: Spec

Return the algorithm specification, used for provenance.

__call__(blocks: Sequence[DataFrame], *, context: Mapping[str, Any] | None = None) → DataFrame[source]

Combine sibling feature blocks into one block.

Parameters:

  • blocks – Child blocks in child order, one per sibling node. All blocks share the same row count (enforced by the tree wrapper).

  • context –

    Optional evaluation context supplied by the tree wrapper. Recognised keys:

    • "sources": source label of each child, in child order (a leaf’s as_ alias when set, else its modality, else the node name). Combiners whose parameters are keyed by child (e.g. weights) resolve them against these labels.

    • "subject_id": id of the subject being processed, for combiners whose parameters are subject-keyed (kinetic acquisition times).

Returns:

The merged block, with the same row count as the inputs.

__init__(*args, **kwargs)