.. _second_level_model:

===================
Second level models
===================

.. topic:: **Page summary**

   Second level models in Nilearn are used to perform group-level analyses on :term:`fMRI` data. Once individual
   subjects have been processed in a common space (e.g. :term:`MNI`, Talairach, or subject average), the data can
   be grouped and statistical tests  performed to make broader inferences on :term:`fMRI` activity. Some common
   second level models are one-sample (unpaired or paired) and two-sample t-tests.


Fitting a second level model
============================

As with first level models, a design matrix needs to be defined before fitting a second level model.
Again, similar to first level models, Nilearn provides a function
:func:`nilearn.glm.second_level.make_second_level_design_matrix` for this purpose. Once
the design matrix has been setup, it can be visualized using the same function as before,
:func:`nilearn.plotting.plot_design_matrix`.

To fit the second level model, the tools to use are within the class
:class:`nilearn.glm.second_level.SecondLevelModel`. Specifically, the function that
fits the model is :func:`nilearn.glm.second_level.SecondLevelModel.fit`.

Some examples to get you going with second level models are provided below::
  * General design matrix setup: :ref:`sphx_glr_auto_examples_05_glm_second_level_plot_second_level_design_matrix.py`
  * One-sample testing, with non-parametric multiple comparisons correction:
    :ref:`sphx_glr_auto_examples_05_glm_second_level_plot_second_level_one_sample_test.py`
  * Two-sample testing, unpaired and paired: :ref:`sphx_glr_auto_examples_05_glm_second_level_plot_second_level_two_sample_test.py`
  * Complex contrast: :ref:`sphx_glr_auto_examples_05_glm_second_level_plot_second_level_association_test.py`


Thresholding statistical maps
=============================

Nilearn's statistical plotting functions provide simple thresholding functionality. For instance, functions
like :func:`nilearn.plotting.plot_stat_map` or :func:`nilearn.plotting.plot_glass_brain` have an argument
called ``threshold`` that, when set, will only show voxels with a value that is over the threshold provided.

Thresholding examples are available here: :ref:`sphx_glr_auto_examples_05_glm_second_level_plot_second_level_one_sample_test.py`
and :ref:`sphx_glr_auto_examples_05_glm_second_level_plot_thresholding.py`.


Multiple comparisons correction
===============================

As discussed in the :ref:`Multiple comparisons` section of the introduction, the issue of multiple comparisons is
important to address with statistical analysis of :term:`fMRI` data. Nilearn provides parametric and non-parametric tools
to address this issue.

Refer to the example :ref:`sphx_glr_auto_examples_05_glm_second_level_plot_thresholding.py` for a guide
to applying :term:`FPR<FPR correction>`, :term:`FDR<FDR correction>`, and :term:`FWER<FWER correction>` corrections.
These corrections are applied using the :func:`nilearn.glm.threshold_stats_img` function.

You can additionally employ a non-parametric correction procedure using either
:func:`nilearn.glm.second_level.non_parametric_inference` or :func:`nilearn.mass_univariate.permuted_ols`.
Refer to the example :ref:`sphx_glr_auto_examples_05_glm_second_level_plot_second_level_one_sample_test.py`
for a practical use of this function.

Within an activated cluster, not all voxels represent true activation. To estimate true positives within a cluster,
Nilearn provides the :func:`nilearn.glm.cluster_level_inference` function. An example with usage information is available
here: :ref:`sphx_glr_auto_examples_05_glm_second_level_plot_proportion_activated_voxels.py`.


Voxel based morphometry
=======================

The :class:`nilearn.glm.second_level.SecondLevelModel` and its associated functions can also be used
to perform voxel based morphometry. An example using the `OASIS <https://www.oasis-brains.org/>`_ dataset to
identify the relationship between aging, sex and gray matter density is available here
:ref:`sphx_glr_auto_examples_05_glm_second_level_plot_oasis.py`.