Note
This page is a reference documentation. It only explains the function signature, and not how to use it. Please refer to the user guide for the big picture.
8.1.6. nilearn.connectome.group_sparse_covariance¶
- nilearn.connectome.group_sparse_covariance(subjects, alpha, max_iter=50, tol=0.001, verbose=0, probe_function=None, precisions_init=None, debug=False)[source]¶
Compute sparse precision matrices and covariance matrices.
The precision matrices returned by this function are sparse, and share a common sparsity pattern: all have zeros at the same location. This is achieved by simultaneous computation of all precision matrices at the same time.
Running time is linear on max_iter, and number of subjects (len(subjects)), but cubic on number of features (subjects[0].shape[1]).
The present algorithm is based on 1.
- Parameters
- subjectslist of numpy.ndarray
input subjects. Each subject is a 2D array, whose columns contain signals. Each array shape must be (sample number, feature number). The sample number can vary from subject to subject, but all subjects must have the same number of features (i.e. of columns).
- alphafloat
regularization parameter. With normalized covariances matrices and number of samples, sensible values lie in the [0, 1] range(zero is no regularization: output is not sparse)
- max_iterint, optional
maximum number of iterations. Default=50.
- tolpositive float or None, optional
The tolerance to declare convergence: if the duality gap goes below this value, optimization is stopped. If None, no check is performed. Default=1e-3.
- verboseint, optional
verbosity level. Zero means “no message”. Default=0.
- probe_functioncallable or None, optional
This value is called before the first iteration and after each iteration. If it returns True, then optimization is stopped prematurely. The function is given as arguments (in that order):
empirical covariances (ndarray),
number of samples for each subject (ndarray),
regularization parameter (float)
maximum iteration number (integer)
tolerance (float)
current iteration number (integer). -1 means “before first iteration”
current value of precisions (ndarray).
previous value of precisions (ndarray). None before first iteration.
- precisions_initnumpy.ndarray, optional
initial value of the precision matrices. If not provided, a diagonal matrix with the variances of each input signal is used.
- debugbool, optional
if True, perform checks during computation. It can help find numerical problems, but increases computation time a lot. Default=False.
- Returns
- emp_covsnumpy.ndarray, shape (n_features, n_features, n_subjects)
empirical covariances matrices
- precisionsnumpy.ndarray, shape (n_features, n_features, n_subjects)
estimated precision matrices
References
- 1
Jean Honorio, Tommi Jaakkola, and Dimitris Samaras. On the statistical efficiency of l1,p multi-task learning of gaussian graphical models. arXiv:1207.4255 [cs, stat], 10 2015. URL: https://arxiv.org/abs/1207.4255, arXiv:1207.4255.