nimare.ml.MaskerTransformer

class MaskerTransformer(masker=None, source_masker=None, masker_kwargs=None, batch_size=32)

Bases: TransformerMixin, BaseEstimator

Apply a nilearn masker to voxel features.

A nilearn masker takes images, where a ColumnTransformer hands out columns of an array. This is the bridge: rows are turned back into images in the source mask’s space, in batches, and handed to the masker, so region definitions, smoothing, resampling and aggregation strategy all stay nilearn’s.

An atlas reduces the voxels to regions; a NiftiMasker gives voxels back, which is how nilearn’s smoothing, standardizing and detrending reach these features. How many regions an atlas yields depends on the nilearn version as well as the atlas; see the machine learning documentation.

Parameters:

• masker (object, optional) – What to apply, by default None. Any nilearn masker, which is cloned rather than modified, or anything nilearn loads as an atlas: a Bunch from a nilearn.datasets.fetch_atlas_* function, a 3D or 4D atlas image or a path to one, or the name of a fetcher with its arguments in masker_kwargs. A 4D atlas is summarised with a NiftiMapsMasker and a 3D one with a NiftiLabelsMasker.

• source_masker (NiftiMasker or img_like, optional) – The masker defining the voxel order of the incoming features, normally the masker a bunch carries, by default None. This is where the columns came from, not what is applied to them. Columns may be the masker’s own voxels, as MAKernel returns them, or the whole image grid, as a bunch’s peak columns arrive; which of the two is read off their width.

• masker_kwargs (dict, optional) – Arguments for the nilearn fetcher when masker names one, by default None.

• batch_size (int, default=32) – How many rows are held in dense image form at once. The default is the measured optimum for a 2 mm whole-brain mask, at roughly 60 MB; see the machine learning documentation.

Variables:

• masker (BaseMasker) – The fitted nilearn masker doing the work.

• region_names (list of str or None) – Region names read from the atlas, when it carries any.

• n_features_out (int) – How many columns the fitted masker reports, known once anything has been transformed or named.

Examples

>>> transformer = MaskerTransformer(
...     fetch_atlas_difumo(dimension=64),
...     source_masker=bunch.masker,
... )
>>> smoother = MaskerTransformer(
...     NiftiMasker(smoothing_fwhm=6),
...     source_masker=bunch.masker,
... )

Methods

fit(X[, y])	Resolve the atlas and fit its masker in the source mask's space.
fit_transform(X[, y])	Fit to data, then transform it.
get_feature_names_out([input_features])	Return the region names, from the atlas or from the masker.
get_metadata_routing()	Get metadata routing of this object.
get_params([deep])	Get parameters for this estimator.
inverse_transform(X)	Return region values spread back over the voxels they summarise.
set_output(*[, transform])	Set output container.
set_params(**params)	Set the parameters of this estimator.
transform(X)	Apply the masker to the features.

fit(X, y=None)

Resolve the atlas and fit its masker in the source mask’s space.

Parameters:

• X (array_like or sparse matrix) – Analysis-by-voxel features, used only for their width.

• y (ignored)

Returns:

The fitted transformer.

Return type:

MaskerTransformer

Raises:

ValueError – If nothing was given to apply, if no source masker was given, or if the columns match neither the source masker’s voxels nor its image grid.

fit_transform(X, y=None, **fit_params)

Fit to data, then transform it.

Fits transformer to X and y with optional parameters fit_params and returns a transformed version of X.

Parameters:

• X (array-like of shape (n_samples, n_features)) – Input samples.

• y (array-like of shape (n_samples,) or (n_samples, n_outputs), default=None) – Target values (None for unsupervised transformations).

• **fit_params (dict) – Additional fit parameters. Pass only if the estimator accepts additional params in its fit method.

Returns:

X_new – Transformed array.

Return type:

ndarray array of shape (n_samples, n_features_new)

get_feature_names_out(input_features=None)

Return the region names, from the atlas or from the masker.

Parameters:

input_features (ignored)

Returns:

One name per region column.

Return type:

numpy.ndarray of str

get_metadata_routing()

Get metadata routing of this object.

Please check User Guide on how the routing mechanism works.

Returns:

routing – A MetadataRequest encapsulating routing information.

Return type:

MetadataRequest

get_params(deep=True)

Get parameters for this estimator.

Parameters:

deep (bool, default=True) – If True, will return the parameters for this estimator and contained subobjects that are estimators.

Returns:

params – Parameter names mapped to their values.

Return type:

dict

inverse_transform(X)

Return region values spread back over the voxels they summarise.

Parameters:

X (array_like) – Analysis-by-region features, as transform() returns them.

Returns:

Analysis-by-voxel features, in the space the transformer reads.

Return type:

numpy.ndarray

set_output(*, transform=None)

Set output container.

Refer to the user guide for more details and Introducing the set_output API for an example on how to use the API.

Parameters:

transform ({"default", "pandas", "polars"}, default=None) –

Configure output of transform and fit_transform.

• ”default”: Default output format of a transformer

• ”pandas”: DataFrame output

• ”polars”: Polars output

• None: Transform configuration is unchanged

Added in version 1.4: “polars” option was added.

Returns:

self – Estimator instance.

Return type:

estimator instance

set_params(**params)

Set the parameters of this estimator.

The method works on simple estimators as well as on nested objects (such as Pipeline). The latter have parameters of the form <component>__<parameter> so that it’s possible to update each component of a nested object.

Parameters:

**params (dict) – Estimator parameters.

Returns:

self – Estimator instance.

Return type:

estimator instance

transform(X)

Apply the masker to the features.

Parameters:

X (array_like or sparse matrix) – Analysis-by-voxel features, over the source masker’s voxels or over its image grid, matching what the transformer was fitted on.

Returns:

Analysis-by-region features for an atlas masker, and analysis-by-voxel for a voxel masker.

Return type:

numpy.ndarray

Examples using nimare.ml.MaskerTransformer

Machine learning in NiMARE

Machine learning in NiMARE