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.
7.9.1. 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 maxtype procedure is used to obtain familywise corrected pvalues.
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 tscore amongst data descriptors can be computed directly, which avoids storing all the computed tscores.
The variates should be given Ccontiguous. target_vars are fortranordered automatically to speedup computations.
Parameters: tested_vars : arraylike, shape=(n_samples, n_regressors)
Explanatory variates, fitted and tested independently from each others.
target_vars : arraylike, shape=(n_samples, n_descriptors)
fMRI data, trying to be explained by explanatory and confounding variates.
confounding_vars : arraylike, 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 pvalues estimation.
two_sided_test : boolean,
If True, performs an unsigned ttest. 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 (abs(n_jobs)  1) ones will be used.
verbose: int, optional
verbosity level (0 means no message).
Returns: pvals : arraylike, shape=(n_regressors, n_descriptors)
Negative log10 pvalues associated with the significance test of the n_regressors explanatory variates against the n_descriptors target variates. Familywise corrected pvalues.
score_orig_data : numpy.ndarray, shape=(n_regressors, n_descriptors)
tstatistic 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 pvalues.
h0_fmax : arraylike, shape=(n_perm, )
Distribution of the (max) tstatistic 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), 7588.
 [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), 292298