Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/dfsp-spirit/neuroformats.jl
Handling of structural neuroimaging file formats for Julia.
https://github.com/dfsp-spirit/neuroformats.jl
brain cortex dti fileformats freesurfer julia mesh mri neuroimaging neuroscience surface voxel
Last synced: 7 days ago
JSON representation
Handling of structural neuroimaging file formats for Julia.
- Host: GitHub
- URL: https://github.com/dfsp-spirit/neuroformats.jl
- Owner: dfsp-spirit
- License: gpl-3.0
- Created: 2021-01-09T21:15:29.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2023-07-23T11:43:33.000Z (over 1 year ago)
- Last Synced: 2024-10-11T07:16:15.577Z (27 days ago)
- Topics: brain, cortex, dti, fileformats, freesurfer, julia, mesh, mri, neuroimaging, neuroscience, surface, voxel
- Language: Julia
- Homepage:
- Size: 6.23 MB
- Stars: 11
- Watchers: 3
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGES
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# NeuroFormats.jl
Handling of structural neuroimaging file formats for [Julia](https://julialang.org).
[](https://doi.org/10.5281/zenodo.8120740) [](https://github.com/dfsp-spirit/NeuroFormats.jl/blob/main/LICENSE) [](https://github.com/dfsp-spirit/NeuroFormats.jl/actions)
## 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](https://freesurfer.net). 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](https://github.com/JuliaNeuroscience), e.g., [NIFTI volume](https://github.com/JuliaNeuroscience/NIfTI.jl) and [GIFTI mesh](https://github.com/JuliaNeuroscience/GIFTI.jl) support. This package does not duplicate these functionalities.
This package is not under heavy development anymore, but that does not mean that it is unmaintained. I consider it pretty feature-complete, and the file formats do not change. If you feel this package is missing an important format, please open an issue.
## Features
* Read and write FreeSurfer per-vertex data in curv format (like `subject/surf/lh.thickness`): functions `read_curv()` and `write_curv()`
* Read brain meshes in FreeSurfer binary mesh format (like `subject/surf/lh.white`): `read_surf()`
* Read and write FreeSurfer label files (like `subject/label/lh.cortex.label`): `read_label()` and `write_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()` and `write_mgh()`
* Read DTI track data from [MRtrix3](https://www.mrtrix.org/) TCK files: `read_tck()`
* Read DTI track data from [DiffusionToolkit](http://trackvis.org/dtk/) TRK files: `read_trk()`
## News
* 2023-07-06: We just released version 0.3.0 of NeuroFormats. This version has been updated for recent Julia versions and works with Julia 1.9. It also adds support for writing label files. See the [CHANGES](./CHANGES) for more details.
## Installation
You can find [NeuroFormats on JuliaHub](https://juliahub.com/ui/Packages/NeuroFormats/zxLcF/), so all you need to do is:
```julia
using Pkg
Pkg.add("NeuroFormats")
```
from a Julia session.
## Documentation
The documentation is included with the package and can be [browsed online at JuliaHub](https://juliahub.com/docs/NeuroFormats/zxLcF/0.3.0/). 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](./test/), 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.
```julia
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.
```julia
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
```julia
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](./LICENSE) for the full license.
### Citing
Please consider citing NeuroFormats if you use it for your research.
[](https://doi.org/10.5281/zenodo.8120740)
```
To cite package ‘NeuroFormats’ in publications use:
Tim Schäfer (2023). NeuroFormats: Handling of structural neuroimaging file formats for Julia. Julia package version 0.3.0. 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 = {2023},
note = {Julia package version 0.3.0},
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:
Main branch: 
Develop branch: 
### Contributing
If you found a bug, have any question, suggestion or comment on freesurferformats, please [open an issue](https://github.com/dfsp-spirit/NeuroFormats.jl/issues). 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](CONTRIBUTING.md) for instructions on how to contribute code.
The NeuroFormats package was written by [Tim Schäfer](https://ts.rcmd.org). To contact me in person, please use the email address given on my website.