
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 (white-matter bundles of a subject, or across subjects / sessions) |
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 the dti package |
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 |
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 white-matter bundle labels such as
"callosum" or with subject or session IDs such as
"sub-01", in which case names are transferred as a
per-bundle attribute in @bundle_data called
id_from_input_names).@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.@bundle_set_data — a named list of set-level
scalars (length-1 values, any type).You can install the development version of fiber from GitHub with:
# install.packages("pak")
pak::pak("tractoverse/fiber")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 streamlines 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 streamlines 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
# Group the bundles of a single subject into a bundle_set, or collect them
# across subjects / sessions. Here each bundle carries a per-bundle label that
# is lifted to the set level (id_from_input_names).
b_cc <- bundle(list(sl)) # e.g. the corpus callosum
b_af <- bundle(list(sl2)) # the arcuate fasciculus
b_cst <- bundle(list(sl)) # the corticospinal tract
# Single subject: all three white-matter bundles of one subject
bs_single <- bundle_set(list("callosum" = b_cc, "arcuate" = b_af, "cst" = b_cst))
bs_single
#>
#> ── Object of class `fiber::bundle_set()` with 3 bundles and [1–1] streamlines per bundle. ──
#>
#> • Point attributes: none
#> • Streamline attributes: none
#> • Bundle attributes: "id_from_input_names"
#> • Set attributes: none
#>
bs_single[["arcuate"]]
#>
#> ── Object of class `fiber::bundle()` with 1 streamline and [50–50] points per streamline. ──
#>
#> • Point attributes: none
#> • Streamline attributes: none
#> • Bundle attributes: "id_from_input_names"
#>
# Multi-subject: the same bundle across two subjects / sessions
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 streamline and [50–50] points per streamline. ──
#>
#> • Point attributes: none
#> • Streamline attributes: none
#> • Bundle attributes: "subject" and "id_from_input_names"
#>