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.

nilearn.mass_univariate.permuted_ols

nilearn.mass_univariate.permuted_ols(tested_vars, target_vars, confounding_vars=None, model_intercept=True, n_perm=10000, two_sided_test=True, random_state=None, n_jobs=1, verbose=0)

Massively univariate group analysis with permuted OLS.

Tested variates are independently fitted to target variates descriptors (e.g. brain imaging signal) according to a linear model solved with an Ordinary Least Squares criterion. Confounding variates may be included in the model. Permutation testing is used to assess the significance of the relationship between the tested variates and the target variates [1, 2]. A max-type procedure is used to obtain family-wise corrected p-values.

The specific permutation scheme implemented here is the one of Freedman & Lane [3]. Its has been demonstrated in [1] that this scheme conveys more sensitivity than alternative schemes. This holds for neuroimaging applications, as discussed in details in [2].

Permutations are performed on parallel computing units. Each of them performs a fraction of permutations on the whole dataset. Thus, the max t-score amongst data descriptors can be computed directly, which avoids storing all the computed t-scores.

The variates should be given C-contiguous. target_vars are fortran-ordered automatically to speed-up computations.

Parameters:

tested_vars : array-like, shape=(n_samples, n_regressors)

Explanatory variates, fitted and tested independently from each others.

target_vars : array-like, shape=(n_samples, n_descriptors)

fMRI data, trying to be explained by explanatory and confounding variates.

confounding_vars : array-like, shape=(n_samples, n_covars)

Confounding variates (covariates), fitted but not tested. If None, no confounding variate is added to the model (except maybe a constant column according to the value of model_intercept)

model_intercept : bool,

If True, a constant column is added to the confounding variates unless the tested variate is already the intercept.

n_perm : int,

Number of permutations to perform. Permutations are costly but the more are performed, the more precision one gets in the p-values estimation.

two_sided_test : boolean,

If True, performs an unsigned t-test. Both positive and negative effects are considered; the null hypothesis is that the effect is zero. If False, only positive effects are considered as relevant. The null hypothesis is that the effect is zero or negative.

random_state : int or None,

Seed for random number generator, to have the same permutations in each computing units.

n_jobs : int,

Number of parallel workers. If 0 is provided, all CPUs are used. A negative number indicates that all the CPUs except (|n_jobs| - 1) ones will be used.

verbose: int, optional :

verbosity level (0 means no message).

Returns:

pvals : array-like, shape=(n_regressors, n_descriptors)

Negative log10 p-values associated with the significance test of the n_regressors explanatory variates against the n_descriptors target variates. Family-wise corrected p-values.

score_orig_data : numpy.ndarray, shape=(n_regressors, n_descriptors)

t-statistic associated with the significance test of the n_regressors explanatory variates against the n_descriptors target variates. The ranks of the scores into the h0 distribution correspond to the p-values.

h0_fmax : array-like, shape=(n_perm, )

Distribution of the (max) t-statistic under the null hypothesis (obtained from the permutations). Array is sorted.

References

[1] Anderson, M. J. & Robinson, J. (2001).

Permutation tests for linear models. Australian & New Zealand Journal of Statistics, 43(1), 75-88.

[2] Winkler, A. M. et al. (2014).

Permutation inference for the general linear model. Neuroimage.

[3] Freedman, D. & Lane, D. (1983).

A nonstochastic interpretation of reported significance levels. J. Bus. Econ. Stats., 1(4), 292-298