--- title: "The fiber API" description: | A technical, exhaustive description of the fiber classes, slots, read-only properties, generics, methods, subsetting semantics, and coercion rules. vignette: > %\VignetteIndexEntry{The fiber API} %\VignetteEngine{quarto::html} %\VignetteEncoding{UTF-8} knitr: opts_chunk: collapse: true comment: '#>' --- ```{r} #| label: setup #| include: false if (!requireNamespace("fiber", quietly = TRUE)) { # R CMD check re-builds vignette outputs in a fresh R process where the # just-installed package is not always on the library path (seen on Windows). # Skip the executable chunks rather than fail the build in that case. knitr::opts_chunk$set(eval = FALSE) } else { library(fiber) } # The dti package (a Suggests) pulls in rgl on load; in headless environments # rgl cannot open a display and emits a warning ('rgl.init' failed / X11 error). # That warning concerns rgl's graphics, not fiber, so we route rgl to its null # device to keep the coercion examples below clean. Sys.setenv(RGL_USE_NULL = "true") ``` This vignette is the reference for **fiber**'s programming interface. It describes every class, slot, read-only property, generic, and method, together with the subsetting ("push-down") semantics and the coercion rules between fiber classes and the `dwiFiber` S4 class of the [dti](https://cran.r-project.org/package=dti) package. For a gentler introduction, see the [getting started](fiber.qmd) vignette. The package defines three [S7](https://rconsortium.github.io/S7/) classes: - [streamline](#class-streamline) - [bundle](#class-bundle) - [bundle_set](#class-bundle_set) and a set of generics and functions: - Constructors & predicates: `streamline()`, `bundle()`, `bundle_set()`, `is_streamline()`, `is_bundle()`, `is_bundle_set()` - Combination: `bind_bundles()`, `bind_bundle_sets()` - Reparametrisation: `reparametrize()` - Shape descriptors: `get_euclidean_length()`, `get_curvilinear_length()`, `get_sinuosity()`, `get_curvature()`, `get_torsion()`, `add_shape_descriptors()` - Distances: `compute_hausdorff_distance()` - Coercion: `as_streamline()`, `as_bundle()`, `as_bundle_set()`, `as_dwifiber()` ## Class: streamline {#class-streamline} A `streamline` represents a single fibre tract as a polyline of 3-D points. It stores three compartments: ### Slots | Slot | Type / shape | Contents | |--------------------|------------------------------------------------|----------| | `@points` | `P x 3` numeric matrix, columns `"X"`, `"Y"`, `"Z"` | The 3-D coordinates of the `P` points along the tract. | | `@point_data` | named list of numeric vectors, each of length `P` | Per-point scalar attributes (e.g. fractional anisotropy). `"X"` / `"Y"` / `"Z"` are **not** allowed here. | | `@streamline_data` | named list of scalars (length 1, any type) | Per-streamline attributes (e.g. mean FA or a character label). | ### Read-only properties | Property | Type | Meaning | |---------------------------|-------------|---------| | `@n_points` | integer | Number of points (`nrow(@points)`). | | `@point_attributes` | character | Names of the entries in `@point_data`. | | `@streamline_attributes` | character | Names of the entries in `@streamline_data`. | ### Construction ```{r} sl <- streamline( points = cbind(X = 0:4, Y = 0:4, Z = 0:4), point_data = list(FA = runif(5)), streamline_data = list(label = "CST") ) sl sl@n_points sl@point_attributes ``` The validator insists that `@points` is a numeric `P x 3` matrix with column names exactly `c("X", "Y", "Z")`, that every `@point_data` entry is a numeric vector of length `P`, and that every `@streamline_data` entry has length 1. ### Method surface `format()` returns a cli-formatted string; `print()` prints it and returns the object invisibly. ## Class: bundle {#class-bundle} A `bundle` is an ordered collection of `streamline` objects, e.g. a tractogram. ### Slots | Slot | Type / shape | Contents | |--------------------|------------------------------------------------|----------| | `@streamlines` | list of `streamline` objects | The individual tracts. | | `@streamline_data` | named list of vectors, each of length `S` | Per-streamline attributes aggregated at the bundle level. Common keys may be lifted here automatically at construction. | | `@bundle_data` | named list of scalars (length 1, any type) | Bundle-level metadata. | ### Read-only properties | Property | Type | Meaning | |--------------------------|------------|---------| | `@n_streamlines` | integer | Number of streamlines. | | `@streamline_attributes` | character | Names of the entries in `@streamline_data`. | | `@bundle_attributes` | character | Names of the entries in `@bundle_data`. | ### Automatic lifting At construction, any `@streamline_data` key present in **all** supplied streamlines is copied into `bundle@streamline_data` as a length-`S` vector, and the key is then not stored redundantly in each streamline. Values supplied explicitly via the `streamline_data` argument take precedence. ```{r} sl1 <- streamline( points = cbind(X = 0:4, Y = 0:4, Z = 0:4), streamline_data = list(mean_FA = 0.6, label = "A") ) sl2 <- streamline( points = cbind(X = 1:3, Y = 1:3, Z = 1:3), streamline_data = list(mean_FA = 0.7, label = "A") ) b <- bundle(streamlines = list(sl1, sl2)) b@streamline_data$mean_FA # c(0.6, 0.7) — lifted automatically b@streamline_attributes # c("mean_FA", "label") ``` The bundle validator requires every element of `@streamlines` to be a `streamline` (with no duplicate names), every `@streamline_data` entry to have length `S`, and every `@bundle_data` entry to have length 1. ### Subsetting and push-down `bundle[[i]]` extracts the `i`-th streamline and **pushes back** the corresponding `bundle@streamline_data` values into the streamline's `@streamline_data`: ```{r} b[[1]]@streamline_data$mean_FA # 0.6 ``` `bundle[i]` returns a new `bundle` with only the selected streamlines, preserving `@bundle_data` and the subset of `@streamline_data`: ```{r} b[1]@streamline_data$mean_FA # c(0.6) b[1]@streamline_data$label # "A" ``` ## Class: bundle_set {#class-bundle_set} A `bundle_set` is a collection of `bundle` objects. It is designed for two closely related use cases: grouping the multiple white-matter bundles of a single subject, or grouping bundles across subjects / sessions in a multi-subject / multi-session study. ### Slots | Slot | Type / shape | Contents | |--------------------|-------------------------------------------|----------| | `@bundles` | list of `bundle` objects (names optional) | One element per bundle (e.g. per white-matter bundle of a subject, or per subject / session). | | `@bundle_data` | named list of vectors, each of length `B` | Per-bundle attributes aggregated at the set level. | | `@bundle_set_data` | named list of scalars (length 1, any type) | Set-level metadata. | ### Read-only properties | Property | Type | Meaning | |---------------------------|------------|---------| | `@n_bundles` | integer | Number of bundles. | | `@bundle_attributes` | character | Names of the entries in `@bundle_data`. | | `@bundle_set_attributes` | character | Names of the entries in `@bundle_set_data`. | ### Names become `id_from_input_names` If the input `bundles` list is named (e.g. `list("sub-01" = b1, "sub-02" = b2)`), the names are transferred into `bundle_set@bundle_data` under the key `id_from_input_names` and the names are then dropped from `@bundles`. ```{r} b_sub01 <- bundle( streamlines = list(sl1), 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@bundle_data$id_from_input_names # c("sub-01", "sub-02") ``` As with bundles, common `@bundle_data` keys are lifted automatically at construction, and the explicit `bundle_data` argument takes precedence. ### Subsetting and push-down `bundle_set[[i]]` extracts the `i`-th bundle and pushes the matching `bundle_set@bundle_data` values into the bundle's `@bundle_data`. `bundle_set[i]` returns a new `bundle_set` with `@bundle_set_data` and the subset of `@bundle_data` preserved. ```{r} bs[["sub-01"]]@bundle_data$subject # "sub-01" (pushed down) bs[1]@bundle_data$subject # "sub-01" ``` ## Predicates | Function | Returns `TRUE` when `x` is ... | |-------------------|--------------------------------| | `is_streamline(x)`| a `streamline` | | `is_bundle(x)` | a `bundle` | | `is_bundle_set(x)`| a `bundle_set` | ```{r} is_streamline(sl) # TRUE is_bundle(sl) # FALSE is_bundle_set(bs) # TRUE ``` ## Combination ### bind_bundles() `bind_bundles(...)` combines any mix of `streamline` and `bundle` objects into a single flat `bundle`. `bundle_data` and `streamline_data` from the first `bundle` argument are preserved by default; pass your own via the `streamline_data` and `bundle_data` arguments to override. Keys present in only some inputs are NA-padded for the others. ```{r} b_all <- bind_bundles(sl1, b) b_all@n_streamlines # 3 ``` ### bind_bundle_sets() `bind_bundle_sets(...)` combines any mix of `bundle` and `bundle_set` objects into a single flat `bundle_set`. Bare `bundle` arguments may be named to carry their name into the resulting set (with `id_from_input_names` populated accordingly), or left unnamed. `bundle_data` from the first `bundle_set` argument is preserved by default; pass your own via `bundle_data` or `bundle_set_data`. ```{r} bs_merged <- bind_bundle_sets("sub-A" = b_sub01, bs) bs_merged@n_bundles # 3 ``` ## Reparametrisation `reparametrize(x, n_points = NULL)` resamples coordinates (and any numeric `@point_data` entries) onto a uniform arc-length grid by linear interpolation. - For a `streamline`, `n_points` defaults to `x@n_points`. - For a `bundle`, it defaults to the rounded mean number of points across its streamlines, and every streamline is resampled to the same grid size. - For a `bundle_set`, each bundle is reparametrized independently (defaulting, per bundle, to the rounded mean across that bundle's streamlines). Non-numeric `@point_data` entries are dropped with a warning (they have no natural arc-length interpolant). `@streamline_data`, `@bundle_data`, and `@bundle_set_data` are preserved unchanged. ```{r} sl_20 <- reparametrize(sl1, n_points = 20L) sl_20@n_points # 20 b_20 <- reparametrize(b, n_points = 20L) b_20[[1]]@n_points # 20 ``` `n_points` must be at least 2. ## Shape descriptors | Function | Returns | |---------------------------------|---------| | `get_euclidean_length(x)` | Straight-line distance between the endpoints (resolution-`P` independent). | | `get_curvilinear_length(x)` | Total arc-length (sum of Euclidean segment lengths). | | `get_sinuosity(x)` | Curvilinear / Euclidean ratio (1 = straight; larger = curvier). | | `get_curvature(x)` | Per-point curvature profile (length `P`), via cubic smoothing splines. | | `get_torsion(x)` | Per-point torsion profile (length `P`), via cubic smoothing splines. | `get_curvature()` and `get_torsion()` are per-point profile descriptors: they fit smoothing splines to each coordinate along the arc-length abscissa, so they need at least four distinct points and are well defined only where the tract is actually curved. On a perfectly straight segment, curvature is identically zero and torsion (which measures out-of-plane twisting) is undefined (`NaN`). The helix below is a good curve to illustrate both, because it is genuinely curved in every direction: ```{r} sl_curve <- streamline( points = cbind( X = cos(seq(0, 2 * pi, length.out = 21)), Y = sin(seq(0, 2 * pi, length.out = 21)), Z = seq(0, 2 * pi, length.out = 21) ) ) # Scalar descriptors are fine on any streamline get_euclidean_length(sl1) get_curvilinear_length(sl1) get_sinuosity(sl1) # Per-point profiles are meaningful on a truly curved tract head(get_curvature(sl_curve)) head(get_torsion(sl_curve)) ``` ### add_shape_descriptors() `add_shape_descriptors(x, descriptors = ...)` is an S7 generic with methods for `streamline`, `bundle`, and `bundle_set`. The default `descriptors` is `c("euclidean_length", "curvilinear_length", "sinuosity", "curvature", "torsion")`. - For a `streamline`, scalar descriptors land in `@streamline_data` and per-point ones in `@point_data`. - For a `bundle`, scalar descriptors are stored as length-`S` vectors in `bundle@streamline_data`; per-point ones (`curvature`, `torsion`) are stored in each individual streamline's `@point_data`. Both are accessible via the subsetting push-down. - For a `bundle_set`, the operation is applied per bundle, preserving `@bundle_data` and `@bundle_set_data`. Unknown descriptor names trigger a structured `cli::cli_warn()` message. Note that `get_curvature()` and `get_torsion()` fit cubic smoothing splines and therefore need a streamline with at least four distinct points (the examples below use 10-point streamlines). ```{r} b_long <- bundle( streamlines = list( streamline(points = cbind(X = 0:9, Y = 0:9, Z = 0:9)), streamline(points = cbind(X = 1:10, Y = 1:10, Z = 1:10)) ) ) b_desc <- add_shape_descriptors(b_long) names(b_desc@streamline_data) names(b_desc[[1]]@point_data) ``` ## Hausdorff distance `compute_hausdorff_distance(x, y = NULL)` computes the symmetric Hausdorff distance. It dispatches on four cases: | `x` | `y` | Returns | |------------|------------|---------| | `streamline` | `streamline` | Scalar: `max(d_H(x→y), d_H(y→x))`. | | `bundle` | `NULL` | `dist` object (size `n`) of all pairwise distances within `x`. | | `bundle` | `streamline` | Numeric vector (length `n`): distance from `y` to each streamline in `x`. | | `bundle` | `bundle` | `dist` object over the concatenation of all streamlines of `x` and `y`. | ```{r} sb <- streamline(points = cbind(X = 0:4, Y = 0:4, Z = 0:4)) sc <- streamline(points = cbind(X = 1:5, Y = 1:5, Z = 1:5)) # streamline x streamline -> scalar compute_hausdorff_distance(sb, sc) # bundle x missing -> dist object bd <- bundle(streamlines = list(sb, sc)) as.matrix(compute_hausdorff_distance(bd)) # bundle x streamline -> vector compute_hausdorff_distance(bd, sb) # bundle x bundle -> combined dist object bd2 <- bundle(streamlines = list(sc)) as.matrix(compute_hausdorff_distance(bd, bd2)) ``` The core pairwise computation is implemented in C++ (via cpp11). Coordinates are coerced to double precision before being passed to the compiled code, so integer-stored `@points` matrices (e.g. built from `X = 1:5`) are handled correctly. Unsupported `x` types (and invalid `y`) produce a clear error via the catch-all method. ## Coercion ### as_streamline() `as_streamline(x)` returns a `streamline`: - `streamline` → returned unchanged (identity). - `bundle` → the sole streamline (errors if the bundle has ≠ 1 streamlines). - `dwiFiber` (from dti) → the single fiber as a `streamline` (errors if multi-fiber; use `as_bundle()` instead). ### as_bundle() `as_bundle(x)` returns a `bundle`: - `streamline` → a single-element `bundle` (lossless). - `bundle` → returned unchanged (identity). - `dwiFiber` → each fiber becomes a `streamline`. Per-point direction vectors (columns 4–6 of `@fibers`) are stored as `@point_data$direction_x/y/z`. Tracking metadata (`method`, `minfa`, `maxangle`) become scalars in `@bundle_data`; vector metadata (`ddim`, `ddim0`, `voxelext`, `orientation`) are expanded into individual scalar entries (e.g. `voxelext_1`, `voxelext_2`, `voxelext_3`). ### as_bundle_set() `as_bundle_set(x)` returns a `bundle_set`: - `bundle_set` → returned unchanged (identity). - `bundle` → a single-element `bundle_set`; the optional `name` argument sets the element name. ### as_dwifiber() `as_dwifiber(x)` converts a `streamline` or `bundle` to the `dwiFiber` S4 class from dti. It requires the `dti` package to be installed. Per-point directions are taken from `@point_data$direction_x/y/z` when present, otherwise estimated from the coordinates via finite differences (forward / backward at the ends, central elsewhere), then unit-normalised. Bundled metadata under `method`, `minfa`, `maxangle`, `level`, and `source` are transferred to the corresponding `dwiFiber` slots when present. ::: {.callout-note} Because dti loads the `rgl` package on startup, calling the coercion functions in an environment without a graphics display can print an rgl warning (e.g. `'rgl.init' failed` or `X11 error`). That warning comes from rgl, not from fiber, and does not affect the conversion. ::: ```{r} if (requireNamespace("dti", quietly = TRUE)) { dfi <- as_dwifiber(bd) class(dfi) # round-trip as_bundle(dfi)@n_streamlines } ``` ## Console output All three classes provide `format()` and `print()` methods that render cli-styled, ANSI-aware summaries (object class, point/bundle counts, and the per-point, per-streamline, per-bundle, and set-level attribute names). `print()` also returns the object invisibly, and `length()`, `[[`, and `[` follow the semantics described above. ## The complete function list For the canonical documentation of every generic, method, argument, and return value, see the package reference at .