Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

FreeSurfer: mri_vol2surf

https://doi.org/10.5281/zenodo.18728766
Run this notebook

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

License:

MIT License

Note: If this notebook uses neuroimaging tools from Neurocontainers, those tools retain their original licenses. Please see Neurodesk citation guidelines for details.

Citation and Resources:

Tools included in this workflow

FreeSurfer

  • Fischl B. (2012). FreeSurfer. NeuroImage, 62(2), 774–781. Fischl (2012)

Dataset

Open source Data from OpenNeuro:

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. Chang et al. (2025)

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==2.3.5 nilearn==0.13.1 nibabel==5.3.3

Import relevant libraries

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

Load FreeSurfer

await module.load('freesurfer/8.1.0')
await module.list()
['freesurfer/8.1.0']

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)
Fetching long content....
0

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
mri_vol2surf done
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
mri_vol2surf done
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
mri_vol2surf done
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
mri_vol2surf done
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
mri_vol2surf done
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
mri_vol2surf done
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
mri_vol2surf done
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
mri_vol2surf done
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
mri_vol2surf done
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
mri_vol2surf done
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
mri_vol2surf done

INFO: using NIfTI-1 sform (sform_code=2)
INFO: using NIfTI-1 sform (sform_code=2)
INFO: using NIfTI-1 sform (sform_code=2)
INFO: using NIfTI-1 sform (sform_code=2)
INFO: using NIfTI-1 sform (sform_code=2)
INFO: using NIfTI-1 sform (sform_code=2)
INFO: using NIfTI-1 sform (sform_code=2)
INFO: using NIfTI-1 sform (sform_code=2)
INFO: using NIfTI-1 sform (sform_code=2)
INFO: using NIfTI-1 sform (sform_code=2)
INFO: using NIfTI-1 sform (sform_code=2)

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-8.1.0/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-8.1.0/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-8.1.0/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-8.1.0/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-8.1.0/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-8.1.0/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-8.1.0/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-8.1.0/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-8.1.0/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-8.1.0/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-8.1.0/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
/opt/freesurfer-8.1.0/bin/mris_convert derivatives/freesurfer/sub-01/surf/lh.sphere derivatives/freesurfer/sub-01/surf/lh.sphere.gii 
Reading in derivatives/freesurfer/sub-01/surf/lh.sphere
Saving derivatives/freesurfer/sub-01/surf/lh.sphere.gii as a surface in TKREGISTER space

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)
    return view

We can generate some interactive plots with ipywidgets and nilearn.

⚠️ Note: ipywidgets that rely on Python callbacks (observe, on_click) require a running kernel and do not function in the static HTML version of this notebook. Widgets using client-side trait linking (jslink) remain interactive without a kernel.

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)
Loading...

Dependencies in Jupyter/Python

  • Using the package watermark to document system environment and software versions used in this notebook, alongside the Neurodesktop version extracted from the JUPYTER_IMAGE or NEURODESKTOP_VERSION environment variables.

import os

%load_ext watermark

%watermark
%watermark --iversions

neurodesktop_version = (
    os.environ.get('JUPYTER_IMAGE', '').split(':')[-1] or
    os.environ.get('NEURODESKTOP_VERSION', 'unknown')
)

print(f"Neurodesktop version: {neurodesktop_version}")
Last updated: 2026-10-05T14:54:02.090870+00:00

Python implementation: CPython
Python version       : 3.13.15
IPython version      : 9.17.1

Compiler    : GCC 15.3.0
OS          : Linux
Release     : 6.8.0-111-generic
Machine     : x86_64
Processor   : x86_64
CPU cores   : 16
Architecture: 64bit

ipywidgets: 8.1.9
nibabel   : 5.3.3
nilearn   : 0.13.1
numpy     : 2.3.5

Neurodesktop version: 2026-09-28
References
  1. Fischl, B. (2012). FreeSurfer. NeuroImage, 62(2), 774–781. 10.1016/j.neuroimage.2012.01.021
  2. 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. 10.1167/jov.25.1.5
  3. Polimeni, J. R., Fischl, B., Greve, D. N., & Wald, L. L. (2010). Laminar analysis of 7T BOLD using an imposed spatial activation pattern in human V1. NeuroImage, 52(4), 1334–1346. 10.1016/j.neuroimage.2010.05.005
  4. Dumoulin, S. O., & Wandell, B. A. (2008). Population receptive field estimates in human visual cortex. NeuroImage, 39(2), 647–660. 10.1016/j.neuroimage.2007.09.034
Neurodesk
Introduction to Preprocessing
Neurodesk
tedana: TE Dependent ANAlysis