.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        Click :ref:`here <sphx_glr_download_auto_examples_05_glm_second_level_plot_second_level_design_matrix.py>`     to download the full example code or to run this example in your browser via Binder
    .. rst-class:: sphx-glr-example-title

    .. _sphx_glr_auto_examples_05_glm_second_level_plot_second_level_design_matrix.py:

Example of second level design matrix
=====================================

This example shows how a second-level design matrix is specified: assuming that
the data refer to a group of individuals, with one image per subject, the
design matrix typically holds the characteristics of each individual.

This is used in a second-level analysis to assess the impact of these
characteristics on brain signals.

This example requires matplotlib.


.. code-block:: default


    try:
        import matplotlib.pyplot as plt
    except ImportError:
        raise RuntimeError("This script needs the matplotlib library")








Create a simple experimental paradigm
--------------------------------------
We want to get the group result of a contrast for 20 subjects.


.. code-block:: default

    n_subjects = 20
    subjects_label = ['sub-%02d' % i for i in range(1, n_subjects + 1)]








Next, we specify extra information about the subjects to create confounders.
Without confounders the design matrix would correspond to a one sample test.


.. code-block:: default

    import pandas as pd
    extra_info_subjects = pd.DataFrame({'subject_label': subjects_label,
                                        'age': range(15, 15 + n_subjects),
                                        'sex': [0, 1] * int(n_subjects / 2)})








Create a second level design matrix
-----------------------------------
With that information we can create the second level design matrix.


.. code-block:: default

    from nilearn.glm.second_level import make_second_level_design_matrix
    design_matrix = make_second_level_design_matrix(subjects_label,
                                                    extra_info_subjects)





.. rst-class:: sphx-glr-script-out

 Out:

 .. code-block:: none

    /home/varoquau/dev/nilearn/nilearn/glm/first_level/design_matrix.py:462: UserWarning: Attention: Design matrix is singular. Aberrant estimates are expected.
      warn('Attention: Design matrix is singular. Aberrant estimates '




Let's plot it.


.. code-block:: default

    from nilearn.plotting import plot_design_matrix
    ax = plot_design_matrix(design_matrix)
    ax.set_title('Second level design matrix', fontsize=12)
    ax.set_ylabel('maps')
    plt.tight_layout()
    plt.show()



.. image:: /auto_examples/05_glm_second_level/images/sphx_glr_plot_second_level_design_matrix_001.png
    :alt: Second level design matrix
    :class: sphx-glr-single-img


.. rst-class:: sphx-glr-script-out

 Out:

 .. code-block:: none

    /home/varoquau/dev/nilearn/examples/05_glm_second_level/plot_second_level_design_matrix.py:49: UserWarning: Tight layout not applied. The left and right margins cannot be made large enough to accommodate all axes decorations. 
      plt.tight_layout()
    /home/varoquau/dev/nilearn/examples/05_glm_second_level/plot_second_level_design_matrix.py:50: UserWarning: Matplotlib is currently using agg, which is a non-GUI backend, so cannot show the figure.
      plt.show()





.. rst-class:: sphx-glr-timing

   **Total running time of the script:** ( 0 minutes  0.243 seconds)


.. _sphx_glr_download_auto_examples_05_glm_second_level_plot_second_level_design_matrix.py:


.. only :: html

 .. container:: sphx-glr-footer
    :class: sphx-glr-footer-example


  .. container:: binder-badge

    .. image:: https://mybinder.org/badge_logo.svg
      :target: https://mybinder.org/v2/gh/nilearn/nilearn.github.io/master?filepath=examples/auto_examples/05_glm_second_level/plot_second_level_design_matrix.ipynb
      :width: 150 px


  .. container:: sphx-glr-download sphx-glr-download-python

     :download:`Download Python source code: plot_second_level_design_matrix.py <plot_second_level_design_matrix.py>`



  .. container:: sphx-glr-download sphx-glr-download-jupyter

     :download:`Download Jupyter notebook: plot_second_level_design_matrix.ipynb <plot_second_level_design_matrix.ipynb>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_