NIPY logo

Site Navigation

NIPY Community

Table Of Contents

Previous topic

neurospin.glm_files_layout.cortical_glm

Next topic

neurospin.glm_files_layout.html_result

This Page

neurospin.glm_files_layout.glm_tools

Module: neurospin.glm_files_layout.glm_tools

This module contains several utiility functions to perform GLM on datasets that are organized according to the layout chosen in brainvisa. It is thus assumed that: 1. within a certain ‘base_path’ directory(*),

there are directories named with a certain session_id, that contain the fMRI data ready to analyse
  1. optionally, within the ‘base_path’ directory, there is also a ‘Minf’ directory that contains a .csv file that describes the paradigm used.
(*) the basepath directory is intended to correspond
to a session of acquistion of a given subjects. It can contains multiple sessions.

Based on this architecture, the module conatins functionalities to - estimate the design matrix - load the data - estimate the linear model - estimate contrasts related to the linear model - write output imges - write an html page that summarizes the results

Note that contrast specification relied on the contrast_tools module

Author : Lise Favre, Bertrand Thirion, 2008-2010

Functions

nipy.neurospin.glm_files_layout.glm_tools.compute_contrasts(contrast_struct, misc, CompletePaths, glms=None, model='default', **kargs)

Contrast computation utility

Parameters :

contrast_struct, ConfigObj instance or string :

it yields the set of contrasts of the multi-session model or the path to a configobj that specifies the contrasts

misc: misc object instance, :

misc information on the datasets used here or path to a configobj file that yields the misc info

Complete_Paths: dictionary or string, :

yields all paths, indexed by contrasts, where outputs will be written if it is a string, all the paths are re-generated based on it as a output directory

glms, dictionary of nipy.neurospin.glm.glm.glm instances :

indexed by sessions, optional if it is not provided, a ‘glm_config’ instance should be provided in kargs

model=’default’, string, :

name of the contrast model used in miscfile

nipy.neurospin.glm_files_layout.glm_tools.design_matrix(misc_file, output_file, session, paradigm_file, frametimes, hrf_model='Canonical', drift_model='Blank', add_regs=None, drift_order=2, hfcut=128, fir_delays=[, 0], fir_duration=1.0, model='default', add_reg_names=None, verbose=0)

Estimation of the design matrix and update of misc info

Parameters :

misc_file: string, :

path of misc info file that is updated with info on design matrix

output_file: string, :

path of the (.csv) file where the design matrix shall be written

session: string, :

id of the session

paradigm_file: string, :

path of (.csv) paradigm-describing file or None, if no such file exists

concerning the following parameters, please refer to :

nipy.neurospin.utils.design_matrix :

Returns :

dmtx: nipy.neurospin.utils.design_matrix.DesignMatrix :

instance

nipy.neurospin.glm_files_layout.glm_tools.generate_all_brainvisa_paths(base_path, sessions, fmri_wc, model_id, misc_id='misc_info.con', mask_id='mask.nii', paradigm_id='paradigm.csv', contrast_id='contrast.con', design_id='design_mat.csv', glm_dump='vba.npz', glm_config='vba_config.con')

This function returns a dictionary with all the paths of all the paths where something id read or written in a standard GLM. The hard-coded paths reflect brainvisa database conventions. Additionally, this creates the missing output directories.

Parameters :

base_path: string, :

path of the acquition (contains database, subject and acquitision ids)

sessions: list of strings :

list of all the session related to the acquisition

fmri_wc: string, :

wildcard for fMRI data files, assumed to be the same for all sessions

model_id: string, :

identifier of the model

misc_id: string, optional :

identifier of the ‘misc file’ that contains meta-information

mask_id: string, optional :

file id of the mask image

paradigm_id: string, optional :

identifier of the paradigm file (should be a .csv file)

contrast_id: string, optional :

id of the contrast file

design_id: string, optional :

id of the design matrices file

glm_dump: string, optional, :

id of the glm dump file (should be .npz file)

glm_config: string, optional, :

id of the glm config file (should disappear in the near future)

Returns :

paths, dictionary :

containing all the paths that are required to perform a glm with brainvisa

nipy.neurospin.glm_files_layout.glm_tools.generate_brainvisa_ouput_paths(output_dir_path, contrasts, z_file=True, stat_file=True, con_file=True, res_file=True, html_file=True)

This function generate standard output paths for all the contrasts and arranges them in a dictionary

Parameters :

output_dir_path: string, :

path of the output dir

contrasts: ConfigObj instance, :

contrast_structure

z_file: bool, optional :

whether the z_file should be written or not

stat_file: bool, optional :

whether the stat file (t or F) should be written or not

con_file: bool, optional, :

whether the contrast file should be written or not

res_file: bool, optional :

whether the residual variance file should be written or not

html_file: bool, optional, :

whether the html result page should be written or not

nipy.neurospin.glm_files_layout.glm_tools.glm_fit(fMRI_path, DesignMatrix, output_glm=None, glm_info=None, fit='Kalman_AR1', mask_url=None, data_scaling=True)

Call the GLM Fit function with apropriate arguments

Parameters :

fMRI_path: string or list of strings, :

path of the fMRI data file(s)

design_matrix: DesignMatrix instance, :

design matrix of the model

output_glm: string, optional :

path of the output glm .npz dump

glm_info: string,optional :

path of the output configobj that gives dome infor on the glm

fit: string, Optional, :

to be chosen among ‘Kalman_AR1’, ‘Ordinary Least Squares’, ‘Kalman’ that represents both the model and the fit method

mask_url: string, Optional, :

path of the mask file

if None, no mask is applied

data_scaling: bool, Optional :

scaling of the data to mean value

Returns :

glm, a nipy.neurospin.glm.glm instance representing the GLM :

nipy.neurospin.glm_files_layout.glm_tools.load_image(image_path, mask_path=None)

Return an array of image data masked by mask data

Parameters :

image_path string or list of strings :

that yields the data of interest

mask_path=None: string that yields the mask path :

Returns :

image_data a data array that can be 1, 2, 3 or 4D :

depending on chether mask==None or not and on the length of the times series

nipy.neurospin.glm_files_layout.glm_tools.save_all_images(contrast, dim, mask_url, kargs)
Parameters :

contrast a structure describing :

the values related to the computed contrast

ContrastId, string, the contrast identifier :

dim the dimension of the contrast :

mask_url path of the mask image related to the data :

kargs, might have ‘z_file’, ‘stat_file’, ‘con_file’, ‘res_file’, ‘html_file’ :

keys yielding paths to write corresponding outputs. optionally it can also have the keys ‘method’, ‘threshold’ and ‘cluster’ that are used to define the parameters for vizualization of the html page.

nipy.neurospin.glm_files_layout.glm_tools.save_volume(shape, path, affine, mask=None, data=None, descrip=None)

volume saving utility for masked volumes

Parameters :

shape, tupe of dimensions of the data :

path, string, output image path :

affine, transformation of the grid to a coordinate system :

mask=None, binary mask used to reduce the volume size :

data=None data to be put in the volume :

descrip=None, a string descibing what the image is :

nipy.neurospin.glm_files_layout.glm_tools.save_volume_from_mask_image(path, mask_image, data, descrip=None)

volume saving utility for masked volumes

Parameters :

path, string, output image path :

mask_image, string, :

path of ther reference mask image

data=None data to be put in the volume :

descrip=None, a string descibing what the image is :