.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "auto_examples/mass-univariate-statistics/volume-source-space.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_mass-univariate-statistics_volume-source-space.py>`
        to download the full example code.

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_auto_examples_mass-univariate-statistics_volume-source-space.py:


.. _exa-vol:

Volume source space
===================

.. currentmodule:: eelbrain

Basic analysis of volume source space vector data.

.. contents:: Contents
   :local:

Dataset
^^^^^^^
Load the :mod:`mne` sample data with responses to tones.
Data contains multiple trials for a single subject, with
tones presented to the left or right ear:

.. GENERATED FROM PYTHON SOURCE LINES 20-33

.. code-block:: Python

    # sphinx_gallery_thumbnail_number = 2
    # dataset: mne_sample

    from pathlib import Path

    from eelbrain import *
    import mne


    # Load the dataset
    data = datasets.get_mne_sample(src='vol', ori='vector')
    data.head()






.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    <figure><table border="1" frame="hsides" rules="none" cellpadding="2"><tr>
    <td style="text-align:left">#</td>
    <td style="text-align:left">i_start</td>
    <td style="text-align:left">trigger</td>
    <td style="text-align:left">index</td>
    <td style="text-align:left">condition</td>
    <td style="text-align:left">side</td>
    <td style="text-align:left">modality</td>
    </tr>
    <tr>
    <td style="text-align:left">0</td>
    <td style="text-align:left">6994</td>
    <td style="text-align:left">2</td>
    <td style="text-align:left">0</td>
    <td style="text-align:left">RA</td>
    <td style="text-align:left">R</td>
    <td style="text-align:left">A</td>
    </tr>
    <tr>
    <td style="text-align:left">1</td>
    <td style="text-align:left">7192</td>
    <td style="text-align:left">1</td>
    <td style="text-align:left">2</td>
    <td style="text-align:left">LA</td>
    <td style="text-align:left">L</td>
    <td style="text-align:left">A</td>
    </tr>
    <tr>
    <td style="text-align:left">2</td>
    <td style="text-align:left">7413</td>
    <td style="text-align:left">2</td>
    <td style="text-align:left">4</td>
    <td style="text-align:left">RA</td>
    <td style="text-align:left">R</td>
    <td style="text-align:left">A</td>
    </tr>
    <tr>
    <td style="text-align:left">3</td>
    <td style="text-align:left">7612</td>
    <td style="text-align:left">1</td>
    <td style="text-align:left">6</td>
    <td style="text-align:left">LA</td>
    <td style="text-align:left">L</td>
    <td style="text-align:left">A</td>
    </tr>
    <tr>
    <td style="text-align:left">4</td>
    <td style="text-align:left">7810</td>
    <td style="text-align:left">2</td>
    <td style="text-align:left">8</td>
    <td style="text-align:left">RA</td>
    <td style="text-align:left">R</td>
    <td style="text-align:left">A</td>
    </tr>
    <tr>
    <td style="text-align:left">5</td>
    <td style="text-align:left">8025</td>
    <td style="text-align:left">1</td>
    <td style="text-align:left">10</td>
    <td style="text-align:left">LA</td>
    <td style="text-align:left">L</td>
    <td style="text-align:left">A</td>
    </tr>
    <tr>
    <td style="text-align:left">6</td>
    <td style="text-align:left">8233</td>
    <td style="text-align:left">2</td>
    <td style="text-align:left">12</td>
    <td style="text-align:left">RA</td>
    <td style="text-align:left">R</td>
    <td style="text-align:left">A</td>
    </tr>
    <tr>
    <td style="text-align:left">7</td>
    <td style="text-align:left">8428</td>
    <td style="text-align:left">1</td>
    <td style="text-align:left">14</td>
    <td style="text-align:left">LA</td>
    <td style="text-align:left">L</td>
    <td style="text-align:left">A</td>
    </tr>
    <tr>
    <td style="text-align:left">8</td>
    <td style="text-align:left">8633</td>
    <td style="text-align:left">2</td>
    <td style="text-align:left">16</td>
    <td style="text-align:left">RA</td>
    <td style="text-align:left">R</td>
    <td style="text-align:left">A</td>
    </tr>
    <tr>
    <td style="text-align:left">9</td>
    <td style="text-align:left">8857</td>
    <td style="text-align:left">1</td>
    <td style="text-align:left">19</td>
    <td style="text-align:left">LA</td>
    <td style="text-align:left">L</td>
    <td style="text-align:left">A</td>
    </tr></table>
    <figcaption>NDVars: src</figcaption></figure>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 34-38

One-sample test
^^^^^^^^^^^^^^^
A one-sample test can be used to detect significant activations.
Perform a one-sample test on the right-ear trials only:

.. GENERATED FROM PYTHON SOURCE LINES 38-41

.. code-block:: Python


    result = testnd.Vector('src', sub="side == 'R'", data=data, samples=250, tfce=True, tstart=0.05, tstop=0.200)








.. GENERATED FROM PYTHON SOURCE LINES 42-43

Morph the data to the template brain for anatomical visualization.

.. GENERATED FROM PYTHON SOURCE LINES 43-68

