FreeSurfer: mri_vol2surf

FreeSurfer: mri_vol2surf#

Sampling fMRI signal across cortical depths#

mri_vol2surf is a FreeSurfer based command that enables one to assign fMRI signal value to each surface vertex.

#

Author: Fernanda L. Ribeiro

Date: 22 June 2025

Citation and Resources:#

Tools included in this workflow#

FreeSurfer

Fischl B. (2012). FreeSurfer. NeuroImage, 62(2), 774–781. https://doi.org/10.1016/j.neuroimage.2012.01.021

Dataset#

Open source Data from OpenNeuro:

Kelly Chang and Ione Fine and Geoffrey M. Boynton (2024). CHN Retinotopic Mapping Dataset OpenNeuro doi: doi:10.18112/openneuro.ds004698.v2.0.0

Publications#

Original manuscript:

Chang, K., Fine, I., & Boynton, G. M. (2025). Improving the reliability and accuracy of population receptive field measures using a logarithmically warped stimulus. Journal of Vision, 25(1), 5. https://doi.org/10.1167/jov.25.1.5

Goal of this example notebook#

In this example notebook we demonstrate how one can assign fMRI signal values to each cortical surface vertex across cortical depths. This can be relevant, for example, to assess how topographic maps may change across cortical depths and determine the potential impact of vasculature in the topological arrangement of such maps.

Although we do not attempt to reconstruct retinotopic maps in this tutorial, here we show how to perform such procedure using retinotopic mapping data.

Install Python packages#

%%capture
!pip install numpy nilearn nibabel

Import relevant libraries#

import numpy as np
import module
import os
import nibabel as nib

Load FreeSurfer#

await module.load('freesurfer/7.3.2')
await module.list()

Lmod Warning: MODULEPATH is undefined.



Lmod has detected the following error: The following module(s) are unknown:
"freesurfer/7.3.2"

Please check the spelling or version number. Also try "module spider ..."
It is also possible your cache file is out-of-date; it may help to try:
  $ module --ignore_cache load "freesurfer/7.3.2"

Also make sure that all modulefiles written in TCL start with the string
#%Module

[]

Download data from the OpenNeuro#

!datalad install https://github.com/OpenNeuroDatasets/ds004698.git # install NYU retinotopy dataset
os.chdir('ds004698') # change directories
subject='sub-01'
cmd1=f"""datalad get derivatives/freesurfer/{subject}/*""" # download all freesurfer files from subject
cmd2=f"""datalad get derivatives/fmriprep/sub-01/ses-01/func/sub-01_ses-01_task-fixedbar_run-1_*""" #download all preprocessed functional volumes from subject
os.system(cmd1)
os.system(cmd2)

It is highly recommended to configure Git before using DataLad. Set both 'user.name' and 'user.email' configuration variables.
Cloning:   0%|                             | 0.00/2.00 [00:00<?, ? candidates/s]

Enumerating: 0.00 Objects [00:00, ? Objects/s]
                                              
Counting:   0%|                              | 0.00/99.6k [00:00<?, ? Objects/s]

                                                                                
Compressing:   0%|                           | 0.00/68.8k [00:00<?, ? Objects/s]

Compressing:  50%|█████████▌         | 34.4k/68.8k [00:00<00:00, 299k Objects/s]

Compressing:  94%|█████████████████▊ | 64.7k/68.8k [00:00<00:00, 238k Objects/s]
                                                                                
Receiving:   0%|                             | 0.00/99.6k [00:00<?, ? Objects/s]

Receiving:   3%|▌                   | 2.99k/99.6k [00:00<00:03, 29.8k Objects/s]

Receiving:  10%|██                  | 9.96k/99.6k [00:00<00:01, 49.9k Objects/s]

Receiving:  20%|████                | 19.9k/99.6k [00:00<00:01, 67.0k Objects/s]

Receiving:  30%|██████              | 29.9k/99.6k [00:00<00:00, 78.0k Objects/s]

Receiving:  42%|████████▍           | 41.8k/99.6k [00:00<00:00, 91.7k Objects/s]

Receiving:  59%|████████████▍        | 58.8k/99.6k [00:00<00:00, 116k Objects/s]

Receiving:  73%|███████████████▎     | 72.7k/99.6k [00:00<00:00, 120k Objects/s]

