:orphan:

=============================================
Examples
=============================================



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. thumbnail-parent-div-close

.. raw:: html

    </div>

########
Examples
########

Some introduction to the encoding/decoding framework.


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="In this example, we fit a residual noise covariance matrix to simulated data from a VonMisesPRF-model.">

.. only:: html

  .. image:: /auto_examples/00_encodingdecoding/images/thumb/sphx_glr_fit_residuals_thumb.png
    :alt:

  :doc:`/auto_examples/00_encodingdecoding/fit_residuals`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Fit the residual covariance matrix</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="It can be helpful to _constrain_ the decoding of a stimulus. For example, we might no be interested in decoding the location of the stimulus, but, rather, want to know which part of the stimulus show most drive.">

.. only:: html

  .. image:: /auto_examples/00_encodingdecoding/images/thumb/sphx_glr_masked_stimulus_decoding_thumb.png
    :alt:

  :doc:`/auto_examples/00_encodingdecoding/masked_stimulus_decoding`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Stimulus decoding using stimulus mask</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="When it comes to fitting encoding models to fMRI data, the most common approach is to use a linear encoding model, were the predicted BOLD response is a linear combination of different neural populations with predefined tuning properties.">

.. only:: html

  .. image:: /auto_examples/00_encodingdecoding/images/thumb/sphx_glr_linear_encoding_model_thumb.png
    :alt:

  :doc:`/auto_examples/00_encodingdecoding/linear_encoding_model`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Linear encoding model</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="In this example, we create a Gaussian PRF model and plot the predictions. We also simulate data and then estimate back the generating parameters.">

.. only:: html

  .. image:: /auto_examples/00_encodingdecoding/images/thumb/sphx_glr_encoding_model_thumb.png
    :alt:

  :doc:`/auto_examples/00_encodingdecoding/encoding_model`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Create a simple Gaussian Prf encoding model</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Here we invert different encoding models">

.. only:: html

  .. image:: /auto_examples/00_encodingdecoding/images/thumb/sphx_glr_invert_model_thumb.png
    :alt:

  :doc:`/auto_examples/00_encodingdecoding/invert_model`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Invert encoding model</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Here we will simulate neural data given a ground truth encoding model  and try to decode the stimulus from the data.">

.. only:: html

  .. image:: /auto_examples/00_encodingdecoding/images/thumb/sphx_glr_decode_thumb.png
    :alt:

  :doc:`/auto_examples/00_encodingdecoding/decode`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Decoding of stimuli from neural data</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Recontruct a 2D visual stimulus from real fMRI data">

.. only:: html

  .. image:: /auto_examples/00_encodingdecoding/images/thumb/sphx_glr_decode_v1_thumb.png
    :alt:

  :doc:`/auto_examples/00_encodingdecoding/decode_v1`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Recontruct a 2D visual stimulus from real fMRI data</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Here we fit a 2D PRF model to data from the Szinte (2024)-dataset.">

.. only:: html

  .. image:: /auto_examples/00_encodingdecoding/images/thumb/sphx_glr_decode_visual_thumb.png
    :alt:

  :doc:`/auto_examples/00_encodingdecoding/decode_visual`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Fit a 2D PRF model</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Fisher information is defined as the expected value of the square of the derivative of the log-likelihood with respect to some parameter.">

.. only:: html

  .. image:: /auto_examples/00_encodingdecoding/images/thumb/sphx_glr_fisher_information_thumb.png
    :alt:

  :doc:`/auto_examples/00_encodingdecoding/fisher_information`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Fisher information to estimate precision of encoding parameters across stimulus space</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="In this example script we will try out increasingly complex models for visual population receptive fields (PRFs). We will start with a simple Gaussian PRF model, and then add more complexity step by step.">

.. only:: html

  .. image:: /auto_examples/00_encodingdecoding/images/thumb/sphx_glr_fit_prf_thumb.png
    :alt:

  :doc:`/auto_examples/00_encodingdecoding/fit_prf`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Different flavors of visual population receptive field models</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Here, we are decoding oriented stimuli from neural data that have an extra dimension: amplitude.">

.. only:: html

  .. image:: /auto_examples/00_encodingdecoding/images/thumb/sphx_glr_decode2d_thumb.png
    :alt:

  :doc:`/auto_examples/00_encodingdecoding/decode2d`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Decoding 2D stimuli from neural data</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

######################################
End-to-end decoding pipeline on real data
######################################

Three connected examples that walk through a full encoding-model decoding
pipeline on a small extract of single-trial fMRI data (numerosity task,
right numerosity-tuned parietal cortex):

1. Select responsive voxels from whole-brain R² by fitting a 2-component
   mixture and picking a threshold (FDR or posterior).
2. Decode trial-wise stimulus posteriors using a noise model whose
   covariance is regularised by *geodesic* distance on the cortical surface.
3. Quantify *expected* decoding uncertainty by simulating from the fitted
   model and re-decoding.

Each example is self-contained but share the same demo dataset, which is
downloaded on first run via ``braincoder.utils.data.load_dehollander2024_npc``.



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="When you fit an encoding model to whole-brain fMRI data, most voxels are genuinely noise — they don&#x27;t tune to the stimulus dimension you&#x27;re modelling. Almost every downstream analysis (decoding, Fisher information, expected uncertainty) needs a way to select voxels that actually carry signal, without hand-picking an arbitrary R² cutoff.">

.. only:: html

  .. image:: /auto_examples/01_decoding_pipeline/images/thumb/sphx_glr_01_voxel_selection_fdr_thumb.png
    :alt:

  :doc:`/auto_examples/01_decoding_pipeline/01_voxel_selection_fdr`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Voxel selection via a 2-component R² mixture model</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Fisher information gives a local lower bound on the variance of any unbiased estimator of a stimulus from a fitted encoding model. It&#x27;s quick to compute and useful as a theoretical bound, but it ignores two things you usually care about in practice:">

.. only:: html

  .. image:: /auto_examples/01_decoding_pipeline/images/thumb/sphx_glr_03_expected_uncertainty_thumb.png
    :alt:

  :doc:`/auto_examples/01_decoding_pipeline/03_expected_uncertainty`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Expected decoding uncertainty via simulate + decode</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="For Bayesian decoding from an encoding model, the noise covariance \Omega between voxels matters as much as the tuning curves themselves. The simplest assumption is uncorrelated isotropic noise (diagonal \Omega), but real fMRI noise has substantial spatially-structured correlations — voxels that sit near each other on the cortical sheet share more noise than distant ones.">

.. only:: html

  .. image:: /auto_examples/01_decoding_pipeline/images/thumb/sphx_glr_02_geodesic_decoder_thumb.png
    :alt:

  :doc:`/auto_examples/01_decoding_pipeline/02_geodesic_decoder`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Geodesic-regularised noise model for trial-wise decoding</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>


.. toctree::
   :hidden:
   :includehidden:


   /auto_examples/00_encodingdecoding/index.rst
   /auto_examples/01_decoding_pipeline/index.rst


.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-gallery

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

      :download:`Download all examples in Python source code: auto_examples_python.zip </auto_examples/auto_examples_python.zip>`

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

      :download:`Download all examples in Jupyter notebooks: auto_examples_jupyter.zip </auto_examples/auto_examples_jupyter.zip>`


.. only:: html

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

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