Modelling the data and not the images in FMRI
=============================================

.. important::

   Check out :ref:`new`!

What is it?
...........

This is the first statistical software tool which implements the `model
based`_ (MB) estimator for functional magnetic resonance imaging (FMRI)
data models. It is a new and original method for the statistical
analysis of FMRI of brain scans. MB estimation combines all
preprocessing steps of standard approaches into one modelling step.
Without altering the original 4D-image, the method results in smooth
fits of the underlying parameter fields. More importantly, the method
yields a trustworthy estimate of the uncertainty in BOLD effect
estimation.

Why should I care?
..................

Current approaches to the analysis of FMRI data apply various
preprocessing steps to the original FMRI. These preprocessings lead to a
general underestimation of residual variance in the downstream analysis.
This negatively impacts the type I error of statistical tests and
increases the risk for reporting false positive results.

In contrast to standard approaches, MB estimation yields sound
statistical estimates for the uncertainty in BOLD effect estimation. The
availability of these uncertainty fields allows to model FMRI studies by
random effects meta regression models, acknowledging that individual
subjects are random entities, and that the certainty at which the
individual BOLD effect can be estimated from an FMRI varies across the
brain and between subjects.

.. note::

    Please note that this is not the MATLAB program fmristat_ nor is it
    a reimplementation of the software. fmristat_ (now also part of
    niak_) remains the reference implementation of Keith Worsley's
    methods_. Instead, this software contains an implementation of
    Möbius' `MB estimator`_.

.. _fmristat: http://www.math.mcgill.ca/keith/fmristat/

.. _niak: https://github.com/SIMEXP/niak

.. _methods: https://www.sciencedirect.com/science/article/pii/S1053811901909334

MB estimation also encourages to process and report BOLD effects in ATI
units. In particular multicentre studies gain power by its use. For more
details, have a look at the chapter :ref:`population_ati`.

How to cite estimator and software
----------------------------------

`Reference publication`_ for the MB estimator is:

..

    Thomas W. D. Möbius (2018) `Modelling the data and not the images in
    FMRI`_, ArXiv e-prints, arXiv:1809.07232

    Thomas W. D. Möbius (2018) fmristats: Modelling the data and not the
    images in FMRI (0.1.0) [Computer program]. Available at
    http://fmristats.github.io/

.. _`Modelling the data and not the images in FMRI`: https://arxiv.org/abs/1809.07232v1

.. _`model based`: https://arxiv.org/abs/1809.07232v1

.. _`MB estimator`: https://arxiv.org/abs/1809.07232v1

.. _`Reference publication`: https://arxiv.org/pdf/1809.07232v1.pdf

Thank you for using and citing this software (BibTeX:
:download:`references.bib`).

Installation
------------

An easy way to install fmristats is to first install Anaconda3_ and then
to use pip_ to install fmristats itself. Anaconda3_ is a cross platform
distribution for data analysis and scientific computing. pip_ is the
"PyPA recommended tool for installing Python packages".

After installation of Anaconda3_ run:

.. code:: shell

    conda install pip numba numpy scipy matplotlib \
        scikit-learn scikit-image \
        pandas statsmodels seaborn

    pip install fmristats

That's it. You should be good to go.

If you are planing to use the fmristats wrappers to FSL_ and ANTS_,
please make sure that the respective command line tools are within your
PATH.

.. _Anaconda3: https://docs.anaconda.com/anaconda/install/

.. _pip: https://pypi.python.org/pypi/pip/

.. _FSL: https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/

.. _ANTS: http://stnava.github.io/ANTs/

Tutorials
---------

Tutorials discussing various parts of fmristats; expect this list to
grow.

.. toctree::
   :maxdepth: 2

   tutorials/getting-started
   tutorials/study-interface
   tutorials/subject-remove-non-brain-areas
   tutorials/subject-inference-at-one-point
   tutorials/population-inference-preliminaries
   tutorials/population-inference-confirmative
   tutorials/population-inference-explorative
   tutorials/population-inference-covariates
   tutorials/thresholding
   tutorials/run-on-server
   tutorials/notes

Python interface
----------------

.. toctree::
   :maxdepth: 2

   modules

Change log
----------

.. toctree::
   :maxdepth: 2

   new

Indices and tables
------------------

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`