modalities.fmri.glm¶
Module: modalities.fmri.glm
¶
Inheritance diagram for nipy.modalities.fmri.glm
:

This module presents an interface to use the glm implemented in nipy.algorithms.statistics.models.regression.
It contains the GLM and contrast classes that are meant to be the main objects of fMRI data analyses.
It is important to note that the GLM is meant as a one-session General Linear Model. But inference can be performed on multiple sessions by computing fixed effects on contrasts
Examples¶
>>> import numpy as np
>>> from nipy.modalities.fmri.glm import GeneralLinearModel
>>> n, p, q = 100, 80, 10
>>> X, Y = np.random.randn(p, q), np.random.randn(p, n)
>>> cval = np.hstack((1, np.zeros(9)))
>>> model = GeneralLinearModel(X)
>>> model.fit(Y)
>>> z_vals = model.contrast(cval).z_score() # z-transformed statistics
Example of fixed effects statistics across two contrasts
>>> cval_ = cval.copy()
>>> np.random.shuffle(cval_)
>>> z_ffx = (model.contrast(cval) + model.contrast(cval_)).z_score()
Classes¶
Contrast
¶
-
class
nipy.modalities.fmri.glm.
Contrast
(effect, variance, dof=10000000000.0, contrast_type='t', tiny=1e-50, dofmax=10000000000.0)¶ Bases:
object
The contrast class handles the estimation of statistical contrasts on a given model: student (t), Fisher (F), conjunction (tmin-conjunction). The important feature is that it supports addition, thus opening the possibility of fixed-effects models.
The current implementation is meant to be simple, and could be enhanced in the future on the computational side (high-dimensional F constrasts may lead to memory breakage).
Notes
The ‘tmin-conjunction’ test is the valid conjunction test discussed in: Nichols T, Brett M, Andersson J, Wager T, Poline JB. Valid conjunction inference with the minimum statistic. Neuroimage. 2005 Apr 15;25(3):653-60. This test gives the p-value of the z-values under the conjunction null, i.e. the union of the null hypotheses for all terms.
Methods
p_value
([baseline])Return a parametric estimate of the p-value associated stat
([baseline])Return the decision statistic associated with the test of the z_score
([baseline])Return a parametric estimation of the z-score associated -
__init__
(effect, variance, dof=10000000000.0, contrast_type='t', tiny=1e-50, dofmax=10000000000.0)¶ Parameters: effect: array of shape (contrast_dim, n_voxels) :
the effects related to the contrast
variance: array of shape (contrast_dim, contrast_dim, n_voxels) :
the associated variance estimate
dof: scalar, the degrees of freedom :
contrast_type: string to be chosen among ‘t’ and ‘F’ :
-
p_value
(baseline=0.0)¶ Return a parametric estimate of the p-value associated with the null hypothesis: (H0) ‘contrast equals baseline’
Parameters: baseline: float, optional, :
Baseline value for the test statistic :
-
stat
(baseline=0.0)¶ Return the decision statistic associated with the test of the null hypothesis: (H0) ‘contrast equals baseline’
Parameters: baseline: float, optional, :
Baseline value for the test statistic
-
z_score
(baseline=0.0)¶ Return a parametric estimation of the z-score associated with the null hypothesis: (H0) ‘contrast equals baseline’
Parameters: baseline: float, optional, :
Baseline value for the test statistic
-
FMRILinearModel
¶
-
class
nipy.modalities.fmri.glm.
FMRILinearModel
(fmri_data, design_matrices, mask='compute', m=0.2, M=0.9, threshold=0.5)¶ Bases:
object
This class is meant to handle GLMs from a higher-level perspective i.e. by taking images as input and output
Methods
contrast
(contrasts[, con_id, contrast_type, …])Estimation of a contrast as fixed effects on all sessions fit
([do_scaling, model, steps])Load the data, mask the data, scale the data, fit the GLM -
__init__
(fmri_data, design_matrices, mask='compute', m=0.2, M=0.9, threshold=0.5)¶ Load the data
Parameters: fmri_data : Image or str or sequence of Images / str
fmri images / paths of the (4D) fmri images
design_matrices : arrays or str or sequence of arrays / str
design matrix arrays / paths of .npz files
mask : str or Image or None, optional
string can be ‘compute’ or a path to an image image is an input (assumed binary) mask image(s), if ‘compute’, the mask is computed if None, no masking will be applied
m, M, threshold: float, optional :
parameters of the masking procedure. Should be within [0, 1]
Notes
The only computation done here is mask computation (if required)
Examples
We need the example data package for this example:
from nipy.utils import example_data from nipy.modalities.fmri.glm import FMRILinearModel fmri_files = [example_data.get_filename('fiac', 'fiac0', run) for run in ['run1.nii.gz', 'run2.nii.gz']] design_files = [example_data.get_filename('fiac', 'fiac0', run) for run in ['run1_design.npz', 'run2_design.npz']] mask = example_data.get_filename('fiac', 'fiac0', 'mask.nii.gz') multi_session_model = FMRILinearModel(fmri_files, design_files, mask) multi_session_model.fit() z_image, = multi_session_model.contrast([np.eye(13)[1]] * 2) # The number of voxels with p < 0.001 given by ... print(np.sum(z_image.get_data() > 3.09))
-
contrast
(contrasts, con_id='', contrast_type=None, output_z=True, output_stat=False, output_effects=False, output_variance=False)¶ Estimation of a contrast as fixed effects on all sessions
Parameters: contrasts : array or list of arrays of shape (n_col) or (n_dim, n_col)
where
n_col
is the number of columns of the design matrix, numerical definition of the contrast (one array per run)con_id : str, optional
name of the contrast
contrast_type : {‘t’, ‘F’, ‘tmin-conjunction’}, optional
type of the contrast
output_z : bool, optional
Return or not the corresponding z-stat image
output_stat : bool, optional
Return or not the base (t/F) stat image
output_effects : bool, optional
Return or not the corresponding effect image
output_variance : bool, optional
Return or not the corresponding variance image
Returns: output_images : list of nibabel images
The required output images, in the following order: z image, stat(t/F) image, effects image, variance image
-
fit
(do_scaling=True, model='ar1', steps=100)¶ Load the data, mask the data, scale the data, fit the GLM
Parameters: do_scaling : bool, optional
if True, the data should be scaled as percent of voxel mean
model : string, optional,
the kind of glm (‘ols’ or ‘ar1’) you want to fit to the data
steps : int, optional
in case of an ar1, discretization of the ar1 parameter
-
GeneralLinearModel
¶
-
class
nipy.modalities.fmri.glm.
GeneralLinearModel
(X)¶ Bases:
object
This class handles the so-called on General Linear Model
Most of what it does in the fit() and contrast() methods fit() performs the standard two-step (‘ols’ then ‘ar1’) GLM fitting contrast() returns a contrast instance, yileding statistics and p-values. The link between fit() and constrast is done vis the two class members:
- glm_results : dictionary of nipy.algorithms.statistics.models.
- regression.RegressionResults instances, describing results of a GLM fit
- labels : array of shape(n_voxels),
- labels that associate each voxel with a results key
Methods
contrast
(con_val[, contrast_type])Specify and estimate a linear contrast fit
(Y[, model, steps])GLM fitting of a dataset using ‘ols’ regression or the two-pass get_beta
([column_index])Accessor for the best linear unbiased estimated of model parameters get_logL
()Accessor for the log-likelihood of the model get_mse
()Accessor for the mean squared error of the model -
__init__
(X)¶ Parameters: X : array of shape (n_time_points, n_regressors)
the design matrix
-
contrast
(con_val, contrast_type=None)¶ Specify and estimate a linear contrast
Parameters: con_val : numpy.ndarray of shape (p) or (q, p)
where q = number of contrast vectors and p = number of regressors
contrast_type : {None, ‘t’, ‘F’ or ‘tmin-conjunction’}, optional
type of the contrast. If None, then defaults to ‘t’ for 1D con_val and ‘F’ for 2D con_val
Returns: con: Contrast instance :
-
fit
(Y, model='ols', steps=100)¶ GLM fitting of a dataset using ‘ols’ regression or the two-pass
Parameters: Y : array of shape(n_time_points, n_samples)
the fMRI data
model : {‘ar1’, ‘ols’}, optional
the temporal variance model. Defaults to ‘ols’
steps : int, optional
Maximum number of discrete steps for the AR(1) coef histogram
-
get_beta
(column_index=None)¶ Accessor for the best linear unbiased estimated of model parameters
Parameters: column_index: int or array-like of int or None, optional :
The indexed of the columns to be returned. if None (default behaviour), the whole vector is returned
Returns: beta: array of shape (n_voxels, n_columns) :
the beta
-
get_logL
()¶ Accessor for the log-likelihood of the model
Returns: logL: array of shape (n_voxels,) :
the sum of square error per voxel
-
get_mse
()¶ Accessor for the mean squared error of the model
Returns: mse: array of shape (n_voxels) :
the sum of square error per voxel
Function¶
-
nipy.modalities.fmri.glm.
data_scaling
(Y)¶ Scaling of the data to have percent of baseline change columnwise
Parameters: Y: array of shape(n_time_points, n_voxels) :
the input data
Returns: Y: array of shape (n_time_points, n_voxels), :
the data after mean-scaling, de-meaning and multiplication by 100
mean : array of shape (n_voxels,)
the data mean