Metadata-Version: 2.1
Name: mitfat
Version: 0.2.0
Summary: A Python-based Scikit-Learn-friendly fMRI Analysis Tool, Made in Tuebingen.
Home-page: https://github.com/vahid-sb/MiTfAT
Author: Vahid Samadi Bokharaie
Author-email: vahid.bokharaie@protonmail.com
License: GNU Version 3
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Requires-Dist: pandas
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: matplotlib
Requires-Dist: nibabel
Requires-Dist: nilearn
Requires-Dist: pathlib
Requires-Dist: seaborn
Requires-Dist: openpyxl

MiTfAT
======

.. image:: https://img.shields.io/pypi/v/MiTfAT.svg
    :target: https://pypi.python.org/pypi/MiTfAT
    :alt: Latest PyPI version
.. image:: https://zenodo.org/badge/290846934.svg
   :target: https://zenodo.org/badge/latestdoi/290846934
.. image:: https://img.shields.io/badge/License-GPLv3-blue.svg
   :target: https://www.gnu.org/licenses/gpl-3.0


Introduction
------------

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

Manual can be found `in this pdf file <https://github.com/vahid-sb/MiTfAT/blob/master/docs/mitfat.pdf>`_.

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:

.. code-block:: bash

   conda create -n env_mitfat
   conda activate env_mitfat


Then in your command prompt or bash, simply type:

.. code-block:: bash

   pip install mitfat


Or if you want to work with the latest beta-release, you can install directly from `this repository <https://github.com/vahid-sb/MiTfAT>`_.

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 <https://github.com/vahid-sb/MiTfAT/blob/master/tests.zip>`_ . 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
^^^^^^^^^^^^

 .. code-block:: bash

	"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 <vahid.bokharaie@protonmail.com>`_.


