R implementation of the registration fusion method for MNI152 and Colin27 to fsaverage/MNI305 mapping.
This package supports easy mapping of neuroimgaging data between the volume and surface templates used by the most common software package for structural neuroimaging in R:
- FreeSurfer surface space: the fsaverage template, in MNI305 space
- FSL volume space: the MNI152 template
- SPM volumne space: the Colin27 template
This is an R implementation of Wu et al. (2018)'s registration fusion methods to project 3D magnetic resonance imaging (MRI) data from standard space volumetric coordinates, either MNI152 or Colin27, to Freesurfer's fsaverage (MNI305), and the other way around. Using this non-linear approach gives higher accuracy than the linear transformation with a 4x4 matrix. See the paper for details.
This R implementation is heavily inspired by Dan Gale's Python implementation in the regfusion pypi package. A huge thank you to Dan Gale and Wu et al. for making their excellent tools openly available!
The API of the regfusionr package consists of the following functions:
Volume → fsaverage surface:
mni152_coords_to_fsaverage(): Map MNI152 RAS coordinates to fsaverage vertices and coordinates.colin27_coords_to_fsaverage(): Map Colin27 RAS coordinates to fsaverage vertices and coordinates.vol_to_fsaverage(): Project 3D or 4D data from an MNI152 or Colin27 volume (NIFTI or MGH/MGZ) to fsaverage per-vertex data.
fsaverage surface → volume:
fsaverage_vertices_to_mni152_coords(): Map fsaverage vertex indices to MNI152 RAS coordinates.fsaverage_vertices_to_colin27_coords(): Map fsaverage vertex indices to Colin27 RAS coordinates.fsaverage_vertices_to_vol_coords(): General function to map fsaverage vertices to MNI152 or Colin27 coordinates (supports all template and RF type combinations).fsaverage_to_vol(): Project fsaverage per-vertex data (e.g., cortical thickness maps) to an MNI152 or Colin27 volume.
Cross-template volume-to-volume:
mni152_coords_to_colin27_coords(): Map MNI152 RAS coordinates to Colin27 space (via fsaverage).colin27_coords_to_mni152_coords(): Map Colin27 RAS coordinates to MNI152 space (via fsaverage).
MNI305 (fsaverage) coordinate mapping:
mni305_coords_to_mni152_coords(): Find the closest fsaverage vertex to a given MNI305 coordinate and return its MNI152 coordinates.mni305_coords_to_colin27_coords(): Same, but returns Colin27 coordinates.
Linear method (for comparison):
linear_fsaverage_coords_to_MNI152_coords(): Map fsaverage (MNI305) coordinates to MNI152 using the linear 4×4 matrix from the FreeSurfer documentation. Faster but less accurate.
library('regfusionr');
# Get fsaverage coordinates for the MNI152 RAS coordinates 60.0, 0.0, 10.0 and 0.0, 0.0, 0.0:
mni_ras_coords = matrix(c(60, 0, 10, 0, 0, 0), ncol = 3, byrow = TRUE);
res = mni152_coords_to_fsaverage(mni_ras_coords, surface = "white");
See the unit tests for more usage examples, and use the in-built R help (with ?) to see more details on all the parameters and return values, e.g. ?regfusionr::mni152_coords_to_fsaverage. A vignette with additional examples is also available: vignette("regfusionr").
- Volume-to-surface projection (
vol_to_fsaverage): currently only the 'linear' (trilinear) interpolation method is implemented, suitable for continuous data. The 'nearest' method, required to project integer labels or atlases, is not available yet in this direction. - Surface-to-volume projection (
fsaverage_to_vol): both 'linear' and 'nearest' interpolation are supported. - Coordinate mapping for Colin27 and RF_M3Z: the MNI152 RF-ANTs combination uses a fast pre-computed vertex index volume. All other combinations (Colin27, RF_M3Z) use a .txt-based nearest-vertex fallback that produces correct results but is slower for large numbers of query coordinates.
- The package data files are ~100 MB, exceeding CRAN's 5 MB limit, so this package is distributed via GitHub and R-universe only.
This is a minimal installation with reduced functionality that does not require you to install the optional dependencies, which can be hard to install.
Note: If you want to project volume data (e.g., a NIFTI or MGZ volume) to fsaverage surface space, follow the Full Installation instructions below.
If all you want to do is to obtain fsaverage coordinates for MNI152 voxels or coordinates, you can get away without installing the system dependencies because you do not need the trilinear interpolation functions, and all you need to do is:
via remotes:
install.packages('remotes');
remotes::install_github('dfsp-spirit/regfusionr');
or using R universe:
options(repos = c(
dfspspirit = 'https://dfsp-spirit.r-universe.dev',
CRAN = 'https://cloud.r-project.org'))
install.packages('regfusionr');I prefer R universe.
This is required to use the vol_to_fsaverage() function.
You need to install these from your system shell before installing the R package (see below).
For Debian-based Linux distros, run:
sudo apt install libudunits2-dev libgdal-dev
Required system level packages for other systems:
- rpm-based systems (like Fedora, EPEL, ...):
sudo yum install udunits2-devel gdal-devel - MacOS (via brew):
brew install udunits gdal
From an R session, via remotes:
install.packages('remotes');
remotes::install_github('dfsp-spirit/regfusionr', dependencies = TRUE);
or using R universe:
options(repos = c(
dfspspirit = 'https://dfsp-spirit.r-universe.dev',
CRAN = 'https://cloud.r-project.org'))
install.packages('regfusionr', dependencies = TRUE);I prefer R universe.
You can also use devtools instead of remotes if you already have it installed. For those who haven't, remotes is a lot smaller and faster to install though.
It's unlikely that this package will go to CRAN soon, it requires some data files which are about 100 MB in total size, and CRAN only supports 5 MB. I know one can work around that, but my time for this is limited. If you prefer to install without remotes/devtools, you can also get regfusionr from my R universe repo.
See the development information file.
Fig. 1 Visualization of a central sulcus probability map on the fsaverage surface. The data has been obtained by projecting this probability map in a volume in MNI152 space to the fsaverage surface with the
vol_to_fsaverage function.
In many cases the meshes that you will want to resample to/from are the two hemispheres of the FreeSurfer standard template fsaverage. You have two options to get them:
- Review the FreeSurfer license, and if you accept it, start an
Rsession, and type:fsbrain::download_fsaverage(accept_freesurfer_license=TRUE)to download only the fsaverage template. It will go into the fsbrain appdata directory in your user home, whereregfusionrwill find it. Note that you may need toinstall::packages('fsbrain')first to install fsbrain if you did installregfusionrwith the minimal installation (i.e., without the suggested dependency packages that include fsbrain). - Download and extract FreeSurfer, get a free license file from their website, and use the
fsaverage_pathparameter of thefsaverage_to_volfunction to point it to<freesurfer_install>/subjects/. That directory should be available as the environment variable$SUBJECTS_DIRafter you run the FreeSurfer setup function for your shell.
If all you need is the coordinate mapping and you are fine with a less acurate result, you can use the matrix listed in the FreeSurfer documentation on Coordinate Systems. See section 8b on this website. The method is implemented in this package in the function linear_fsaverage_coords_to_MNI152_coords(). The difference between the results is shown below.
Fig. 2 Difference between the regfusionr approach and the linear method. The coordinates of all fsaverage vertices were mapped to MNI152 space using both the regfusionr method and the linear method. The difference between the two methods was computed as the Euclidean distance between the resulting MNI152 coordinates.
The code used to produce the comparison figure is available in this unit test.
This R package is a reimplementation of the registration fusion method by Wu Jianxiao, Ngo Gia Hung, Greve Douglas, Li Jingwei, He Tong, Fischl Bruce, Eickhoff Simon, and Yeo B.T. Thomas. All credit for the method and the underlying mapping data goes to them. The original MATLAB implementation is part of the CBIG repository.
The R package was heavily inspired by Dan Gale's Python implementation, available as the regfusion package on PyPI and on GitHub. Thank you, Dan, for making your code and the reformatted mapping data openly available.
Both Wu et al. and Dan Gale released their work under permissive open-source licenses, without which this R package would not exist.
Just cite the original Wu et al. paper:
Wu J, Ngo GH, Greve DN, Li J, He T, Fischl B, Eickhoff SB, Yeo BTT. Accurate nonlinear mapping between MNI volumetric and FreeSurfer surface coordinate systems, Human Brain Mapping 39:3793–3808, 2018.