Receiving:  86%|██████████████████   | 85.7k/99.6k [00:00<00:00, 116k Objects/s]

                                                                                

Resolving:   0%|                              | 0.00/28.4k [00:00<?, ? Deltas/s]

Resolving:  22%|████▌                | 6.24k/28.4k [00:00<00:00, 61.5k Deltas/s]

Resolving:  49%|██████████▎          | 13.9k/28.4k [00:00<00:00, 70.3k Deltas/s]

Resolving:  74%|███████████████▌     | 21.0k/28.4k [00:00<00:00, 55.9k Deltas/s]

Resolving:  98%|████████████████████▌| 27.8k/28.4k [00:00<00:00, 59.3k Deltas/s]

                                                                                
[INFO   ] Remote origin not usable by git-annex; setting annex-ignore 
[INFO   ] https://github.com/OpenNeuroDatasets/ds004698.git/config download failed: Not Found
[INFO   ] Cannot run git-annex-remote-openneuro -- It is not installed in PATH (/usr/lib/git-core:/opt/conda/bin:/github/home/.local/bin:/opt/conda/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin) 
[INFO   ] Cannot run git-annex-remote-openneuro -- It is not installed in PATH (/usr/lib/git-core:/opt/conda/bin:/github/home/.local/bin:/opt/conda/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin) 
[INFO   ] unable to use external special remote git-annex-remote-openneuro
[INFO   ] Author identity unknown
| 
| *** Please tell me who you are.
| 
| Run
| 
|   git config --global user.email "you@example.com"
|   git config --global user.name "Your Name"
| 
| to set your account's default identity.
| Omit --global to set the identity only in this repository. 
[INFO   ] fatal: unable to auto-detect email address (got 'root@b9bf9defb41b.(none)') 
[INFO   ] git-annex: user error (git ["--git-dir=.git","--work-tree=.","--literal-pathspecs","-c","annex.dotfiles=true","commit-tree","7973d7d20f09ae44d26caacd6481fdd2f3a62956","--no-gpg-sign","-p","refs/heads/git-annex"] exited 128) 
install(error): /tmp/tmpo_pd0xw1/ds004698 (dataset) [CommandError: 'git -c diff.ignoreSubmodules=none -c core.quotepath=false annex init -c annex.dotfiles=true' failed with exitcode 1 under /tmp/tmpo_pd0xw1/ds004698] [CommandError: 'git -c diff.ignoreSubmodules=none -c core.quotepath=false annex init -c annex.dotfiles=true' failed with exitcode 1 under /tmp/tmpo_pd0xw1/ds004698]

---------------------------------------------------------------------------
FileNotFoundError                         Traceback (most recent call last)
Cell In[4], line 2
      1 get_ipython().system('datalad install https://github.com/OpenNeuroDatasets/ds004698.git # install NYU retinotopy dataset')
----> 2 os.chdir('ds004698') # change directories
      3 subject='sub-01'
      4 cmd1=f"""datalad get derivatives/freesurfer/{subject}/*""" # download all freesurfer files from subject

FileNotFoundError: [Errno 2] No such file or directory: 'ds004698'

Sample fMRI data across layers#

if not os.path.exists('../new_data'):
    os.mkdir('../new_data') # create a directory to save the newly sampled fMRI data

Now, we can run mri_vol2surf to sample fMRI signal values from a volume to each surface vertex.

depths = np.arange(0,1.1,0.1)
print(f"Functional data will be sample at the following depths: {depths}")

Functional data will be sample at the following depths: [0.  0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9 1. ]

! Note:

Before assigning fMRI data to each surface vertex make sure that both the anatomical and functional data are aligned.

for depth in depths:
    print(f"""Processing depth: {depth}""")
    cmd = f"""mri_vol2surf --src derivatives/fmriprep/sub-01/ses-01/func/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold.nii.gz \
                 --regheader sub-01 \
                 --hemi lh \
                 --surf white \
                 --projfrac {depth} \
                 --sd derivatives/freesurfer \
                 --out ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-{depth:.1f}.func.mgh"""
    os.system(cmd)