.. code-block:: Python


    # Store the test result as NDVar
    y = result.masked_difference()

    # Make sure the source space for fsaverage exists
    fname_src_fsaverage = Path(y.source.subjects_dir) / "fsaverage" / "bem" / "fsaverage-vol-7-src.fif"
    if fname_src_fsaverage.exists():
        src_fs = mne.read_source_spaces(fname_src_fsaverage)
    else:
        src_fs = mne.setup_volume_source_space('fsaverage', 7, subjects_dir=y.source.subjects_dir)
        src_fs.save(Path(y.source.subjects_dir) / "fsaverage" / "bem" / "fsaverage-vol-7-src.fif")

    # Compute the transformation from the sample subject to fsaverage
    morph = mne.compute_source_morph(
        y.source.get_source_space(),
        subject_from=y.source.subject,
        subjects_dir=y.source.subjects_dir,
        niter_affine=[10, 10, 5],
        niter_sdr=[10, 10, 5],  # just for speed
        src_to=src_fs,
    )

    # Morph the test result
    y = morph_source_space(y, 'fsaverage', morph=morph)





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

 .. code-block:: none

    [2026-05-19 11:06:53][dipy] INFO: ➞ Running center_of_mass step from affine registration...
    [2026-05-19 11:06:53][dipy] INFO: ➞ Running translation step from affine registration...
    [2026-05-19 11:06:54][dipy] INFO: ➞ Running rigid step from affine registration...
    [2026-05-19 11:06:54][dipy] INFO: ➞ Running affine step from affine registration...
    [2026-05-19 11:06:54][dipy] INFO: Creating scale space from the moving image. Levels: 3. Sigma factor: 0.200000.
    [2026-05-19 11:06:54][dipy] INFO: Creating scale space from the static image. Levels: 3. Sigma factor: 0.200000.
    [2026-05-19 11:06:54][dipy] INFO: Optimizing level 2
    [2026-05-19 11:06:54][dipy] INFO: Optimizing level 1
    [2026-05-19 11:06:54][dipy] INFO: Optimizing level 0




.. GENERATED FROM PYTHON SOURCE LINES 69-73

For static visualization, we can use a combination of :class:`plot.Butterfly`
and :class:`plot.GlassBrain` plots.
A :class:`plot.Butterfly` plot can give a quick overview of amplitudes over
time:

.. GENERATED FROM PYTHON SOURCE LINES 73-85

.. code-block:: Python


    # Extract vector norm (amplitude)
    y_norm = y.norm('space')
    # Split data by hemisphere
    butterfly_data = [y_norm.sub(source=hemi, name=hemi.capitalize()) for hemi in ['lh', 'rh']]
    # Buterfly plot
    p = plot.Butterfly(butterfly_data, axh=2, axw=3)
    # Mark time points for anatomical visualization
    times = [0.090, 0.160]
    for t in times:
        p.add_vline(t)




.. image-sg:: /auto_examples/mass-univariate-statistics/images/sphx_glr_volume-source-space_001.png
   :alt: Lh, Rh
   :srcset: /auto_examples/mass-univariate-statistics/images/sphx_glr_volume-source-space_001.png
   :class: sphx-glr-single-img





.. GENERATED FROM PYTHON SOURCE LINES 86-93

:class:`plot.GlassBrain` plots show anatomical distribution of activity at
relevant time points. Glassbrains project activity through the head, i.e.,
each voxel in a projection shows the largest value along the line of sight.
By comparing different projections, the 3D distribution of activity can be
inferred. Here, the lateral view shows activity in temporal regions over
auditory cortex, while the coronal view shows how lateral/medial the peaks
are:

.. GENERATED FROM PYTHON SOURCE LINES 93-97

.. code-block:: Python


    for t in times:
        p = plot.GlassBrain(y.sub(time=t), title=f"{t * 1000:.0f} ms", vmax=4)




.. rst-class:: sphx-glr-horizontal


    *

      .. image-sg:: /auto_examples/mass-univariate-statistics/images/sphx_glr_volume-source-space_002.png
         :alt: 90 ms
         :srcset: /auto_examples/mass-univariate-statistics/images/sphx_glr_volume-source-space_002.png
         :class: sphx-glr-multi-img

    *

      .. image-sg:: /auto_examples/mass-univariate-statistics/images/sphx_glr_volume-source-space_003.png
         :alt: 160 ms
         :srcset: /auto_examples/mass-univariate-statistics/images/sphx_glr_volume-source-space_003.png
         :class: sphx-glr-multi-img





.. GENERATED FROM PYTHON SOURCE LINES 98-101

In a notebook, `LiveNeuron <https://github.com/liang-bo96/LiveNeuron>`_
can provide interactive visualization. Start the visualization with
the code below (after uncommenting):

.. GENERATED FROM PYTHON SOURCE LINES 101-107

.. code-block:: Python


    # from eelbrain_plotly_viz import EelbrainPlotly2DViz

    # viz = EelbrainPlotly2DViz(result.difference, layout_mode='horizontal', realtime=True, arrow_scale=0.2)
    # viz.show_in_jupyter()








.. GENERATED FROM PYTHON SOURCE LINES 108-110

In an interactive iPython session, butterfly and glassbrain plots can be
linked for interactive visualization using:

.. GENERATED FROM PYTHON SOURCE LINES 110-112

.. code-block:: Python


    # butterfly, brain = plot.GlassBrain.butterfly(result)








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

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


.. _sphx_glr_download_auto_examples_mass-univariate-statistics_volume-source-space.py:

.. only:: html

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

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

      :download:`Download Jupyter notebook: volume-source-space.ipynb <volume-source-space.ipynb>`

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

      :download:`Download Python source code: volume-source-space.py <volume-source-space.py>`

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: volume-source-space.zip <volume-source-space.zip>`


.. only:: html

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

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