.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "auto_examples/05_glm_second_level/plot_second_level_design_matrix.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

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

        :ref:`Go to the end <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.

.. GENERATED FROM PYTHON SOURCE LINES 15-22

.. code-block:: Python


    from nilearn._utils.helpers import check_matplotlib

    check_matplotlib()

    import matplotlib.pyplot as plt








.. GENERATED FROM PYTHON SOURCE LINES 23-26

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

.. GENERATED FROM PYTHON SOURCE LINES 26-29

.. code-block:: Python

    n_subjects = 20
    subjects_label = [f"sub-{int(i):02}" for i in range(1, n_subjects + 1)]








.. GENERATED FROM PYTHON SOURCE LINES 30-32

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

.. GENERATED FROM PYTHON SOURCE LINES 32-42

.. code-block:: Python

    import pandas as pd

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








.. GENERATED FROM PYTHON SOURCE LINES 43-46

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

.. GENERATED FROM PYTHON SOURCE LINES 46-52

.. code-block:: Python

    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

 .. code-block:: none

    /home/runner/work/nilearn/nilearn/examples/05_glm_second_level/plot_second_level_design_matrix.py:48: UserWarning: Attention: Design matrix is singular. Aberrant estimates are expected.
      design_matrix = make_second_level_design_matrix(




.. GENERATED FROM PYTHON SOURCE LINES 53-54

Let's plot it.

.. GENERATED FROM PYTHON SOURCE LINES 54-62

.. code-block:: Python

    from nilearn.plotting import plot_design_matrix

    fig, ax1 = plt.subplots(1, 1, figsize=(3, 4), constrained_layout=True)

    ax = plot_design_matrix(design_matrix, axes=ax1)
    ax.set_ylabel("maps")
    ax.set_title("Second level design matrix", fontsize=12)
    plt.show()



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






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

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

**Estimated memory usage:**  108 MB


.. _sphx_glr_download_auto_examples_05_glm_second_level_plot_second_level_design_matrix.py:

.. only:: html

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

    .. container:: binder-badge

      .. image:: images/binder_badge_logo.svg
        :target: https://mybinder.org/v2/gh/nilearn/nilearn/0.12.0?urlpath=lab/tree/notebooks/auto_examples/05_glm_second_level/plot_second_level_design_matrix.ipynb
        :alt: Launch binder
        :width: 150 px

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

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

    .. 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-zip

      :download:`Download zipped: plot_second_level_design_matrix.zip <plot_second_level_design_matrix.zip>`


.. only:: html

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

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