Processing depth: 0.0
srcvol = derivatives/fmriprep/sub-01/ses-01/func/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold.nii.gz
srcreg unspecified
srcregold = 0
srcwarp unspecified
surf = white
hemi = lh
reshape = 0
interp = nearest
float2int = round
GetProjMax = 0
INFO: float2int code = 0
Done loading volume
Computing registration from header.
  Using derivatives/freesurfer/sub-01/mri/orig.mgz as target reference.
-------- original matrix -----------
-1.00000   0.00000  -0.00000   0.12505;
-0.00000  -0.00000   1.00000   2.69328;
 0.00000  -1.00000   0.00000   0.19273;
 0.00000   0.00000   0.00000   1.00000;
-------- original matrix -----------
Reading surface derivatives/freesurfer/sub-01/surf/lh.white
Done reading source surface
Mapping Source Volume onto Source Subject Surface
Projecting 0 0 1
 1 0 0 0
using old
Done mapping volume to surface
Number of source voxels hit = 28255
Writing to ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-0.0.func.mgh
Dim: 221709 1 1
Processing depth: 0.1
srcvol = derivatives/fmriprep/sub-01/ses-01/func/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold.nii.gz
srcreg unspecified
srcregold = 0
srcwarp unspecified
surf = white
hemi = lh
ProjFrac = 0.1
thickness = thickness
reshape = 0
interp = nearest
float2int = round
GetProjMax = 0
INFO: float2int code = 0
Done loading volume
Computing registration from header.
  Using derivatives/freesurfer/sub-01/mri/orig.mgz as target reference.
-------- original matrix -----------
-1.00000   0.00000  -0.00000   0.12505;
-0.00000  -0.00000   1.00000   2.69328;
 0.00000  -1.00000   0.00000   0.19273;
 0.00000   0.00000   0.00000   1.00000;
-------- original matrix -----------
Reading surface derivatives/freesurfer/sub-01/surf/lh.white
Done reading source surface
Reading thickness derivatives/freesurfer/sub-01/surf/lh.thickness
Done
Mapping Source Volume onto Source Subject Surface
Projecting 0.1 0.1 1
 1 0.1 0.1 0.1
using old
Done mapping volume to surface
Number of source voxels hit = 29515
Writing to ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-0.1.func.mgh
Dim: 221709 1 1
Processing depth: 0.2
srcvol = derivatives/fmriprep/sub-01/ses-01/func/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold.nii.gz
srcreg unspecified
srcregold = 0
srcwarp unspecified
surf = white
hemi = lh
ProjFrac = 0.2
thickness = thickness
reshape = 0
interp = nearest
float2int = round
GetProjMax = 0
INFO: float2int code = 0
Done loading volume
Computing registration from header.
  Using derivatives/freesurfer/sub-01/mri/orig.mgz as target reference.
-------- original matrix -----------
-1.00000   0.00000  -0.00000   0.12505;
-0.00000  -0.00000   1.00000   2.69328;
 0.00000  -1.00000   0.00000   0.19273;
 0.00000   0.00000   0.00000   1.00000;
-------- original matrix -----------
Reading surface derivatives/freesurfer/sub-01/surf/lh.white
Done reading source surface
Reading thickness derivatives/freesurfer/sub-01/surf/lh.thickness
Done
Mapping Source Volume onto Source Subject Surface
Projecting 0.2 0.2 1
 1 0.2 0.2 0.2
using old
Done mapping volume to surface
Number of source voxels hit = 30311
Writing to ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-0.2.func.mgh
Dim: 221709 1 1
Processing depth: 0.30000000000000004
srcvol = derivatives/fmriprep/sub-01/ses-01/func/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold.nii.gz
srcreg unspecified
srcregold = 0
srcwarp unspecified
surf = white
hemi = lh
ProjFrac = 0.3
thickness = thickness
reshape = 0
interp = nearest
float2int = round
GetProjMax = 0
INFO: float2int code = 0
Done loading volume
Computing registration from header.
  Using derivatives/freesurfer/sub-01/mri/orig.mgz as target reference.
-------- original matrix -----------
-1.00000   0.00000  -0.00000   0.12505;
-0.00000  -0.00000   1.00000   2.69328;
 0.00000  -1.00000   0.00000   0.19273;
 0.00000   0.00000   0.00000   1.00000;
