R Inputs/Outputs for Tractography • riot

Overview

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 .vtk and .vtp files;
medInria .fds files;
MRtrix .tck/.tsf files; and,
TrackVis .trk files.

The package reads tractography data into S7 objects defined by the fiber package:

streamline — a single fibre tract stored in three typed slots: @points (an $n \times 3$ matrix with columns X, Y, Z), @point_data (a named list of per-point numeric vectors, e.g. diffusion metrics sampled at every point), and @streamline_data (a named list of per-streamline scalar attributes).
bundle — an ordered collection of streamline objects in @streamlines, plus optional bundle-level metadata in @bundle_data.

read_bundle() returns a streamline when the file contains a single tract and a bundle otherwise.

The package also allows to write bundles back into the following exporting formats:

native VTK .vtk and .vtp files; or,
medInria .fds files.

Installation

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")

Example

library(riot)

Native VTK `.vtk` and `.vtp` files

uf_left_vtk <- read_bundle(system.file(
  "extdata",
  "UF_left.vtk",
  package = "riot"
))
uf_left_vtk
#> <bundle [2042 streamlines | 9–33 pts/streamline]>

uf_left_vtp <- read_bundle(system.file(
  "extdata",
  "UF_left.vtp",
  package = "riot"
))
uf_left_vtp
#> <bundle [2042 streamlines | 9–33 pts/streamline]>

medInria `.fds` files

uf_left_fds <- read_bundle(system.file(
  "extdata",
  "UF_left.fds",
  package = "riot"
))
uf_left_fds
#> <bundle [2042 streamlines | 9–33 pts/streamline]>

MRtrix `.tck/.tsf` files

af_left_tck <- read_bundle(system.file(
  "extdata",
  "AF_left.tck",
  package = "riot"
))
af_left_tck
#> <bundle [5000 streamlines | 8–54 pts/streamline]>

TrackVis `.trk` files

cc_mid_trk <- read_bundle(system.file(
  "extdata",
  "CCMid.trk",
  package = "riot"
))
cc_mid_trk
#> <bundle [525 streamlines | 29–270 pts/streamline]>

Dependencies

fiber

riot relies on the fiber package for the S7 classes streamline and bundle that represent tractography data in R, as well as the constructors, predicates, and geometry methods that operate on them. riot does not depend on S7 directly.

VTK

Since version 1.2.0, riot delegates all VTK linkage to the rvtk infrastructure package. VTK is not a system requirement: neither for riot nor for rvtk. At install time, rvtk searches for a pre-installed VTK in the following order:

VTK_DIR environment variable (highest priority).
Homebrew — macOS only (brew install vtk).
pkg-config — macOS and Linux.
Well-known system prefix paths (/usr, /usr/local) — Linux.
Rtools42+ pacman package for the active MSYS2 environment (e.g. mingw-w64-ucrt-x86_64-vtk for UCRT64) — Windows.

If no pre-installed VTK is found, rvtk automatically downloads a pre-compiled static or shared VTK build from its GitHub releases, so no manual VTK installation is ever required.

TinyXML-2

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.

Acknowledgements

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.

riot