Note

This page is a reference documentation. It only explains the class signature, and not how to use it. Please refer to the user guide for the big picture.

nilearn.maskers.SurfaceMasker

class nilearn.maskers.SurfaceMasker(mask_img=None, smoothing_fwhm=None, standardize=False, standardize_confounds=True, detrend=False, high_variance_confounds=False, low_pass=None, high_pass=None, t_r=None, memory=None, memory_level=1, verbose=0, reports=True, cmap='inferno', clean_args=None)[source]

Extract data from a SurfaceImage.

Added in Nilearn 0.11.0.

Parameters:
mask_imgSurfaceImage or None, default=None
smoothing_fwhmfloat or int or None, optional.

If smoothing_fwhm is not None, it gives the full-width at half maximum in millimeters of the spatial smoothing to apply to the signal. This parameter is not implemented yet.

standardizeany of: ‘zscore_sample’, ‘zscore’, ‘psc’, True, False or None; default=False

Strategy to standardize the signal:

  • 'zscore_sample': The signal is z-scored. Timeseries are shifted to zero mean and scaled to unit variance. Uses sample std.

  • 'zscore': The signal is z-scored. Timeseries are shifted to zero mean and scaled to unit variance. Uses population std by calling default numpy.std with N - ddof=0.

    Deprecated since Nilearn 0.10.1: This option will be removed in Nilearn version 0.14.0. Use zscore_sample instead.

  • 'psc': Timeseries are shifted to zero mean value and scaled to percent signal change (as compared to original mean signal).

  • True: The signal is z-scored (same as option zscore). Timeseries are shifted to zero mean and scaled to unit variance.

    Deprecated since Nilearn 0.13.0dev: In nilearn version 0.15.0, True will be replaced by 'zscore_sample'.

  • False: Do not standardize the data.

    Deprecated since Nilearn 0.13.0dev: In nilearn version 0.15.0, False will be replaced by None.

Deprecated since Nilearn 0.15.0dev: The default will be changed to None in version 0.15.0.

standardize_confoundsbool, default=True

If set to True, the confounds are z-scored: their mean is put to 0 and their variance to 1 in the time dimension.

detrendbool, optional

Whether to detrend signals or not.

high_variance_confoundsbool, default=False

If True, high variance confounds are computed on provided image with nilearn.image.high_variance_confounds and default parameters and regressed out.

low_passfloat or int or None, default=None

Low cutoff frequency in Hertz. If specified, signals above this frequency will be filtered out. If None, no low-pass filtering will be performed.

high_passfloat or int or None, default=None

High cutoff frequency in Hertz. If specified, signals below this frequency will be filtered out.

t_rfloat or int or None, default=None

Repetition time, in seconds (sampling period). Set to None if not provided.

memoryNone, instance of joblib.Memory, str, or pathlib.Path, default=None

Used to cache the masking process. By default, no caching is done. If a str is given, it is the path to the caching directory.

memory_levelint, default=1

Rough estimator of the amount of memory used by caching. Higher value means more memory for caching. Zero means no caching.

verbosebool or int, default=0

Verbosity level (0 or False means no message).

reportsbool, default=True

If set to True, data is saved in order to produce a report.

cmapmatplotlib.colors.Colormap, or str, optional

The colormap to use. Either a string which is a name of a matplotlib colormap, or a matplotlib colormap object. default=”inferno” Only relevant for the report figures.

clean_argsdict or None, default=None

Keyword arguments to be passed to clean called within the masker. Within clean, kwargs prefixed with 'butterworth__' will be passed to the Butterworth filter.

Attributes:
clean_args_dict

Keyword arguments to be passed to clean called within the masker. Within clean, kwargs prefixed with 'butterworth__' will be passed to the Butterworth filter.

mask_img_A 1D binary SurfaceImage

The mask of the data, or the one computed from imgs passed to fit. If a mask_img is passed at masker construction, then mask_img_ is the resulting binarized version of it where each vertex is True if all values across samples (for example across timepoints) is finite value different from 0.

memory_joblib memory cache
n_elements_int or None

number of vertices included in mask