-------- original matrix -----------
Reading surface derivatives/freesurfer/sub-01/surf/lh.white
Done reading source surface
Reading thickness derivatives/freesurfer/sub-01/surf/lh.thickness
Done
Mapping Source Volume onto Source Subject Surface
Projecting 0.3 0.3 1
 1 0.3 0.3 0.3
using old
Done mapping volume to surface
Number of source voxels hit = 30832
Writing to ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-0.3.func.mgh
Dim: 221709 1 1
Processing depth: 0.4
srcvol = derivatives/fmriprep/sub-01/ses-01/func/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold.nii.gz
srcreg unspecified
srcregold = 0
srcwarp unspecified
surf = white
hemi = lh
ProjFrac = 0.4
thickness = thickness
reshape = 0
interp = nearest
float2int = round
GetProjMax = 0
INFO: float2int code = 0
Done loading volume
Computing registration from header.
  Using derivatives/freesurfer/sub-01/mri/orig.mgz as target reference.
-------- original matrix -----------
-1.00000   0.00000  -0.00000   0.12505;
-0.00000  -0.00000   1.00000   2.69328;
 0.00000  -1.00000   0.00000   0.19273;
 0.00000   0.00000   0.00000   1.00000;
-------- original matrix -----------
Reading surface derivatives/freesurfer/sub-01/surf/lh.white
Done reading source surface
Reading thickness derivatives/freesurfer/sub-01/surf/lh.thickness
Done
Mapping Source Volume onto Source Subject Surface
Projecting 0.4 0.4 1
 1 0.4 0.4 0.4
using old
Done mapping volume to surface
Number of source voxels hit = 31178
Writing to ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-0.4.func.mgh
Dim: 221709 1 1
Processing depth: 0.5
srcvol = derivatives/fmriprep/sub-01/ses-01/func/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold.nii.gz
srcreg unspecified
srcregold = 0
srcwarp unspecified
surf = white
hemi = lh
ProjFrac = 0.5
thickness = thickness
reshape = 0
interp = nearest
float2int = round
GetProjMax = 0
INFO: float2int code = 0
Done loading volume
Computing registration from header.
  Using derivatives/freesurfer/sub-01/mri/orig.mgz as target reference.
-------- original matrix -----------
-1.00000   0.00000  -0.00000   0.12505;
-0.00000  -0.00000   1.00000   2.69328;
 0.00000  -1.00000   0.00000   0.19273;
 0.00000   0.00000   0.00000   1.00000;
-------- original matrix -----------
Reading surface derivatives/freesurfer/sub-01/surf/lh.white
Done reading source surface
Reading thickness derivatives/freesurfer/sub-01/surf/lh.thickness
Done
Mapping Source Volume onto Source Subject Surface
Projecting 0.5 0.5 1
 1 0.5 0.5 0.5
using old
Done mapping volume to surface
Number of source voxels hit = 31350
Writing to ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-0.5.func.mgh
Dim: 221709 1 1
Processing depth: 0.6000000000000001
srcvol = derivatives/fmriprep/sub-01/ses-01/func/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold.nii.gz
srcreg unspecified
srcregold = 0
srcwarp unspecified
surf = white
hemi = lh
ProjFrac = 0.6
thickness = thickness
reshape = 0
interp = nearest
float2int = round
GetProjMax = 0
INFO: float2int code = 0
Done loading volume
Computing registration from header.
  Using derivatives/freesurfer/sub-01/mri/orig.mgz as target reference.
-------- original matrix -----------
-1.00000   0.00000  -0.00000   0.12505;
-0.00000  -0.00000   1.00000   2.69328;
 0.00000  -1.00000   0.00000   0.19273;
 0.00000   0.00000   0.00000   1.00000;
-------- original matrix -----------
Reading surface derivatives/freesurfer/sub-01/surf/lh.white
Done reading source surface
Reading thickness derivatives/freesurfer/sub-01/surf/lh.thickness
Done
Mapping Source Volume onto Source Subject Surface
Projecting 0.6 0.6 1
 1 0.6 0.6 0.6
