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.SpaceNetRegressor¶

class nilearn.decoding.SpaceNetRegressor(penalty='graph-net', l1_ratios=0.5, alphas=None, n_alphas=10, mask=None, target_affine=None, target_shape=None, low_pass=None, high_pass=None, t_r=None, max_iter=200, tol=0.0001, memory=None, memory_level=1, standardize=True, verbose=1, n_jobs=1, eps=0.001, cv=8, fit_intercept=True, screening_percentile=20, debias=False, positive=False)[source]¶

Regression learners with sparsity and spatial priors.

SpaceNetRegressor implements Graph-Net and TV-L1 priors / penalties for regression problems. Thus, the penalty is a sum an L1 term and a spatial term. The aim of such a hybrid prior is to obtain weights maps which are structured (due to the spatial prior) and sparse (enforced by L1 norm).

Parameters:

penaltystr, default=’graph-net’: Penalty to used in the model. Can be ‘graph-net’ or ‘tv-l1’.
l1_ratiosfloat or list of floats in the interval [0, 1]; default=0.5: Constant that mixes L1 and spatial prior terms in penalization. l1_ratios == 1 corresponds to pure LASSO. The larger the value of this parameter, the sparser the estimated weights map. If list is provided, then the best value will be selected by cross-validation.
alphasfloat or list of float or None, default=None: Choices for the constant that scales the overall regularization term. This parameter is mutually exclusive with the n_alphas parameter. If None or list of floats is provided, then the best value will be selected by cross-validation.
n_alphasint, default=10: Generate this number of alphas per regularization path. This parameter is mutually exclusive with the alphas parameter.`
maskfilename, niimg, NiftiMasker instance, default=None: Mask to be used on data. If an instance of masker is passed, then its mask will be used. If no mask is it will be computed automatically by a MultiNiftiMasker with default parameters.
target_affinenumpy.ndarray or None, default=None: If specified, the image is resampled corresponding to this new affine. target_affine can be a 3x3 or a 4x4 matrix.
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.
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.
max_iterint, default=200: Maximum number of iterations for the solver.
tolfloat, default=1e-4: Defines the tolerance for convergence.
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=1: Rough estimator of the amount of memory used by caching. Higher value means more memory for caching. Zero means no caching.
standardizebool, default=True: If set, then we’ll center the data (X, y) have mean zero along axis 0. This is here because nearly all linear models will want their data to be centered.
verboseint, default=1: Verbosity level (0 means no message).
n_jobsint, default=1: The number of CPUs to use to do the computation. -1 means ‘all CPUs’.
epsfloat, default=1e-3: Length of the path. For example, eps=1e-3 means that alpha_min / alpha_max = 1e-3
cvint, a cv generator instance, or None, default=8: The input specifying which cross-validation generator to use. It can be an integer, in which case it is the number of folds in a KFold, None, in which case 3 fold is used, or another object, that will then be used as a cv generator.
fit_interceptbool, default=True: Fit or not an intercept.
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.
debiasbool, default=False: If set, then the estimated weights maps will be debiased.
positivebool, default=False: When set to True, forces the coefficients to be positive. This option is only supported for dense arrays.

Added in version 0.12.1.

Attributes:

all_coef_ndarray, shape (n_l1_ratios, n_folds, n_features): Coefficients for all folds and features.
alpha_grids_ndarray, shape (n_folds, n_alphas): Alpha values considered for selection of the best ones (saved in best_model_params_)
best_model_params_ndarray, shape (n_folds, n_parameter): Best model parameters (alpha, l1_ratio) saved for the different cross-validation folds.
coef_ndarray, shape (1, n_features) for 2 class classification problems (i.e n_classes = 2) (n_classes, n_features) for n_classes > 2: Coefficient of the features in the decision function.
coef_img_nifti image: Masked model coefficients
cv_list of pairs of lists: Each pair is the list of indices for the train and test samples for the corresponding fold.
cv_scores_ndarray, shape (n_folds, n_alphas) or (n_l1_ratios, n_folds, n_alphas): Scores (misclassification) for each alpha, and on each fold
intercept_narray, shape: (1,) for 2 class classification problems (i.e n_classes = 2) (n_classes,) for n_classes > 2 Intercept (a.k.a. bias) added to the decision function. It is available only when parameter intercept is set to True.
mask_ndarray 3D: An array contains values of the mask image.
masker_instance of NiftiMasker: The nifti masker used to mask the data.
mask_img_Nifti like image: The mask of the data. If no mask was supplied by the user, this attribute is the mask image computed automatically from the data X.
memory_joblib memory cache
n_elements_int: The number of features in the mask.

Added in version 0.12.1.
screening_percentile_float: Screening percentile corrected according to volume of mask, relative to the volume of standard brain.
w_ndarray, shape: (1, n_features + 1) for 2 class classification problems (i.e n_classes = 2) (n_classes, n_features + 1) for n_classes > 2, and (n_features,) for regression Model weights
Xmean_array, shape (n_features,): Mean of X across samples
Xstd_array, shape (n_features,): Standard deviation of X across samples
ymean_array, shape (n_samples,): Mean of prediction targets

Examples using `nilearn.decoding.SpaceNetRegressor`¶

FREM on Jimura et al “mixed gambles” dataset

FREM on Jimura et al "mixed gambles" dataset

Voxel-Based Morphometry on Oasis dataset with Space-Net prior

nilearn.decoding.SpaceNetRegressor¶

Examples using nilearn.decoding.SpaceNetRegressor¶

Examples using `nilearn.decoding.SpaceNetRegressor`¶