.. only:: html

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

        Click :ref:`here <sphx_glr_download_auto_examples_07_advanced_plot_bids_analysis.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_07_advanced_plot_bids_analysis.py:


BIDS dataset first and second level analysis
============================================


Full step-by-step example of fitting a :term:`GLM` to perform a first and second level
analysis in a :term:`BIDS` dataset and visualizing the results.
Details about the :term:`BIDS` standard can be consulted at
`http://bids.neuroimaging.io/ <http://bids.neuroimaging.io/>`_.

More specifically:

1. Download an :term:`fMRI` :term:`BIDS` dataset with two language conditions to contrast.
2. Extract first level model objects automatically from the :term:`BIDS` dataset.
3. Fit a second level model on the fitted first level models. Notice that
   in this case the preprocessed :term:`bold<BOLD>` images were already normalized to the
   same :term:`MNI` space.

To run this example, you must launch IPython via ``ipython
--matplotlib`` in a terminal, or use the Jupyter notebook.

.. contents:: **Contents**
    :local:
    :depth: 1

Fetch example BIDS dataset
--------------------------
We download a simplified :term:`BIDS` dataset made available for illustrative
purposes. It contains only the necessary
information to run a statistical analysis using Nilearn. The raw data
subject folders only contain bold.json and events.tsv files, while the
derivatives folder includes the preprocessed files preproc.nii and the
confounds.tsv files.


.. code-block:: default

    from nilearn.datasets import fetch_language_localizer_demo_dataset
    data_dir, _ = fetch_language_localizer_demo_dataset()








Here is the location of the dataset on disk.


.. code-block:: default

    print(data_dir)





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

 Out:

 .. code-block:: none

    /home/nicolas/nilearn_data/fMRI-language-localizer-demo-dataset




Obtain automatically FirstLevelModel objects and fit arguments
--------------------------------------------------------------
From the dataset directory we automatically obtain the FirstLevelModel objects
with their subject_id filled from the :term:`BIDS` dataset. Moreover, we obtain
for each model a dictionary with run_imgs, events and confounder regressors
since in this case a confounds.tsv file is available in the :term:`BIDS` dataset.
To get the first level models we only have to specify the dataset directory
and the task_label as specified in the file names.


.. code-block:: default

    from nilearn.glm.first_level import first_level_from_bids
    task_label = 'languagelocalizer'
    models, models_run_imgs, models_events, models_confounds = \
        first_level_from_bids(
            data_dir, task_label,
            img_filters=[('desc', 'preproc')])





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

 Out:

 .. code-block:: none

    /home/nicolas/GitRepos/nilearn-fork/nilearn/glm/first_level/first_level.py:945: UserWarning: SliceTimingRef not found in file /home/nicolas/nilearn_data/fMRI-language-localizer-demo-dataset/derivatives/sub-01/func/sub-01_task-languagelocalizer_desc-preproc_bold.json. It will be assumed that the slice timing reference is 0.0 percent of the repetition time. If it is not the case it will need to be set manually in the generated list of models
      warn('SliceTimingRef not found in file %s. It will be assumed'




Quick sanity check on fit arguments
-----------------------------------
Additional checks or information extraction from pre-processed data can
be made here.

We just expect one run_img per subject.


.. code-block:: default

    import os
    print([os.path.basename(run) for run in models_run_imgs[0]])





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

 Out:

 .. code-block:: none

    ['sub-01_task-languagelocalizer_desc-preproc_bold.nii.gz']




The only confounds stored are regressors obtained from motion correction. As
we can verify from the column headers of the confounds table corresponding
to the only run_img present.


.. code-block:: default

    print(models_confounds[0][0].columns)





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

 Out:

 .. code-block:: none

    Index(['RotX', 'RotY', 'RotZ', 'X', 'Y', 'Z'], dtype='object')




During this acquisition the subject read blocks of sentences and
consonant strings. So these are our only two conditions in events.
We verify there are 12 blocks for each condition.


.. code-block:: default

    print(models_events[0][0]['trial_type'].value_counts())





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

 Out:

 .. code-block:: none

    string      12
    language    12
    Name: trial_type, dtype: int64




First level model estimation
----------------------------
Now we simply fit each first level model and plot for each subject the
:term:`contrast` that reveals the language network (language - string).
Notice that we can define a contrast using the names of the conditions
specified in the events dataframe.
Sum, subtraction and scalar multiplication are allowed.

Set the threshold as the z-variate with an uncorrected p-value of 0.001.


.. code-block:: default

    from scipy.stats import norm
    p001_unc = norm.isf(0.001)








Prepare figure for concurrent plot of individual maps.


.. code-block:: default

    from nilearn import plotting
    import matplotlib.pyplot as plt

    fig, axes = plt.subplots(nrows=2, ncols=5, figsize=(8, 4.5))
    model_and_args = zip(models, models_run_imgs, models_events, models_confounds)
    for midx, (model, imgs, events, confounds) in enumerate(model_and_args):
        # fit the GLM
        model.fit(imgs, events, confounds)
        # compute the contrast of interest
        zmap = model.compute_contrast('language-string')
        plotting.plot_glass_brain(zmap, colorbar=False, threshold=p001_unc,
                                  title=('sub-' + model.subject_label),
                                  axes=axes[int(midx / 5), int(midx % 5)],
                                  plot_abs=False, display_mode='x')
    fig.suptitle('subjects z_map language network (unc p<0.001)')
    plotting.show()




.. image:: /auto_examples/07_advanced/images/sphx_glr_plot_bids_analysis_001.png
    :alt: subjects z_map language network (unc p<0.001)
    :class: sphx-glr-single-img





Second level model estimation
-----------------------------
We just have to provide the list of fitted FirstLevelModel objects
to the SecondLevelModel object for estimation. We can do this because
all subjects share a similar design matrix (same variables reflected in
column names).


.. code-block:: default

    from nilearn.glm.second_level import SecondLevelModel
    second_level_input = models








Note that we apply a smoothing of 8mm.


.. code-block:: default

    second_level_model = SecondLevelModel(smoothing_fwhm=8.0)
    second_level_model = second_level_model.fit(second_level_input)








Computing contrasts at the second level is as simple as at the first level.
Since we are not providing confounders we are performing a one-sample test
at the second level with the images determined by the specified first level
contrast.


.. code-block:: default

    zmap = second_level_model.compute_contrast(
        first_level_contrast='language-string')








The group level contrast reveals a left lateralized fronto-temporal
language network.


.. code-block:: default

    plotting.plot_glass_brain(zmap, colorbar=True, threshold=p001_unc,
                              title='Group language network (unc p<0.001)',
                              plot_abs=False, display_mode='x')
    plotting.show()



.. image:: /auto_examples/07_advanced/images/sphx_glr_plot_bids_analysis_002.png
    :alt: plot bids analysis
    :class: sphx-glr-single-img






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

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


.. _sphx_glr_download_auto_examples_07_advanced_plot_bids_analysis.py:


.. only :: html

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


  .. container:: binder-badge

    .. image:: images/binder_badge_logo.svg
      :target: https://mybinder.org/v2/gh/nilearn/nilearn.github.io/main?filepath=examples/auto_examples/07_advanced/plot_bids_analysis.ipynb
      :alt: Launch binder
      :width: 150 px


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

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



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

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


.. only:: html

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

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