using old
Done mapping volume to surface
Number of source voxels hit = 31311
Writing to ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-0.6.func.mgh
Dim: 221709 1 1
Processing depth: 0.7000000000000001
srcvol = derivatives/fmriprep/sub-01/ses-01/func/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold.nii.gz
srcreg unspecified
srcregold = 0
srcwarp unspecified
surf = white
hemi = lh
ProjFrac = 0.7
thickness = thickness
reshape = 0
interp = nearest
float2int = round
GetProjMax = 0
INFO: float2int code = 0
Done loading volume
Computing registration from header.
  Using derivatives/freesurfer/sub-01/mri/orig.mgz as target reference.
-------- original matrix -----------
-1.00000   0.00000  -0.00000   0.12505;
-0.00000  -0.00000   1.00000   2.69328;
 0.00000  -1.00000   0.00000   0.19273;
 0.00000   0.00000   0.00000   1.00000;
-------- original matrix -----------
Reading surface derivatives/freesurfer/sub-01/surf/lh.white
Done reading source surface
Reading thickness derivatives/freesurfer/sub-01/surf/lh.thickness
Done
Mapping Source Volume onto Source Subject Surface
Projecting 0.7 0.7 1
 1 0.7 0.7 0.7
using old
Done mapping volume to surface
Number of source voxels hit = 31118
Writing to ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-0.7.func.mgh
Dim: 221709 1 1
Processing depth: 0.8
srcvol = derivatives/fmriprep/sub-01/ses-01/func/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold.nii.gz
srcreg unspecified
srcregold = 0
srcwarp unspecified
surf = white
hemi = lh
ProjFrac = 0.8
thickness = thickness
reshape = 0
interp = nearest
float2int = round
GetProjMax = 0
INFO: float2int code = 0
Done loading volume
Computing registration from header.
  Using derivatives/freesurfer/sub-01/mri/orig.mgz as target reference.
-------- original matrix -----------
-1.00000   0.00000  -0.00000   0.12505;
-0.00000  -0.00000   1.00000   2.69328;
 0.00000  -1.00000   0.00000   0.19273;
 0.00000   0.00000   0.00000   1.00000;
-------- original matrix -----------
Reading surface derivatives/freesurfer/sub-01/surf/lh.white
Done reading source surface
Reading thickness derivatives/freesurfer/sub-01/surf/lh.thickness
Done
Mapping Source Volume onto Source Subject Surface
Projecting 0.8 0.8 1
 1 0.8 0.8 0.8
using old
Done mapping volume to surface
Number of source voxels hit = 30573
Writing to ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-0.8.func.mgh
Dim: 221709 1 1
Processing depth: 0.9
srcvol = derivatives/fmriprep/sub-01/ses-01/func/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold.nii.gz
srcreg unspecified
srcregold = 0
srcwarp unspecified
surf = white
hemi = lh
ProjFrac = 0.9
thickness = thickness
reshape = 0
interp = nearest
float2int = round
GetProjMax = 0
INFO: float2int code = 0
Done loading volume
Computing registration from header.
  Using derivatives/freesurfer/sub-01/mri/orig.mgz as target reference.
-------- original matrix -----------
-1.00000   0.00000  -0.00000   0.12505;
-0.00000  -0.00000   1.00000   2.69328;
 0.00000  -1.00000   0.00000   0.19273;
 0.00000   0.00000   0.00000   1.00000;
-------- original matrix -----------
Reading surface derivatives/freesurfer/sub-01/surf/lh.white
Done reading source surface
Reading thickness derivatives/freesurfer/sub-01/surf/lh.thickness
Done
Mapping Source Volume onto Source Subject Surface
Projecting 0.9 0.9 1
 1 0.9 0.9 0.9
using old
Done mapping volume to surface
Number of source voxels hit = 29872
Writing to ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-0.9.func.mgh
Dim: 221709 1 1
Processing depth: 1.0
srcvol = derivatives/fmriprep/sub-01/ses-01/func/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold.nii.gz
srcreg unspecified
srcregold = 0
srcwarp unspecified
surf = white
hemi = lh
ProjFrac = 1
thickness = thickness
reshape = 0
interp = nearest
float2int = round
GetProjMax = 0
INFO: float2int code = 0
Done loading volume
Computing registration from header.
  Using derivatives/freesurfer/sub-01/mri/orig.mgz as target reference.
-------- original matrix -----------
-1.00000   0.00000  -0.00000   0.12505;
-0.00000  -0.00000   1.00000   2.69328;
 0.00000  -1.00000   0.00000   0.19273;
 0.00000   0.00000   0.00000   1.00000;
