search

dfsp-spirit / freesurferformats

GNU R package for reading and writing neuroimaging file formats. Not limited to FreeSurfer anymore, despite its name.
Other
23 stars 3 forks source link
brain brain-atlas brain-surfaces curv dti fileformats freesurfer label mesh mgh mri neuroimaging parcellation r research surface voxel

readme

AppVeyor build status codecov

freesurferformats

GNU R package to read and write structural neuroimaging file formats. Comes with support for file formats used by FreeSurfer, CAT12/SPM, FSL, BrainVoyager, MRtrix3, Diffusion Toolkit/TrackVis and other neuroimaging software packages.

Vis

Supported formats | Installation | Documentation | License | Citation | Development

A note to end users

This low-level package provides well-tested file format readers and writers for FreeSurfer neuroimaging data. Typically, you want to access not only individual files, but datasets of subjects stored in the standardized output structure of recon-all (your $SUBJECTS_DIR) when doing neuroimaging research. In that case, I recommend to use the high-level functions from the fsbrain package instead of re-inventing the wheel. The fsbrain package is built on top of freesurferformats and provides functions for working with the data of your study, including visualization of results on brain meshes.

Supported formats

You do not need to have FreeSurfer installed to use this package. It implements its own readers and writers for the following file formats:

We also provide wrappers and adapter functions for existing neuroimaging file format packages, which load the data into freesurferformats data structures:

Installation

The package is on CRAN, so you can simply:

install.packages("freesurferformats")

If you want support for as many neuroimaging file formats as possible, do this instead to install with all optional dependencies:

install.packages("freesurferformats", dependencies=TRUE);

The package is also available from neuroconductor.

In case something goes wrong, don't worry. Just install the missing system dependencies and retry.

System dependencies

Note: You can ignore this section unless you want to build the freesurferformats package from the source code.

A system dependency is a non-R software that is needed for the installation of a package. System dependencies cannot be installed automatically using the R package system, so you need to install them manually or using the package manager of your operating system.

If you install R packages from source (the default under Linux) and want support for the GIFTI XML file format, you will need libxml2-dev. If you do not have it installed already, before installing freesurferformats, run the following command in your system shell (not in R):

Documentation

Quick Usage

Before using any functions, of course load the package itself:

library("freesurferformats")

Now you can call the following functions:

read.fs.mgh()         # read volume or morphometry data from files in MGH or MGZ format, e.g., `mri/brain.mgz` or `surf/lh.area.fwhm10.fsaverage.mgh`.
read.fs.curv()        # read morphometry data from 'curv' format files like `surf/lh.area`
read.fs.morph()       # read any morphometry file (mgh/mgz/curv). The format is derived from the file extension.
read.fs.annot()       # read annotation data or brain atlas labels from files like `label/lh.aparc.annot`
read.fs.surface()     # read a surface mesh, like `surf/lh.white`, supports many standard mesh formats
read.fs.label()       # read a label file, like `label/lh.cortex.label`
read.fs.colortable()  # read a color lookup table (LUT), like `$FREESURFER_HOME/FreeSurferColorLUT.txt`
read.fs.weight()      # read scalar data for a subset of vertices, defined by index. Known as `weight`, `paint` or simply `w` format.
read.fs.patch()       # read a surface patch, which is a part of a surface.
read.fs.transform()   # read spatial transformation matrix
read.dti.tck()        # read DTI tracks from MRtrix3 'TCK' format
read.dti.trk()        # read DTI tracks from Diffusion Toolkit/TrakVis 'TRK' format

write.fs.mgh()        # write data with 1 to 4 dimensions to an MGH format file
write.fs.curv()       # write a data vector to a 'curv' format file
write.fs.morph()      # write any morphometry file (mgh/mgz/curv). The format is derived from the file extension.
write.fs.surface()    # write a surface mesh
write.fs.label()      # write a label file
write.fs.annot()      # write an annotation file
write.fs.colortable() # write a color lookup table (LUT)
write.fs.weight()     # write scalar vertex data in weight or w format
write.fs.patch()      # write a surface patch, which is a part of a surface.

