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.

7.4.2. nilearn.decomposition.DictLearning

class nilearn.decomposition.DictLearning(n_components=20, n_epochs=1, alpha=10, reduction_ratio='auto', dict_init=None, random_state=None, batch_size=20, method='cd', mask=None, smoothing_fwhm=4, standardize=True, detrend=True, low_pass=None, high_pass=None, t_r=None, target_affine=None, target_shape=None, mask_strategy='epi', mask_args=None, n_jobs=1, verbose=0, memory=Memory(cachedir=None), memory_level=0)

Perform a map learning algorithm based on spatial component sparsity, over a CanICA initialization. This yields more stable maps than CanICA.

New in version 0.2.

Parameters:

mask: Niimg-like object or MultiNiftiMasker instance, optional

Mask to be used on data. If an instance of masker is passed, then its mask will be used. If no mask is given, it will be computed automatically by a MultiNiftiMasker with default parameters.

n_components: int

Number of components to extract.

batch_size : int, optional, default=20

The number of samples to take in each batch.

n_epochs: float

Number of epochs the algorithm should run on the data.

alpha: float, optional, default=1

Sparsity controlling parameter.

dict_init: Niimg-like object, optional

Initial estimation of dictionary maps. Would be computed from CanICA if not provided.

reduction_ratio: ‘auto’ or float between 0. and 1.

  • Between 0. or 1. : controls data reduction in the temporal domain. 1. means no reduction, < 1. calls for an SVD based reduction.
  • if set to ‘auto’, estimator will set the number of components per reduced session to be n_components.

method : {‘lars’, ‘cd’}

Coding method used by sklearn backend. Below are the possible values. lars: uses the least angle regression method to solve the lasso problem (linear_model.lars_path) cd: uses the coordinate descent method to compute the Lasso solution (linear_model.Lasso). Lars will be faster if the estimated components are sparse.

random_state: int or RandomState

Pseudo number generator state used for random sampling.

smoothing_fwhm: float, optional

If smoothing_fwhm is not None, it gives the size in millimeters of the spatial smoothing to apply to the signal.

standardize : boolean, optional

If standardize is True, the time-series are centered and normed: their variance is put to 1 in the time dimension.

target_affine: 3x3 or 4x4 matrix, optional

This parameter is passed to image.resample_img. Please see the related documentation for details.

target_shape: 3-tuple of integers, optional

This parameter is passed to image.resample_img. Please see the related documentation for details.

low_pass: None or float, optional

This parameter is passed to signal.clean. Please see the related documentation for details.

high_pass: None or float, optional

This parameter is passed to signal.clean. Please see the related documentation for details.

t_r: float, optional

This parameter is passed to signal.clean. Please see the related documentation for details.

memory: instance of joblib.Memory or string

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

memory_level: integer, optional

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

n_jobs: integer, optional, default=1

The number of CPUs to use to do the computation. -1 means ‘all CPUs’, -2 ‘all CPUs but one’, and so on.

verbose: integer, optional

Indicate the level of verbosity. By default, nothing is printed.

References

  • Arthur Mensch, Gael Varoquaux, Bertrand Thirion, Compressed online dictionary learning for fast resting-state fMRI decomposition. IEEE 13th International Symposium on Biomedical Imaging (ISBI), 2016. pp. 1282-1285
__init__(n_components=20, n_epochs=1, alpha=10, reduction_ratio='auto', dict_init=None, random_state=None, batch_size=20, method='cd', mask=None, smoothing_fwhm=4, standardize=True, detrend=True, low_pass=None, high_pass=None, t_r=None, target_affine=None, target_shape=None, mask_strategy='epi', mask_args=None, n_jobs=1, verbose=0, memory=Memory(cachedir=None), memory_level=0)
fit(imgs, y=None, confounds=None)

Compute the mask and component maps across subjects

Parameters:

imgs: list of Niimg-like objects

See http://nilearn.github.io/manipulating_images/input_output.html Data on which PCA must be calculated. If this is a list, the affine is considered the same for all.

confounds: CSV file path or 2D matrix

This parameter is passed to nilearn.signal.clean. Please see the related documentation for details

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 : numpy array of shape [n_samples, n_features]

Training set.

y : numpy array of shape [n_samples]

Target values.

Returns:

X_new : numpy array of shape [n_samples, n_features_new]

Transformed array.

get_params(deep=True)

Get parameters for this estimator.

Parameters:

deep : boolean, optional

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

Returns:

params : mapping of string to any

Parameter names mapped to their values.

inverse_transform(loadings)

Use provided loadings to compute corresponding linear component combination in whole-brain voxel space

Parameters:

loadings: list of numpy array (n_samples x n_components)

Component signals to tranform back into voxel signals

Returns:

reconstructed_imgs: list of nibabel.Nifti1Image

For each loading, reconstructed Nifti1Image

score(imgs, confounds=None)

Score function based on explained variance on imgs.

Should only be used by DecompositionEstimator derived classes

Parameters:

imgs: iterable of Niimg-like objects

confounds: CSV file path or 2D matrix

This parameter is passed to nilearn.signal.clean. Please see the related documentation for details

Returns:

score: float,

Holds the score for each subjects. Score is two dimensional if per_component is True. First dimension is squeezed if the number of subjects is one

set_params(**params)

Set the parameters of this estimator.

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

Returns:self
transform(imgs, confounds=None)

Project the data into a reduced representation

Parameters:

imgs: iterable of Niimg-like objects

confounds: CSV file path or 2D matrix

This parameter is passed to nilearn.signal.clean. Please see the related documentation for details

Returns:

loadings: list of 2D ndarray,

For each subject, each sample, loadings for each decomposition components shape: number of subjects * (number of scans, number of regions)