The riot (R Input/Output for
Tractography) package provides an R interface for importing and
exporting tractography data to and from R. Currently supported
importing formats are:
- native VTK
.vtkand.vtpfiles; - medInria
.fdsfiles; - MRtrix
.tck/.tsffiles; and, - TrackVis
.trkfiles.
The package reads tractography data into a tibble in which each row is a point characterized by at least the following five variables:
X,Y,Z: 3D coordinates of the current point;PointId: Identification number of the current point among all points of the streamline it belongs to;StreamlineId: Identification number of the streamline which the current point belongs to.
The points might also have attributes or a color assigned to them, in which case, additional variables will be properly created to import them as well. The user can perform statistical analysis on the point cloud and store any new variable that (s)he would deem to be useful as additional column of the tibble. The package also allows to write back the tibble, including all newly created attributes, into the following exporting formats:
You can install the released version of riot from CRAN with:
install.packages("riot")Alternatively you can install the development version of riot from GitHub with:
# install.packages("remotes")
remotes::install_github("astamm/riot")library(riot)Native VTK .vtk and .vtp files
uf_left_vtk <- read_tractogram(system.file(
"extdata",
"UF_left.vtk",
package = "riot"
))
#> Number of data points: 38697
#> Number of streamlines: 2042
#> ✔ The tractogram stored in '/private/var/folders/f3/ycwwj6td205fvwjmcfj53w5r0000gn/T/RtmpVW9OFz/temp_libpath1004323a241a/riot/extdata/UF_left.vtk' has been successfully imported.
uf_left_vtk
#> ℹ Tractogram with 2042 streamlines.
#> ℹ Distribution of the number of sampled points per streamline: 9, 15, 18, 18.9505386875612, 23, and 33.
#> cli-27115-8uf_left_vtp <- read_tractogram(system.file(
"extdata",
"UF_left.vtp",
package = "riot"
))
#> Number of data points: 38697
#> Number of streamlines: 2042
#> ✔ The tractogram stored in '/private/var/folders/f3/ycwwj6td205fvwjmcfj53w5r0000gn/T/RtmpVW9OFz/temp_libpath1004323a241a/riot/extdata/UF_left.vtp' has been successfully imported.
uf_left_vtp
#> ℹ Tractogram with 2042 streamlines.
#> ℹ Distribution of the number of sampled points per streamline: 9, 15, 18, 18.9505386875612, 23, and 33.
#> cli-27115-14medInria .fds files
uf_left_fds <- read_tractogram(system.file(
"extdata",
"UF_left.fds",
package = "riot"
))
#> Number of data points: 38697
#> Number of streamlines: 2042
#> ✔ The tractogram stored in '/private/var/folders/f3/ycwwj6td205fvwjmcfj53w5r0000gn/T/RtmpVW9OFz/temp_libpath1004323a241a/riot/extdata/UF_left.fds' has been successfully imported.
uf_left_fds
#> ℹ Tractogram with 2042 streamlines.
#> ℹ Distribution of the number of sampled points per streamline: 9, 15, 18, 18.9505386875612, 23, and 33.
#> cli-27115-20MRtrix .tck/.tsf files
af_left_tck <- read_tractogram(system.file(
"extdata",
"AF_left.tck",
package = "riot"
))
#> ✔ The tractogram stored in '/private/var/folders/f3/ycwwj6td205fvwjmcfj53w5r0000gn/T/RtmpVW9OFz/temp_libpath1004323a241a/riot/extdata/AF_left.tck' has been successfully imported.
af_left_tck
#> ℹ Tractogram with 5000 streamlines.
#> ℹ Distribution of the number of sampled points per streamline: 8, 23, 28, 28.0602, 33, and 54.
#> cli-27115-26TrackVis .trk files
cc_mid_trk <- read_tractogram(system.file(
"extdata",
"CCMid.trk",
package = "riot"
))
#> ✔ The tractogram stored in '/private/var/folders/f3/ycwwj6td205fvwjmcfj53w5r0000gn/T/RtmpVW9OFz/temp_libpath1004323a241a/riot/extdata/CCMid.trk' has been successfully imported.
cc_mid_trk
#> ℹ Tractogram with 525 streamlines.
#> ℹ Distribution of the number of sampled points per streamline: 29, 189, 224, 214.619047619048, 243, and 270.
#> cli-27115-32Since version 1.2.0, riot no longer bundles VTK source files.
Instead it links against an externally installed
VTK (>= 9.1.0). VTK must be present on the host
before installing the package. Both shared and static VTK builds are
supported; static builds on macOS and Linux must have been compiled with
-fPIC.
At install time, configure (Unix-like) / configure.win (Windows)
search for VTK in the following order:
VTK_DIRenvironment variable (highest priority).- Homebrew — macOS only (
brew install vtk). pkg-config— macOS and Linux.- Well-known system prefix paths (
/usr,/usr/local) — Linux. - Rtools45 / UCRT64 pacman package
mingw-w64-ucrt-x86_64-vtk— Windows.
riot bundles TinyXML-2.
tinyxml2.cpp has been modified to avoid the use of stdout and
printf as per Writing R Extensions manual recommendations because
R has its own input/output mechanism for writing to the console.
The authors would like to thank Tim Schäfer, the author of the freesurferformats package, for his helpful code to read MRtrix and TrackVis tractography file formats.