The documentation is included in the package and not repeated on this website.

Full Documentation

The documentation can be accessed from within an R session after you have loaded the freesurferformats package:

An example R session: Reading Bert's brain

One of the example subjects that comes with FreeSurfer is bert. The following example shows how to load Bert's brain. If you have FreeSurfer installed, you can start GNU R by typing R in your favourite terminal application and run the following commands:

install.packages("freesurferformats")

# Load volume from file
library("freesurferformats")
berts_brain = paste(Sys.getenv("FREESURFER_HOME"), "/subjects/bert/mri/brain.mgz", sep="")
mgh = read.fs.mgh(berts_brain, with_header=TRUE);

# Compute the vox2ras matrix from the header:
mghheader.vox2ras(mgh)
#     [,1] [,2] [,3]      [,4]
#[1,]   -1    0    0  133.3997
#[2,]    0    0    1 -110.0000
#[3,]    0   -1    0  128.0000
#[4,]    0    0    0    1.0000

# ...and the data:
mean(mgh$data)
#[1] 8.214322
dim(drop(mgh$data))
# [1] 256 256 256

If you do not have FreeSurfer installed and thus don't have Bert, replace berts_brain with the example brain that comes with freesurferformats:

fsf_brain = system.file("extdata", "brain.mgz", package = "freesurferformats", mustWork = TRUE);

License

The freesurferformats package is free software, published under the MIT license.

Note: The file LICENSE in this repository is a CRAN license template only (as required by CRAN) and does not contain the full MIT license text. See the file LICENSE_FULL for the full license text.

Citation

A paper is in the making. For now, please cite the R package. You can generate the citation for the version you use by typing the following command in R:

citation("freesurferformats")

This will ouput something like this (but for the version you actually used, which is important for reproducibility):

To cite package ‘freesurferformats’ in publications use:

  Tim Schäfer (2020). freesurferformats: Read and Write 'FreeSurfer'
  Neuroimaging File Formats. R package version 0.1.9.
  https://CRAN.R-project.org/package=freesurferformats

A BibTeX entry for LaTeX users is

  @Manual{,
    title = {freesurferformats: Read and Write 'FreeSurfer' Neuroimaging File Formats},
    author = {Tim Schäfer},
    year = {2020},
    note = {R package version 0.1.9,
    url = {https://CRAN.R-project.org/package=freesurferformats},
    doi = {10.5281/zenodo.3540434},
    url = {https://dx.doi.org/10.5281/zenodo.3540434},
  }

The Digital Object Identifier (DOI) for freesurferformats is: 10.5281/zenodo.3540434. Note that this DOI always points to the latest version, so be sure to still include the package version in the citation.

A poster of freesurferformats has been presented at INSAR 2020 Annual Meeting: Abstract, ePoster

Development

Installing the development version

You can install the latest development version directly from Github if you need features which have not been released yet. Please run the tests before using the dev version (see the Unit tests / CI section below).

If you do not have devtools and related tools installed yet:

install.packages(c("devtools", "knitr", "rmarkdown", "testthat", "covr"));

Then:

devtools::install_github("dfsp-spirit/freesurferformats", build_vignettes=TRUE)

While the development versions may have new features, you should not consider their API stable. Wait for the next release if you are not fine with adapting your code to API changes later. If in doubt, do not use the dev version.

Unit tests and Continuous integration

This package comes with lots of unit tests. To run them, in a clean R session:

library(devtools)
library(freesurferformats)
devtools::check()

Continuous integration results:

R-CMD-check

AppVeyor build status AppVeyor CI under Windows

codecov Test coverage

The displayed status represents the development version. Don't worry if you are using the stable version from CRAN and CI is currently failing.

Contributing

If you found a bug, have any question, suggestion or comment on freesurferformats, please open an issue. I will definitely answer and try to help.

Please see CONTRIBUTING.md for instructions on how to contribute code.

The freesurferformats package was written by Tim Schäfer. To contact me in person, please use the maintainer email address listed on the CRAN webpage for freesurferformats.