In this document, we show how to write brain imaging data to FreeSurfer binary files.
Morphometry data, or vertex-wise measures, are data that usually describe a measure like cortical thickness or surface area over the cortex. There is one scalar value per vertex of the brain surface mesh. Of course, you could write whatever you want (p-values, effect sizes at the vertex, …), as long as the data is scalar.
The package provides the
write.fs.morph function to
write any scalar data that does not require metadata like MR acquisition
parameters or transforms. With this function, the format gets determined
automatically from the file name. In the following example, we load the
area and thickness values for a subject and write the product of area
and thickness (which is not cortical volume, by the way) to new
files in MGH, MGZ and curv format.
Let’s first load the data:
Now we could write our derived data like this:
When writing 3D or 4D images, the voxels alone are sometimes not
enough: depending on what you intend to do with the data later on, you
may want to save metadata like MR acquisition parameters or vox2ras
transformation matrices in the file header. This is possible with the
write.fs.mgh function, that gives you full control over the
MGH header. The two relevant pieces of header data are:
vox2ras_matrix: a 4x4 double matrix that encodes
the affine transformation from voxel indices to x, y, z
coordinates in space
mr_params: a double vector of length 4 that
contains the following values (in this order):
Here is an example that writes a file in MGH format including custom header data:
mgh_outfile = "mystudy/subject1/mri/shifted_brain.mgz"
data = array(data=rep(1L, 256*256*256), dim=c(256,256,256)); # not exactly a brain, but will do.
mr_params = c(2300, 0.1, 2., 900.)
vox2ras_matrix = matrix(c(-1,0,0,0, 0,0,-1,0, 0,1,0,0, 127.5,-98.6273,79.0953,1.000), nrow=4, byrow = FALSE)
write.fs.mgh(mgh_outfile, data, vox2ras_matrix=vox2ras_matrix, mr_params=mr_params);
Note that if and only if you provide a
ras2vox_matrix, the ras_good flag will be set to
TRUE in the file header. If you do not provide
mr_params, they default to all zero.
Data can be stored in the following data types in MGH files:
One can control the data type that is used through the
dtype parameter. The default value, ‘auto’, will determine
the MRI data type from the R data type of the
parameter. The following rules are applied for R data types:
You can manually set the ‘dtype’ parameter to force a certain MRI data type. E.g., you could force ‘MRI_SHORT’ for your integer data if you are sure that the supported value range of that data type is enough for the values contained in your data. Be aware though that chosing an unsuitable MRI data type for your data will lead to an MGH file with incorrect data.
Hint: If you need to save data in a certain data type, cast
your data before passing them to the
E.g., if you have integers but want to store them as ‘MRI_FLOAT’, do the
Notice: That was an example only. For a label, storing the indices as
MRI_FLOAT makes little sense (you could use
instead to store them as as ‘MRI_UCHAR’).
You can use
write.fs.curv to write arbitrary data in
binary curv format. The result is identical to using
write.fs.morph with any filename that does not end in
It’s worth knowing the if your filename ends with
the file will be written compressed.
You can use
write.fs.surface to write triangular meshes
in binary surface format (the format used for files like ‘surf/lh.white’
or ‘surf/rh.pial’). A mesh is defined by a list of vertices and a list
of faces as indices into the latter, knows as an indexed
The vertex indices used to define the faces should be 1-based, as used in R. They will be written 0-based to the file.
You can also use this function to write meshes in FreeSurfer ASCII
.asc) or in VTK ASCII format (
see the parameter
format for details.
Labels can be written with the
A label is nothing but a list of vertex indices. These indices should be
passed 1-based, as they are used in
You can attach a single floating point value to each vertex of the label, see the parameter ‘vertex_data’ for details.
The following example uses the
function to write a colortable:
A colortable is a table that contains one structure per row, and assigns each structure an RGBA color. Colortables are typically used to color the different brain regions of the segmented brain volume. The file ‘FreeSurferColorLUT.txt’ that comes with FreeSurfer is an example for a colortable.