Brainload Example Workflows¶
This document illustrates example workflows for common tasks.
Loading data for a single subject¶
Load brain mesh and morphometry data for a single subject in subject space¶
In this example, we will load area data for each vertex of the example subject bert that comes with FreeSurfer from the files ?h.area
. We will not rely on the environment variable SUBJECTS_DIR, but explicitly specify the directory containing the data.
import brainload as bl
import os
freesurfer_dir = os.path.join('usr', 'local', 'freesurfer') # or wherever your FREESURFER_HOME is
subjects_dir = os.path.join(freesurfer_dir, 'subjects')
vert_coords, faces, per_vertex_data, meta_data = bl.subject('bert', subjects_dir=subjects_dir, measure='area')
This operation loaded 4 files: the 2 brain mesh files (one for the hemisphere, one for the right hemisphere) and the 2 morphometry data files. The mesh data are in the variables vert_coords and faces, and the morphometry data can be found in per_vertex_data. The meta_data contains information on the loaded data. Let’s use it to see exactly which files were loaded.
print "%s\n%s\n%s\n%s\n" % (meta_data['lh.curv_file'], meta_data['rh.curv_file'], meta_data['lh.morphometry_file'], meta_data['rh.morphometry_file'])
/usr/local/freesurfer/subjects/bert/surf/lh.white
/usr/local/freesurfer/subjects/bert/surf/rh.white
/usr/local/freesurfer/subjects/bert/surf/lh.area
/usr/local/freesurfer/subjects/bert/surf/rh.area
This way you always know what data you are working with. See the API documentation for more options. You can specify a different surface, load only one hemisphere, or not load the mesh at all when using this function.
Load morphometry data for a single subject that has been mapped to a common subject¶
In this example, we will load morphometry data that have been mapped to a common subject, in this case, the fsaverage subject from FreeSurfer. The data have to be mapped using the recon-all ... -qcache
FreeSurfer command. We assume the data already exist for your subject in files like ?h.area.fwhm20.fsaverage.mgh.
import brainload as bl
import os
subjects_dir = os.path.join(os.getenv('HOME'), 'data', 'mystudy')
vert_coords, faces, morphometry_data, meta_data = bl.subject_avg('subject1', subjects_dir=subjects_dir, measure='area', fwhm='20')
This operation loaded 4 files: the 2 brain mesh files of the fsaverage subject and the 2 morphometry data files of subject1. The mesh data are in the variables vert_coords and faces, and the morphometry data can be found in per_vertex_data. The meta_data contains information on the loaded data. Let’s use it to see exactly which files were loaded.
print "%s\n%s\n%s\n%s\n" % (meta_data['lh.curv_file'], meta_data['rh.curv_file'], meta_data['lh.morphometry_file'], meta_data['rh.morphometry_file'])
/home/me/data/mystudy/fsaverage/surf/lh.white
/home/me/data/mystudy/fsaverage/surf/rh.white
/home/me/data/mystudy/subject1/surf/lh.area.fwhm20.fsaverage.mgh
/home/me/data/mystudy/subject1/surf/rh.area.fwhm20.fsaverage.mgh
See the API documentation for more options. You can specify a different surface, load only one hemisphere, not load the mesh at all, or chose a custom average subject when using this function.