-------- original matrix -----------
Reading surface derivatives/freesurfer/sub-01/surf/lh.white
Done reading source surface
Reading thickness derivatives/freesurfer/sub-01/surf/lh.thickness
Done
Mapping Source Volume onto Source Subject Surface
Projecting 1 1 1
 1 1 1 1
using old
Done mapping volume to surface
Number of source voxels hit = 29162
Writing to ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-1.0.func.mgh
Dim: 221709 1 1

Finally, we can convert our data to ‘func.gii’, so we can perform population receptive field modeling using tools like SamSrf.

for depth in depths:
    print(f"Processing depth: {depth}")
    cmd = f"""mri_convert ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-{depth:.1f}.func.mgh \
                    ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-{depth:.1f}.func.gii"""
    os.system(cmd)
    print("Data has been converted!")

Processing depth: 0.0
/opt/freesurfer-7.3.2/bin/mri_convert ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-0.0.func.mgh ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-0.0.func.gii 
reading from ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-0.0.func.mgh...
TR=1200.00, TE=0.00, TI=0.00, flip angle=0.00
i_ras = (1, 0, 0)
j_ras = (0, 1, 0)
k_ras = (0, 0, 1)
writing to ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-0.0.func.gii...
Data has been converted!
Processing depth: 0.1
/opt/freesurfer-7.3.2/bin/mri_convert ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-0.1.func.mgh ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-0.1.func.gii 
reading from ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-0.1.func.mgh...
TR=1200.00, TE=0.00, TI=0.00, flip angle=0.00
i_ras = (1, 0, 0)
j_ras = (0, 1, 0)
k_ras = (0, 0, 1)
writing to ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-0.1.func.gii...
Data has been converted!
Processing depth: 0.2
/opt/freesurfer-7.3.2/bin/mri_convert ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-0.2.func.mgh ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-0.2.func.gii 
reading from ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-0.2.func.mgh...
TR=1200.00, TE=0.00, TI=0.00, flip angle=0.00
i_ras = (1, 0, 0)
j_ras = (0, 1, 0)
k_ras = (0, 0, 1)
writing to ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-0.2.func.gii...
Data has been converted!
Processing depth: 0.30000000000000004
/opt/freesurfer-7.3.2/bin/mri_convert ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-0.3.func.mgh ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-0.3.func.gii 
reading from ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-0.3.func.mgh...
TR=1200.00, TE=0.00, TI=0.00, flip angle=0.00
i_ras = (1, 0, 0)
j_ras = (0, 1, 0)
k_ras = (0, 0, 1)
writing to ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-0.3.func.gii...
Data has been converted!
Processing depth: 0.4
/opt/freesurfer-7.3.2/bin/mri_convert ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-0.4.func.mgh ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-0.4.func.gii 
reading from ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-0.4.func.mgh...
TR=1200.00, TE=0.00, TI=0.00, flip angle=0.00
i_ras = (1, 0, 0)
j_ras = (0, 1, 0)
k_ras = (0, 0, 1)
writing to ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-0.4.func.gii...
Data has been converted!
Processing depth: 0.5
/opt/freesurfer-7.3.2/bin/mri_convert ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-0.5.func.mgh ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-0.5.func.gii 
reading from ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-0.5.func.mgh...
TR=1200.00, TE=0.00, TI=0.00, flip angle=0.00
i_ras = (1, 0, 0)
j_ras = (0, 1, 0)
k_ras = (0, 0, 1)
writing to ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-0.5.func.gii...
Data has been converted!
Processing depth: 0.6000000000000001
/opt/freesurfer-7.3.2/bin/mri_convert ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-0.6.func.mgh ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-0.6.func.gii 
reading from ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-0.6.func.mgh...
TR=1200.00, TE=0.00, TI=0.00, flip angle=0.00
i_ras = (1, 0, 0)
j_ras = (0, 1, 0)
k_ras = (0, 0, 1)
writing to ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-0.6.func.gii...
Data has been converted!
Processing depth: 0.7000000000000001
/opt/freesurfer-7.3.2/bin/mri_convert ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-0.7.func.mgh ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-0.7.func.gii 
reading from ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-0.7.func.mgh...
TR=1200.00, TE=0.00, TI=0.00, flip angle=0.00
i_ras = (1, 0, 0)
j_ras = (0, 1, 0)
k_ras = (0, 0, 1)
writing to ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-0.7.func.gii...
Data has been converted!
Processing depth: 0.8
/opt/freesurfer-7.3.2/bin/mri_convert ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-0.8.func.mgh ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-0.8.func.gii 
reading from ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-0.8.func.mgh...
TR=1200.00, TE=0.00, TI=0.00, flip angle=0.00
i_ras = (1, 0, 0)
j_ras = (0, 1, 0)
k_ras = (0, 0, 1)
writing to ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-0.8.func.gii...
Data has been converted!
Processing depth: 0.9
/opt/freesurfer-7.3.2/bin/mri_convert ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-0.9.func.mgh ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-0.9.func.gii 
reading from ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-0.9.func.mgh...
TR=1200.00, TE=0.00, TI=0.00, flip angle=0.00
i_ras = (1, 0, 0)
j_ras = (0, 1, 0)
k_ras = (0, 0, 1)
writing to ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-0.9.func.gii...
Data has been converted!
Processing depth: 1.0
/opt/freesurfer-7.3.2/bin/mri_convert ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-1.0.func.mgh ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-1.0.func.gii 
reading from ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-1.0.func.mgh...
TR=1200.00, TE=0.00, TI=0.00, flip angle=0.00
i_ras = (1, 0, 0)
j_ras = (0, 1, 0)
k_ras = (0, 0, 1)
writing to ../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-1.0.func.gii...
Data has been converted!

