habit.feature_preprocessing: scale voxel-feature matrices

Feature preprocessing for clustering inputs (voxel and supervoxel).

Two chains over one shared set of methods. The chains differ by whether their state crosses subject boundaries, not by what they process:

• SubjectPreprocessingChain – stateless, per subject, usable at either granularity, removes between-subject variation.

• CohortPreprocessingChain – stateful, fitted on the training cohort, makes subjects comparable, state travels in the habitat model.

Distinguish this domain from table_preprocessor: that one preprocesses the MODELLING table (one row per subject, with identifier and outcome columns) on the way to an outcome model. This one preprocesses the CLUSTERING input (one row per voxel or supervoxel) on the way to a habitat definition.

Chains speak plain DataFrame. The bridge to the typed contracts is the symmetric pair feature_frame() / with_feature_frame() carried by both VoxelFeatureField and Supervoxelization, so a chain never needs to know which one it is processing.

User guide: Habitat Guide Feature preprocessing · Habitat domain API. Component names: Habitat Spec component catalog.

Subject-level and cohort-level preprocessing of voxel / supervoxel feature matrices, composable into chains. This is not image preprocessing (Image preprocessing (bookmark)) and not table-ML preprocessing (Tabular ML (bookmark)).

Classes

SubjectFeaturePreprocessor	Preprocess one subject's feature matrix using only that subject's data.
CohortFeaturePreprocessor	Preprocess the pooled cohort feature matrix with fitted statistics.
SubjectPreprocessingChain	Stateless preprocessing of one subject's feature matrix.
CohortPreprocessingChain	Stateful preprocessing of the pooled cohort feature matrix.
ZScoreScaling	Standardise features to zero mean and unit variance.
MinMaxScaling	Scale features to [0, 1].
RobustScaling	Centre features on the median and scale by the interquartile range.
Winsorizing	Clip extreme values at tail quantiles instead of discarding them.
LogTransform	Compress right-skewed features with log(x - min + 1).
Binning	Discretise features into ordinal bin indices.
Impute	Replace non-finite feature values with a learned per-column statistic.
VarianceFilter	Drop feature columns whose variance is at or below a threshold.
CorrelationFilter	Greedily drop redundant, highly correlated feature columns.
PreciseCorrelationFilter	Prior 2024 Spearman screen: signed r, p-value, keep the later column.
MaxAbsScaling	Scale features by the maximum absolute value.
QuantileTransform	Map each feature onto a uniform or normal distribution by percentile rank.
L2Normalizer	Scale each row (voxel / supervoxel) to unit Euclidean length.
FeatureWhitelist	Restrict the feature matrix to an explicit, externally derived list.
FeaturePreprocessingMethodRegistry	Name-to-implementation registry for feature-matrix preprocessing methods.

Functions

build_methods

Instantiate preprocessing methods from their specifications.