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.decoding.DecoderRegressor¶

class nilearn.decoding.DecoderRegressor(estimator='svr', mask=None, cv=10, param_grid=None, screening_percentile=20, scoring='r2', smoothing_fwhm=None, standardize=True, target_affine=None, target_shape=None, mask_strategy='background', low_pass=None, high_pass=None, t_r=None, memory=None, memory_level=0, n_jobs=1, verbose=0)[source]¶

A wrapper for popular regression strategies in neuroimaging.

The DecoderRegressor object supports regression methods. It implements a model selection scheme that averages the best models within a cross validation loop. The resulting average model is the one used as a regressor. This object also leverages the NiftiMaskers to provide a direct interface with the Nifti files on disk.

Parameters:

estimatorstr, optional

The estimator to choose among:

ridge: {Ridge regression}.

ridge = RidgeCV()

ridge_regressor: {Ridge regression}.

Note

Same option as ridge.

svr: {Support vector regression}.

svr = SVR(kernel="linear", max_iter=1e4)

lasso: {Lasso regression}.

lasso = LassoCV()

lasso_regressor: {Lasso regression}.

Note

Same option as lasso.

dummy_regressor: {Dummy regressor}.

dummy = DummyRegressor(strategy="mean")

Default ‘svr’.

maskfilename, Nifti1Image, NiftiMasker, or MultiNiftiMasker, optional

Mask to be used on data. If an instance of masker is passed, then its mask and parameters will be used. If no mask is given, mask will be computed automatically from provided images by an inbuilt masker with default parameters. Refer to NiftiMasker or MultiNiftiMasker to check for default parameters. Default None

cvcross-validation generator, int or None, default=10

A cross-validation generator. See: https://scikit-learn.org/stable/modules/cross_validation.html. If None is passed, cv=10 will be used. It can be an integer, in which case it is the number of folds in a KFold using StratifiedKFold when groups is None in the fit method for this class. If groups is specified but cv is not set to custom CV splitter, default is LeaveOneGroupOut.

param_griddict of str to sequence, or sequence of such, or None, default=None

The parameter grid to explore, as a dictionary mapping estimator parameters to sequences of allowed values.

None or an empty dict signifies default parameters.

A sequence of dicts signifies a sequence of grids to search, and is useful to avoid exploring parameter combinations that make no sense or have no effect. See scikit-learn documentation for more information, for example: https://scikit-learn.org/stable/modules/grid_search.html

For DummyRegressor, parameter grid defaults to empty dictionary, class predictions are estimated using default strategy.

screening_percentileint, float, in the closed interval [0, 100], or None, default=20

Percentile value for ANOVA univariate feature selection. If None is passed, it will be set to 100. A value of 100 means “keep all features”. This percentile is expressed with respect to the volume of either a standard (MNI152) brain (if mask_img_ is a 3D volume) or a the number of vertices in the mask mesh (if mask_img_ is a SurfaceImage). This means that the screening_percentile is corrected at runtime by premultiplying it with the ratio of volume of the standard brain to the volume of the mask of the data.

Note

If the mask used is too small compared to the total brain volume / surface, then all its elements (voxels / vertices) may be included even for very small screening_percentile.

scoringstr, callable or None, optional. default=’r2’

The scoring strategy to use. See the scikit-learn documentation at https://scikit-learn.org/stable/modules/model_evaluation.html#the-scoring-parameter-defining-model-evaluation-rules If callable, takes as arguments the fitted estimator, the test data (X_test) and the test target (y_test) if y is not None. e.g. scorer(estimator, X_test, y_test)

For regression, valid entries are: ‘r2’, ‘neg_mean_absolute_error’, or ‘neg_mean_squared_error’.

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.

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

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.10.1: The default will be changed to 'zscore_sample' and 'zscore' will be removed in in version 0.14.0.

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

target_affine3x3 or a 4x4 array-like, or None, default=None

If specified, the image is resampled corresponding to this new affine.

target_shapetuple or list or None, default=None

If specified, the image will be resized to match this new shape. len(target_shape) must be equal to 3.

Note

If target_shape is specified, a target_affine of shape (4, 4) must also be given.

mask_strategy{“background”, “epi”, “whole-brain-template”,”gm-template”, “wm-template”}, optional

The strategy used to compute the mask:

