mitfat 0.2.0

A Python-based Scikit-Learn-friendly fMRI Analysis Tool, Made in Tuebingen.

Introduction

MiTfAT is a scikit-learn-friendly Python library to analyse fMRI data.

Manual can be found in this pdf file.

There are a few software packages that are commonly used by researchers to pre-process the fMRI time-series and then analyse them. But the decision to develop a new library which eventually led to MiTfAT library is motivated by a few reasons. The main reason is that all the commonly used fMRI analysis packages come with so many belts and whistles that it usually takes the user a long time to find out which parts of each software package is what he/she need. Another reason was that none of the commonly used software packages I could find was written in Python, which is my programming language of choice. And lastly, the analysis methods I needed for the problems I had in mind were not available in any of those software packages.

Hence the MiTfAT was developed. It is designed to be used for general fMRI time-series analysis, but in particular, signals obtained from molecular fMRI studies, i.e. the cases in which we measure the changes in concentration of molecules which might have been directly injected into the brain (which happens when the molecule is too big to pass through blood-brain-barrier).

The basic principle behind MiTfAT is that it imports all the relevant data of an fMRI experiment into a class object. The fMRI time-series are a member of this class and are stores as NumPy arrays. There are various functionalities available to analyse the data in a number of ways. They include:

• Clustering the time-series using K-means clustering. Clustering can be done based on values in all time-steps, or the mean value of each time-series or slope of a linear-regression passing through the time-series. And it can be applied to raw data or the normalised data. MiTfAT uses scikit-learn for all machine learning functions. Hence, K-means can be easily changed with any other clustering algorithm implemented in scikit-learn.

• Hierarchical clustering; which applies clustering in two stages. In the first step, the algorithm removes the time-series corresponding to voxels in which signal to noise ratio is not high enough. And in the second step, the time-series corresponding to the remaining voxels are clustered.

• Detrending. We can remove the general trends in time-series to make the transient changes more visible. As an example, if we cannot wait long enough until the concentration of our agent reaches steady-state level then transient variations in the signal caused by changes in experimental conditions, which is what we are interested in, might be obscured by such trends in the signal. MiTfAT can detrend the time series and give us a signal which looks like the one we might expect in steady-state. And then, transient changes due to experimental design would be quantifiable.

• Interpolation of time-series under varying conditions. Let’s say we have an experiment in which the total recording time is divided into 3 segments. In the second segment, we record under a different condition compared to the first and last segment. This can be, as an example, the occlusion of an artery which changes calcium concertation in the brain when the agent we have injected into the brain binds with calcium. Obviously, we want to quantify how the signal has changed in the second segment. In order to do so, we should interpolate the time-series in segment 2 based on values of segments 1 and 3, and then compare it with the actual measurements. MiTfAT provides such a feature for us.

• Averaging over many trials. If we repeat an experiment many times, then it is usually of interest to average the measurements over all the trials. This can be useful if each measurement is noisy and we want to attenuate the effects of noise. MiTfAT allows us to do so.

Installation

It is better to install MiTfAT in a new virtual environment. If you are using Anaconda Python, you can do the following:

conda create -n env_mitfat
conda activate env_mitfat

Then in your command prompt or bash, simply type:

pip install mitfat

Or if you want to work with the latest beta-release, you can install directly from this repository.

Basics

The MiTfAT library incorporates all the relevant data and information about an experiment into a Python class of type fmri_dataset, and then the user can perform various analysis and visualisatin steps. In order to load the fMRI data, currently, the required information about data files and details of the experiment should be written down in a specified format in a config file, details of which will be discussed shortly. But if you want to get started with some sample data and know some of the features of the library, you can download two sample scripts and corresponding datasets from here . When up unzip the file, you can see a folder called tests in which you can see two python scrips. There are also two subfolder, each contains sample datasets that are used by each of the scripts. And you can also see three text files which are the config files used by scripts.

If you have installed MiTfAT, then you can run each of these scripts and the outputs they generate will be saved in new sub-folders inside the tests folder. Studying these two scripts can be quite informative and it is highly recommended for the users. If you want to use these samples scripts for your own data, you can simply edit the config files.

In the following chapters, main features of the code are explained. The figures you will see in the following chapter are generated using these two sample scripts.

Requirements

"pandas",
"numpy",
"scipy",
"matplotlib",
"nibabel",
"nilearn",
"pathlib",
"click",
"seaborn",
"openpyxl",

Compatibility

This code is tested under Python 3.7, and 3.8.

License

GNU General Public License (Version 3).

Citation

Please cite this code as follows:

Bokharaie VS (2019) “MiTfAT: A Python-based fMRI Analysis Tool”, Zenodo. https://doi.org/10.5281/zenodo.3372365.

Citation

Please use the CITATION.cff file.

This code was originally developed for a collaboration which led to the following publications:

Savić T. , Gambino G., Bokharaie V. S., Noori H. R., Logothetis N.K., Angelovski G., “Early detection and monitoring of cerebral ischemia using calcium-responsive MRI probes”, PNAS, 2019.

Author

MiTfAT is maintained by Vahid Samadi Bokharaie.