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
>>> 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()
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 | |
stat | Constants/functions for interpreting results of os.stat() and os.lstat(). |
z_score(pvalue) | Return the z-score corresponding to a given p-value. |
Parameters : | effect: array of shape (contrast_dim, n_voxels) :
variance: array of shape (contrast_dim, contrast_dim, n_voxels) :
dof: scalar, the degrees of freedom : contrast_type: string to be chosen among ‘t’ and ‘F’ : |
---|
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 : |
---|
Return the decision statistic associated with the test of the null hypothesis: (H0) ‘contrast equals baseline’
Parameters : | baseline: float, optional, :
|
---|
Return a parametric estimation of the z-score associated with the null hypothesis: (H0) ‘contrast equals baseline’
Parameters : | baseline: float, optional, :
|
---|
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 | |
fit |
Load the data
Parameters : | fmri_data : Image or str or sequence of Images / str
design_matrices : arrays or str or sequence of arrays / str
mask : str or Image or None, optional
m, M, threshold: float, optional :
|
---|
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
>>> np.sum(z_image.get_data() > 3.09)
671
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)
con_id : str, optional
contrast_type : {‘t’, ‘F’, ‘tmin-conjunction’}, optional
output_z : bool, optional
output_stat : bool, optional
output_effects : bool, optional
output_variance : bool, optional
|
---|---|
Returns : | output_images : list of nibabel images
|
Load the data, mask the data, scale the data, fit the GLM
Parameters : | do_scaling : bool, optional
model : string, optional,
steps : int, optional
|
---|
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:
Methods
contrast | |
fit | |
get_beta | |
get_logL | |
get_mse |
Parameters : | X : array of shape (n_time_points, n_regressors)
|
---|
Specify and estimate a linear contrast
Parameters : | con_val : numpy.ndarray of shape (p) or (q, p)
contrast_type : {None, ‘t’, ‘F’ or ‘tmin-conjunction’}, optional
|
---|---|
Returns : | con: Contrast instance : |
GLM fitting of a dataset using ‘ols’ regression or the two-pass
Parameters : | Y : array of shape(n_time_points, n_samples)
model : {‘ar1’, ‘ols’}, optional
steps : int, optional
|
---|
Acessor for the best linear unbiased estimated of model parameters
Parameters : | column_index: int or array-like of int or None, optional :
|
---|---|
Returns : | beta: array of shape (n_voxels, n_columns) :
|
Acessor for the log-likelihood of the model
Returns : | logL: array of shape (n_voxels,) :
|
---|
Acessor for the mean squared error of the model
Returns : | mse: array of shape (n_voxels) :
|
---|
Scaling of the data to have pourcent of baseline change columnwise
Parameters : | Y: array of shape(n_time_points, n_voxels) :
|
---|---|
Returns : | Y: array of shape (n_time_points, n_voxels), :
mean : array of shape (n_voxels,)
|