PyHRF documentation

Overview | (Page Top) |

The current package contains PyHRF 1.0 and all its dependencies. A python module that implements a joint detection-estimation approach of brain activity from fMRI datasets described in:

VINCENT, Thomas (CEA), CIUCIU, Philippe (CEA), IDIER, Jérôme (CNRS)
Application and Validation of Spatial Mixture Modelling for the Joint Detection-Estimation of Brain Activity in Fmri
29th IEEE EMBS Annual International Conference, August 23-26, 2007, Cité Internationale, Lyon, France
VINCENT, Thomas (CEA), CIUCIU, Philippe (CEA), IDIER, Jérôme (CNRS)
Spatial mixture modelling for the joint detection-estimation of brain activity in fMRI
International Conference on Acoustics, Speech, and Signal Procession, April 15-20, 2007, Hawai'i Convention Center - Honolulu, Hawaii, USA.
This methods relies on several ingredients/inputs, the most important being a parcellation of the brain into functionally homogeneous regions-of-interests (ROIs) in which a specific Hemodynamic response Function will be estimated. Within each ROI, brain activity elicited by experimental conditions will also be detected and localized using spatial mixture models in the Bayesian framework. In this sense, the proposed approach extends the seminal contribution of [Makni et al., 2008]:
MAKNI, Salima (CEA), IDIER, Jérôme (CNRS), VINCENT, Thomas (CEA), THIRION, Bertrand (INRIA), DEHAENE-LAMBERTZ, Ghislaine (CNRS) and CIUCIU, Philippe (CEA),
A fully Bayesian approach to the parcel-based detection-estimation of brain activity in fMRI
NeuroImage, published on line:doi:10.1016/j.neuroimage.2008.02.017

Here is an example of what kind of results our algorithm is able to provide:

A region-based HRF estimate for each primary auditory cortex, as well as estimated effect and variance maps for any contrast of interest.

This software is delivered is on pre-release version and is not intended to be distributed.
It is mainly written in Python with some extension in C. The installation is semi-automatic and relies on setuptools which is an enhancement of setuptools.

Pyhrf requires 2 main dependencies to be installed by the user:

If you wish to use image viewer (pyhrf_view), you would have to install: If an internet connection is available, the following dependencies should be automatically taken care of by the pyrhf installation:

Installation | (Page Top) |

The following softwares are required prior to the installation:

Other recommanded software: kxmleditor, to edit configuration files. It is commonly available through the standard repository of your linux distribution.

Installation of nifticlib and pynifti

This set of libraries is used to read/write neuroimaging data in nifti format. See http://nifti.nimh.nih.gov/ for more details. Installation has two steps: first the compilation/installation of a low-level C library and second the building of a more high level python package which binds to the C-library.
Sources are available at the sourceforge project page (Recommanded versions: nifticlib-1.0.0 and pynifti_0.20070930.1). Please refer to their documentation for instructions of installation.
You may run
$ python -c "import nifti"
to test nifti installation.

Installation of fff/gsl

The package fff (Fast FMRI Functions) requires GSL v1.9 to be installed.
Here is the ftp repository for the GSL. You may test the GSL installation with:
gsl-config --version
A suitable version of the fff package is provided: nipy-fff.tar.gz (along with pyhrf-1.0.tar.gz).
Uncompress it, go to ./trunk/ and run
python setup.py install
Please refer to README.txt for details on installation (especially local installation).

Installation of pyhrf

In the directory where pyhrf-1.0.tar.gz is uncompressed, simply run
$ python setup.py install
Running "python setup.py install" will result in an attempt to write in the Python site-packages directory and will fail if you don't have the appropriate permissions. In this case, consider a local installation.

Local installation

You may install pyhrf in an alternative directory, using:
$ python setup.py install --prefix=/my/directory
This will install pyhrf library under /my/directory/lib/python2.5/site-packages/. Make sure that the later path actually exists and is in the PYTHONPATH environment variable. Pyhrf executables will be installed in /my/directory/bin/ so that the latter should be in the PATH environment variable.

Execution | (Page Top) |

The utilisation of pyhrf is composed of 4 steps :

  1. Build a parcellation from SPM analyses
  2. Configure a pyhrf treatment
  3. Launch the pyhrf detection-estimation procedure
  4. View output results

Parcellation

A mask defining the regions of interest can be computed from statistics produced by SPM (betas, constrasts, ...). To build a configuration template file (clustering.xml):
$ pyhrf_clus_builcfg
Edit this XML file and fill the functional field with pathes to 3D statistical map files (SPM betas or contrasts).
To actually run the parcellation process:
$ pyhrf_clus_run

Pyhrf configuration

Information needed by a Pyhrf treatment for one session are: the BOLD 4D data, a 3D volume of labels defining the ROIs, a set of stimuli with their time arrivals. Configuration of pyhrf is made through the edition of a xml file. At first, generate a template of this file by issuing:

$ pyhrf_jde_buildcfg
A file detectestim.xml is then created. By default, it contains the definition of a treatment over data included in the Pyhrf distribution (i.e. localizer experiment). This serves as example to build a customized treatment.
This file is organised as follows:

The SessionsParams section describes all fMRI sessions. Each child tag stands for each session name, here only one session named session0. Down one level, the definition of one session is made of: After the definition of data inputs in SessionsParams, one can define the minimal number of voxels in a ROI. ROIs which do not verify this condition are discarded.
The last part analyser groups all parameters for the actual analysis. See contextual comments within the xml for more information.

Run the joint detection-estimation process

To run the pyhrf treatment defined in detectestim.xml:

> pyhrf_jde_estim -v1

Here -v1 stands for the level of verbosity (from 0: quiet, to 6: everything - debug only purpose)

Output results

Outputs (in nifti format)