"background": Use this option if your images present a clear homogeneous background. Uses nilearn.masking.compute_background_mask under the hood.
"epi": Use this option if your images are raw EPI images. Uses nilearn.masking.compute_epi_mask.
"whole-brain-template": This will extract the whole-brain part of your data by resampling the MNI152 brain mask for your data’s field of view. Uses nilearn.masking.compute_brain_mask with mask_type="whole-brain".

Note

This option is equivalent to the previous ‘template’ option which is now deprecated.
"gm-template": This will extract the gray matter part of your data by resampling the corresponding MNI152 template for your data’s field of view. Uses nilearn.masking.compute_brain_mask with mask_type="gm".

Added in Nilearn 0.8.1.
"wm-template": This will extract the white matter part of your data by resampling the corresponding MNI152 template for your data’s field of view. Uses nilearn.masking.compute_brain_mask with mask_type="wm".

Added in Nilearn 0.8.1.

Note

This parameter will be ignored if a mask image is provided.

Note

Depending on this value, the mask will be computed from nilearn.masking.compute_background_mask, nilearn.masking.compute_epi_mask, or nilearn.masking.compute_brain_mask.

Default=’background’.

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

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=0

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

n_jobsint, default=1

The number of CPUs to use to do the computation. -1 means ‘all CPUs’.

verboseint, default=0

Verbosity level (0 means no message).

Attributes:

coef_numpy.ndarray, shape=(n_classes, n_features): Contains the mean of the models weight vector across fold for each class. Returns None for Dummy estimators.
coef_img_dict of Nifti1Image: Dictionary containing coef_ with class names as keys, and coef_ transformed in Nifti1Images as values. In the case of a regression, it contains a single Nifti1Image at the key ‘beta’. Ignored if Dummy estimators are provided.
cv_list of pairs of lists: List of the (n_folds,) folds. For the corresponding fold, each pair is composed of two lists of indices, one for the train samples and one for the test samples.
cv_params_dict of list: Best point in the parameter grid for each tested fold in the inner cross validation loop. The grid is empty when Dummy estimators are provided.

Note

If the estimator used its built-in cross-validation, this will include an additional key for the single best value estimated by the built-in cross-validation (‘best_C’ for LogisticRegressionCV and ‘best_alpha’ for RidgeCV/RidgeClassifierCV/LassoCV), in addition to the input list of values.
cv_scores_dict, (classes, n_folds): Scores (misclassification) for each parameter, and on each fold
dummy_output_ndarray, shape=(n_classes, 2) or shape=(1, 1) for regression: Contains dummy estimator attributes after class predictions using strategies of sklearn.dummy.DummyClassifier (class_prior) and sklearn.dummy.DummyRegressor (constant) from scikit-learn. This attribute is necessary for estimating class predictions after fit. Returns None if non-dummy estimators are provided.
estimator_Estimator object used during decoding.
intercept_ndarray, shape (nclasses,): Intercept (also known as bias) added to the decision function. Ignored if Dummy estimators are provided.
mask_img_Nifti1Image or SurfaceImage: Mask computed by the masker object.
masker_instance of NiftiMasker, MultiNiftiMasker, or SurfaceMasker: The masker used to mask the data.
memory_joblib memory cache
n_elements_int: The number of voxels or vertices in the mask.

Added in Nilearn 0.12.1.
n_outputs_int: Number of outputs (column-wise)
scorer_function: Scorer function used on the held out data to choose the best parameters for the model.
screening_percentile_float: Percentile value for ANOVA univariate feature selection. A value of 100 means ‘keep all features’. This percentile is expressed with respect to the volume of either a standard (MNI152) brain (if mask_img is a 3D volume) or a the number of vertices in the mask mesh (if mask_img is a SurfaceImage).
std_coef_numpy.ndarray, shape=(n_classes, n_features): Contains the standard deviation of the models weight vector across fold for each class. Note that folds are not independent, see https://scikit-learn.org/stable/modules/cross_validation.html#cross-validation-iterators-for-grouped-data Ignored if Dummy estimators are provided.
std_coef_img_dict of Nifti1Image: Dictionary containing std_coef_ with class names as keys, and coef_ transformed in Nifti1Image as values. In the case of a regression, it contains a single Nifti1Image at the key ‘beta’. Ignored if Dummy estimators are provided.

Examples using `nilearn.decoding.DecoderRegressor`¶

Voxel-Based Morphometry on Oasis dataset

nilearn.decoding.DecoderRegressor¶

Examples using nilearn.decoding.DecoderRegressor¶

Examples using `nilearn.decoding.DecoderRegressor`¶