__init__(mask_img=None, smoothing_fwhm=None, standardize=False, standardize_confounds=True, detrend=False, high_variance_confounds=False, low_pass=None, high_pass=None, t_r=None, memory=None, memory_level=1, verbose=0, reports=True, cmap='inferno', clean_args=None)[source]
fit(imgs=None, y=None)[source]

Prepare signal extraction from regions.

Parameters:
imgsSurfaceImage or list of SurfaceImage or tuple of SurfaceImage or None, default = None

Mesh and data for both hemispheres.

yNone

This parameter is unused. It is solely included for scikit-learn compatibility.

Returns:
SurfaceMasker object
fit_transform(imgs, y=None, confounds=None, sample_mask=None)[source]

Prepare and perform signal extraction from regions.

Parameters:
imgsSurfaceImage object or list of SurfaceImage or tuple of SurfaceImage

Mesh and data for both hemispheres. The data for each hemisphere is of shape (n_vertices_per_hemisphere, n_timepoints).

yNone

This parameter is unused. It is solely included for scikit-learn compatibility.

confoundsnumpy.ndarray, str, pathlib.Path, pandas.DataFrame or list of confounds timeseries, default=None

This parameter is passed to nilearn.signal.clean. Please see the related documentation for details. shape: (number of scans, number of confounds)

sample_maskAny type compatible with numpy-array indexing, default=None

shape = (total number of scans - number of scans removed) for explicit index (for example, sample_mask=np.asarray([1, 2, 4])), or shape = (number of scans) for binary mask (for example, sample_mask=np.asarray([False, True, True, False, True])). Masks the images along the last dimension to perform scrubbing: for example to remove volumes with high motion and/or non-steady-state volumes. This parameter is passed to nilearn.signal.clean.

Returns:
signalsnumpy.ndarray, pandas.DataFrame or polars.DataFrame

Signal for each element.

Changed in Nilearn 0.13.0dev: Added set_output support.

The type of the output is determined by set_output(): see the scikit-learn documentation.

Output shape for :

  • For Numpy outputs:

    • 1D images: (number of elements,)

    • 2D images: (number of scans, number of elements) array

  • For DataFrame outputs:

    • 1D or 2D images: (number of scans, number of elements) array

generate_report(title=None)[source]

Generate an HTML report for the current object.

Parameters:
titlestr or None, default=None

title for the report. If None, title will be the class name.

Returns:
reportnilearn.reporting.html_report.HTMLReport

HTML report for the masker.

get_feature_names_out(input_features=None)

Get output feature names for transformation.

The feature names out will prefixed by the lowercased class name. For example, if the transformer outputs 3 features, then the feature names out are: [“class_name0”, “class_name1”, “class_name2”].

Parameters:
input_featuresarray-like of str or None, default=None

Only used to validate feature names with the names seen in fit.

Returns:
feature_names_outndarray of str objects

Transformed feature names.

get_metadata_routing()

Get metadata routing of this object.

Please check User Guide on how the routing mechanism works.

Returns:
routingMetadataRequest

A MetadataRequest encapsulating routing information.

get_params(deep=True)

Get parameters for this estimator.

Parameters:
deepbool, default=True

If True, will return the parameters for this estimator and contained subobjects that are estimators.

Returns:
paramsdict

Parameter names mapped to their values.

inverse_transform(signals)[source]

Transform extracted signal back to surface object.

Parameters:
signals1D/2D numpy.ndarray

Extracted signal. If a 1D array is provided, then the shape should be (number of elements,). If a 2D array is provided, then the shape should be (number of scans, number of elements).

Returns:
imgSurfaceImage

Signal for each vertex projected on the mesh. Output shape for :

See Input and output: neuroimaging data representation.

set_fit_request(*, imgs='$UNCHANGED$')

Configure whether metadata should be requested to be passed to the fit method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

  • True: metadata is requested, and passed to fit if provided. The request is ignored if metadata is not provided.

  • False: metadata is not requested and the meta-estimator will not pass it to fit.

  • None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.

  • str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Parameters:
imgsstr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for imgs parameter in fit.

Returns:
selfobject

The updated object.