Before moving forward, make sure the newly sampled data has the same shape as previously preprocessed, sampled data.

our_newly_sampled_data = nib.load("../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-1.0.func.gii").agg_data()
previous_sampled_data = nib.load("derivatives/fmriprep/sub-01/ses-01/func/sub-01_ses-01_task-fixedbar_run-1_hemi-L_space-fsnative_bold.func.gii").agg_data()

assert our_newly_sampled_data.shape == previous_sampled_data.shape, "Sampled data is not correct!"

Visualize the data#

!mris_convert derivatives/freesurfer/sub-01/surf/lh.sphere derivatives/freesurfer/sub-01/surf/lh.sphere.gii

Saving derivatives/freesurfer/sub-01/surf/lh.sphere.gii as a surface

from nilearn import plotting
from ipywidgets import Dropdown, interact
import nibabel as nib
import numpy as np

def plot_data(depth, time_point):
    if depth !='average':
        data = np.array(nib.load("../new_data/sub-01_ses-01_task-fixedbar_run-1_space-T1w_desc-preproc_bold_depth-"
                                 + str(depth) + ".func.gii").agg_data())[:,time_point]
    else:
        data = np.array(nib.load("derivatives/fmriprep/sub-01/ses-01/func/sub-01_ses-01_task-fixedbar_run-1_hemi-L_space-fsnative_bold.func.gii").agg_data())[:,time_point]
    view = plotting.view_surf(
    surf_mesh="derivatives/freesurfer/sub-01/surf/lh.sphere.gii",
    surf_map=np.reshape(data[:], (-1)),
    cmap="Reds", black_bg=False, symmetric_cmap=False,
    threshold=0, vmax=10000, darkness=None)
    return view

We can generate some interactive plots with ipywidgets and nilearn.

depth = Dropdown(options = [0.0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0, 'average'])
time_point = Dropdown(options = [0, 50, 100, 150, 200, 250, 300])

@interact(depth = depth, time_point = time_point)
def plot1(depth, time_point):

    return plot_data(depth, time_point)

Dependencies in Jupyter/Python#

Using the package watermark to document system environment and software versions used in this notebook

%load_ext watermark

%watermark
%watermark --iversions

Last updated: 2025-12-04T04:06:29.784777+00:00

Python implementation: CPython
Python version       : 3.11.6
IPython version      : 8.16.1

Compiler    : GCC 12.3.0
OS          : Linux
Release     : 5.4.0-204-generic
Machine     : x86_64
Processor   : x86_64
CPU cores   : 32
Architecture: 64bit

numpy     : 2.2.4
ipywidgets: 8.1.2
nibabel   : 5.3.2
nilearn   : 0.11.1