fiber

Overview

The fiber package provides three S7 classes — streamline, bundle, and bundle_set — for representing diffusion MRI tractography data in R, together with a concise set of methods:

Function	Description
streamline()	Construct a single streamline
bundle()	Construct a bundle of streamlines
bundle_set()	Construct a set of bundles (multi-subject / multi-session)
is_streamline()	Test if an object is a streamline
is_bundle()	Test if an object is a bundle
is_bundle_set()	Test if an object is a bundle_set
bind_bundles()	Combine streamlines and/or bundles into a single bundle
bind_bundle_sets()	Combine bundles and/or bundle sets into a single bundle set
as_streamline()	Coerce to streamline class
as_bundle()	Coerce to bundle class
as_bundle_set()	Coerce to bundle_set class
as_dwifiber()	Coerce to dwiFiber class from
reparametrize()	Resample onto a uniform arc-length grid
get_euclidean_length()	Straight-line distance between endpoints
get_curvilinear_length()	Total arc-length
get_sinuosity()	Curvilinear / Euclidean length ratio
get_curvature()	Curvature profile or summary scalar
get_torsion()	Torsion profile or summary scalar
add_shape_descriptors()	Add curvature, torsion, and/or sinuosity to @point_data and/or @streamline_data
compute_hausdorff_distance()	Symmetric Hausdorff distance

Classes

A streamline stores:

• @points — a numeric matrix of size $P \times 3$ (the number of points by the three spatial dimensions). The columns must be named "X", "Y", and "Z".
• @point_data — a named list of numeric-only vectors of length $P$ (the number of points). Stores additional per-point attributes (e.g. fractional anisotropy).
• @streamline_data — a named list of per-streamline scalars (length-1 values, any type, e.g. a mean FA or a character label).

A bundle stores:

• @streamlines — a list of streamline objects.
• @streamline_data — a named list of per-streamline vectors of length $S$ (the number of streamlines). Attributes common to all streamlines are lifted here automatically at construction time and pushed back into individual streamlines when subsetting.
• @bundle_data — a named list of bundle-level scalars (length-1 values, any type).

A bundle_set stores:

• @bundles — a list of bundle objects (optionally named, e.g. with subject or session IDs such as "sub-01", in which case names are transferred as a bundle attribute in @bundle_data called id_from_input_list).
• @bundle_data — a named list of per-bundle vectors of length $B$ (the number of bundles). Attributes common to all bundles are lifted here automatically at construction time and pushed back into individual bundles when subsetting.
• @set_data — a named list of set-level scalars (length-1 values, any type).

Installation

You can install the development version of fiber from GitHub with:

# install.packages("pak")
pak::pak("tractoverse/fiber")

Quick start

library(fiber)

# Build a helix streamline (50 points)
t <- seq(0, 2 * pi, length.out = 50)
sl <- streamline(
  points = cbind(X = cos(t), Y = sin(t), Z = t / (2 * pi))
)
sl
#> 
#> ── Object of class `fiber::streamline()` with 50 points. ──
#> 
#> • Point attributes: none
#> • Streamline attributes: none
#> 

# Shape descriptors
get_curvilinear_length(sl)
#> [1] 6.358015
get_sinuosity(sl)
#> [1] 6.358015
head(get_curvature(sl))
#> [1] 1.537338e-05 1.625127e-02 4.592627e-02 8.636675e-02 1.352354e-01
#> [6] 1.906608e-01

# Bundle two streamlines
sl2 <- streamline(
  points = cbind(X = cos(t) * 1.1, Y = sin(t) * 1.1, Z = t / (2 * pi))
)
b <- bundle(list(sl, sl2))
b
#> 
#> ── Object of class `fiber::bundle()` with 2 streamliness and [50–50] points per streamline. ──
#> 
#> • Point attributes: none
#> • Streamline attributes: none
#> • Bundle attributes: none
#> 

# Reparametrize to 20 points each
b20 <- reparametrize(b, n_points = 20L)
b20
#> 
#> ── Object of class `fiber::bundle()` with 2 streamliness and [20–20] points per streamline. ──
#> 
#> • Point attributes: none
#> • Streamline attributes: none
#> • Bundle attributes: none
#> 

# Hausdorff distance
compute_hausdorff_distance(sl, sl2)
#> [1] 0.1

# Multi-subject: collect bundles from two subjects into a bundle_set
b_sub01 <- bundle(
  streamlines = list(sl),
  bundle_data = list(subject = "sub-01")
)
b_sub02 <- bundle(
  streamlines = list(sl2),
  bundle_data = list(subject = "sub-02")
)
bs <- bundle_set(list("sub-01" = b_sub01, "sub-02" = b_sub02))
bs
#> 
#> ── Object of class `fiber::bundle_set()` with 2 bundles and [1–1] streamlines per bundle. ──
#> 
#> • Point attributes: none
#> • Streamline attributes: none
#> • Bundle attributes: "subject" and "id_from_input_names"
#> • Set attributes: none
#> 
bs[["sub-01"]]
#> 
#> ── Object of class `fiber::bundle()` with 1 streamlines and [50–50] points per streamline. ──
#> 
#> • Point attributes: none
#> • Streamline attributes: none
#> • Bundle attributes: "subject" and "id_from_input_names"
#>