---
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
<https://tractoverse.github.io/fiber/reference/>.