set_inverse_transform_request(*, signals='$UNCHANGED$')

Configure whether metadata should be requested to be passed to the inverse_transform method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

  • True: metadata is requested, and passed to inverse_transform if provided. The request is ignored if metadata is not provided.

  • False: metadata is not requested and the meta-estimator will not pass it to inverse_transform.

  • None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.

  • str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Parameters:
signalsstr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for signals parameter in inverse_transform.

Returns:
selfobject

The updated object.

set_output(*, transform=None)

Set output container.

See 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:
selfestimator instance

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:
**paramsdict

Estimator parameters.

Returns:
selfestimator instance

Estimator instance.

set_transform_request(*, confounds='$UNCHANGED$', imgs='$UNCHANGED$', sample_mask='$UNCHANGED$')

Configure whether metadata should be requested to be passed to the transform method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

  • True: metadata is requested, and passed to transform if provided. The request is ignored if metadata is not provided.

  • False: metadata is not requested and the meta-estimator will not pass it to transform.

  • None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.

  • str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Parameters:
confoundsstr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for confounds parameter in transform.

imgsstr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for imgs parameter in transform.

sample_maskstr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for sample_mask parameter in transform.

Returns:
selfobject

The updated object.

transform(imgs, confounds=None, sample_mask=None)[source]

Apply mask, spatial and temporal preprocessing.

Parameters:
imgsSurfaceImage object or iterable of SurfaceImage

Images to process.

confoundsnumpy.ndarray, str, pathlib.Path, pandas.DataFrame or list of confounds timeseries, default=None

This parameter is passed to nilearn.signal.clean. Please see the related documentation for details. shape: (number of scans, number of confounds)

sample_maskAny type compatible with numpy-array indexing, default=None

shape = (total number of scans - number of scans removed) for explicit index (for example, sample_mask=np.asarray([1, 2, 4])), or shape = (number of scans) for binary mask (for example, sample_mask=np.asarray([False, True, True, False, True])). Masks the images along the last dimension to perform scrubbing: for example to remove volumes with high motion and/or non-steady-state volumes. This parameter is passed to nilearn.signal.clean.

Returns:
signalsnumpy.ndarray, pandas.DataFrame or polars.DataFrame

Signal for each element.

Changed in Nilearn 0.13.0dev: Added set_output support.

The type of the output is determined by set_output(): see the scikit-learn documentation.

Output shape for :

  • For Numpy outputs:

    • 1D images: (number of elements,)

    • 2D images: (number of scans, number of elements) array

  • For DataFrame outputs:

    • 1D or 2D images: (number of scans, number of elements) array

transform_single_imgs(imgs, confounds=None, sample_mask=None)[source]

Extract signals from fitted surface object.

Parameters:
imgsimgsSurfaceImage object or iterable of SurfaceImage

Images to process. Mesh and data for both hemispheres/parts.

confoundsnumpy.ndarray, str, pathlib.Path, pandas.DataFrame or list of confounds timeseries, default=None

This parameter is passed to nilearn.signal.clean. Please see the related documentation for details. shape: (number of scans, number of confounds)

sample_maskAny type compatible with numpy-array indexing, default=None

shape = (total number of scans - number of scans removed) for explicit index (for example, sample_mask=np.asarray([1, 2, 4])), or shape = (number of scans) for binary mask (for example, sample_mask=np.asarray([False, True, True, False, True])). Masks the images along the last dimension to perform scrubbing: for example to remove volumes with high motion and/or non-steady-state volumes. This parameter is passed to nilearn.signal.clean.

Returns:
signalsnumpy.ndarray, pandas.DataFrame or polars.DataFrame

Signal for each element.

Changed in Nilearn 0.13.0dev: Added set_output support.

The type of the output is determined by set_output(): see the scikit-learn documentation.

Output shape for :

  • For Numpy outputs:

    • 1D images: (number of elements,)

    • 2D images: (number of scans, number of elements) array

  • For DataFrame outputs:

    • 1D or 2D images: (number of scans, number of elements) array

Examples using nilearn.maskers.SurfaceMasker

A short demo of the surface images & maskers

A short demo of the surface images & maskers