NeuroFormats.jl
Handling of structural neuroimaging file formats for Julia.
About
The NeuroFormats package provides an API for reading structural neuroimaging data files in Julia. The focus is on surface-based data, as produced by FreeSurfer. The aim of the package is to allow scientists to access their neuroimaging data in Julia so they can use the language's power to implement custom data analysis pipelines.
Note that some functions for reading neuroimaging data files are available from JuliaNeuroscience, e.g., NIFTI volume and GIFTI mesh support. This package does not duplicate these functionalities.
Features
- Read and write FreeSurfer per-vertex data in curv format (like
subject/surf/lh.thickness
): functionsread_curv()
andwrite_curv()
- Read brain meshes in FreeSurfer binary mesh format (like
subject/surf/lh.white
):read_surf()
- Read FreeSurfer label files (like
subject/label/lh.cortex.label
):read_label()
- Read FreeSurfer brain surface parcellations (like
subject/label/lh.aparc.annot
):read_annot()
- Read and write FreeSurfer MGH and MGZ brain volumes (4D voxel images, like
subject/mri/brain.mgz
):read_mgh()
andwrite_mgh()
- Read DTI track data from MRtrix3 TCK files:
read_tck()
- Read DTI track data from DiffusionToolkit TRK files:
read_trk()
Installation
You can find NeuroFormats on JuliaHub, so all you need to do is:
using Pkg
Pkg.add("NeuroFormats")
from a Julia session.
Documentation
The documentation is included with the package and can be browsed online at JuliaHub. It is not repeated on this website.
Use ?
to access the package documentation from within Julia, e.g., get help on a function named read_curv
from within Julia by typing ?read_curv
. I also encourage you to have a look at the unit tests of this package, they are essentially a collection of usage examples.
Usage Examples
Example 1: Cortical thickness on a brain mesh
The following example shows how to load a FreeSurfer brain mesh with per-vertex data and visualize it in Julia using NeuroFormats and GLMakie.
Note: If you do not have GLMakie
installed, install it with Pkg.add()
as described for NeuroFormats
above. In that case, the example below will take a while to execute the first time you run it, as the packages will need to be precompiled first. Afterwards, visualization will be almost instant.
using NeuroFormats
using GLMakie
# Uses NeuroFormats demo data, feel free to use your own FreeSurfer data.
fs_subject_dir = joinpath(tdd(), "subjects_dir/subject1/")
surf = read_surf(joinpath(fs_subject_dir, "surf/lh.white")) # The brain mesh.
curv = read_curv(joinpath(fs_subject_dir, "surf/lh.thickness")) # cortical thickness.
vertices = surf.mesh.vertices
faces = surf.mesh.faces .+ 1
scene = mesh(vertices, faces, color = curv)
Example 2: An MRI volume
This example loads a 3D MRI scan of a brain and visualizes it.
using NeuroFormats
using GLMakie
mgh = read_mgh(joinpath(tdd(), "subjects_dir/subject1/mri/brain.mgz"))
volume = dropdims(mgh.data, dims = 4) # drop time dimension, we only have one frame here.
axis = range(0, stop = 1, length = size(volume, 1))
scene3d = contour(axis, axis, axis, volume, alpha = 0.1, levels = 6)
Example 3: An atlas-based brain surface parcellation
using NeuroFormats
using GLMakie
fs_subject_dir = joinpath(tdd(), "subjects_dir/subject1/")
surf = read_surf(joinpath(fs_subject_dir, "surf/lh.white"))
annot = read_annot(joinpath(fs_subject_dir, "label/lh.aparc.annot")) # from Desikan-Killiani atlas
vertices = surf.mesh.vertices
faces = surf.mesh.faces .+ 1
scene = mesh(vertices, faces, color = vertex_colors(annot))
Development
License
NeuroFormats is free software published under the GPL v3, see the LICENSE file for the full license.
Citing
Please consider citing NeuroFormats if you use it for your research.
To cite package ‘NeuroFormats’ in publications use:
Tim Schäfer (2021). NeuroFormats: Handling of structural neuroimaging file formats for Julia. Julia package version 0.2.2. https://juliahub.com/ui/Packages/NeuroFormats/zxLcF/
A BibTeX entry for LaTeX users is
@Manual{,
title = {NeuroFormats: Handling of structural neuroimaging file formats for Julia},
author = {Tim Schäfer},
year = {2021},
note = {Julia package version 0.2.2},
url = {https://juliahub.com/ui/Packages/NeuroFormats/zxLcF/},
}
Be sure to adapt the package version to the version you actually used.
Unit tests and continuous integration
Continuous integration results:
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. You can also let me know if you need support for a new file format.
Please see CONTRIBUTING.md for instructions on how to contribute code.
The NeuroFormats package was written by Tim Schäfer. To contact me in person, please use the email address given on my website.