### R Package Installation Error

Source: https://github.com/dynverse/dynwrap/blob/master/revdep/problems.md

This error message signifies that the dynfeature package failed to install. Refer to the specified log file for detailed reasons.

```text
Installation failed.
See ‘/home/rcannood/workspace/vib/dynwrap/revdep/checks/dynfeature/old/dynfeature.Rcheck/00install.out’ for details.
```

--------------------------------

### Run revdepcheck Details

Source: https://github.com/dynverse/dynwrap/blob/master/revdep/problems.md

Use this command to get more detailed information about reverse dependency checks for a specific package.

```r
revdepcheck::revdep_details(, "dynfeature")
```

--------------------------------

### add_root() / add_root_using_expression()

Source: https://context7.com/dynverse/dynwrap/llms.txt

Designates a start milestone (or a start cell, whose closest milestone is used). Flips any edges that point toward the root so the entire network flows away from it. Required before calling `calculate_pseudotime()`.

```APIDOC
## `add_root()` / `add_root_using_expression()` — Root the trajectory

Designates a start milestone (or a start cell, whose closest milestone is used). Flips any edges that point toward the root so the entire network flows away from it. Required before calling `calculate_pseudotime()`.

```r
trajectory <- example_trajectory

# Root by cell ID
trajectory <- add_root(
  trajectory,
  root_cell_id = sample(trajectory$cell_ids, 1)
)
trajectory$root_milestone_id

# Root by milestone ID
trajectory <- add_root(trajectory, root_milestone_id = "milestone_begin")
trajectory$milestone_network  # edge directions updated

# Root using marker gene expression (highest-expressing cells = root)
trajectory <- add_root_using_expression(
  trajectory,
  features_oi       = c("Gene1", "Gene5"),
  expression_source = "expression"
)
```
```

--------------------------------

### Root Trajectory with add_root() and add_root_using_expression()

Source: https://context7.com/dynverse/dynwrap/llms.txt

Designates a start milestone or cell, and flips edges to flow away from the root. Required before calculating pseudotime. Can also use marker gene expression to determine the root.

```r
trajectory <- example_trajectory

# Root by cell ID
trajectory <- add_root(
  trajectory,
  root_cell_id = sample(trajectory$cell_ids, 1)
)
trajectory$root_milestone_id

# Root by milestone ID
trajectory <- add_root(trajectory, root_milestone_id = "milestone_begin")
trajectory$milestone_network  # edge directions updated

# Root using marker gene expression (highest-expressing cells = root)
trajectory <- add_root_using_expression(
  trajectory,
  features_oi       = c("Gene1", "Gene5"),
  expression_source = "expression"
)
```

--------------------------------

### add_prior_information() / generate_prior_information()

Source: https://context7.com/dynverse/dynwrap/llms.txt

Manually attaches or automatically derives prior information (start cells, end cells, cell grouping, important features, time-course data) that can be passed to trajectory inference methods. When the dataset already contains a trajectory and expression, priors are inferred automatically.

```APIDOC
## `add_prior_information()` / `generate_prior_information()` — Add biological prior knowledge

Manually attaches or automatically derives prior information (start cells, end cells, cell grouping, important features, time-course data) that can be passed to trajectory inference methods. When the dataset already contains a trajectory and expression, priors are inferred automatically.

```r
# Manual priors for inference
dataset <- wrap_expression(
  counts     = example_dataset$counts,
  expression = example_dataset$expression
)
dataset <- add_prior_information(
  dataset,
  start_id   = "Cell1",
  end_id     = c("Cell45", "Cell90"),
  features_id = c("Gene3", "Gene7", "Gene12")
)
names(dataset$prior_information)  # "start_id" "end_id" "features_id"
```
```

--------------------------------

### Add prior information to a trajectory

Source: https://context7.com/dynverse/dynwrap/llms.txt

Extracts prior information such as start and end points, and number of branches from a trajectory object. Requires the trajectory object as input.

```R
trajectory <- add_prior_information(example_trajectory, verbose = TRUE)
trajectory$prior_information$start_id
trajectory$prior_information$end_id
trajectory$prior_information$groups_n  # number of branches
```

--------------------------------

### Create Base Data Wrapper with wrap_data()

Source: https://context7.com/dynverse/dynwrap/llms.txt

Use wrap_data() to create the foundational wrapper object. It accepts cell IDs and optionally cell/feature metadata. Ensure the output is a data wrapper using is_data_wrapper().

```r
library(dynwrap)
library(tibble)

# Minimal wrapper from a vector of cell IDs
dataset <- wrap_data(
  id       = "pbmc_3k",
  cell_ids = paste0("Cell", 1:200)
)

# With optional cell and feature metadata
cell_info <- tibble(
  cell_id   = paste0("Cell", 1:200),
  condition = rep(c("ctrl", "treat"), 100)
)
feature_info <- tibble(feature_id = paste0("Gene", 1:50))

dataset <- wrap_data(
  id           = "pbmc_3k",
  cell_ids     = paste0("Cell", 1:200),
  cell_info    = cell_info,
  feature_ids  = paste0("Gene", 1:50),
  feature_info = feature_info
)

is_data_wrapper(dataset)  # TRUE
dataset$cell_ids[1:5]     # "Cell1" "Cell2" "Cell3" "Cell4" "Cell5"
```

--------------------------------

### Create Wrapper from Expression Matrices with wrap_expression()

Source: https://context7.com/dynverse/dynwrap/llms.txt

Use wrap_expression() as a convenience constructor to combine wrap_data() and add_expression(). It derives cell and feature IDs from matrix names and accepts sparse or dense matrices. Check the dimensions and class of the resulting expression matrix.

```r
library(Matrix)

# Simulate sparse count and normalised expression matrices
set.seed(42)
counts     <- Matrix(matrix(rpois(200 * 50, 2), 200, 50), sparse = TRUE)
expression <- log1p(counts)
rownames(counts) <- rownames(expression) <- paste0("Cell", 1:200)
colnames(counts) <- colnames(expression) <- paste0("Gene", 1:50)

# Optionally include RNA-velocity projected expression
expression_future <- expression * 1.05

dataset <- wrap_expression(
  id                = "my_dataset",
  counts            = counts,
  expression        = expression,
  expression_future = expression_future
)

dim(dataset$expression)        # 200 x 50
class(dataset$expression)      # "dgCMatrix"
dataset$expression[1:3, 1:4]
```

--------------------------------

### create_ti_method_r

Source: https://context7.com/dynverse/dynwrap/llms.txt

Packages an R function as a standardised dynwrap TI method.

```APIDOC
## create_ti_method_r()

### Description
Wraps an arbitrary R function into the standardised dynwrap `ti_*` method format, complete with parameter schema (via `dynparam`), required package declarations, and metadata. The resulting method object can be passed directly to `infer_trajectory()`.

### Example
```r
library(dynparam)

definition <- definition(
  method     = def_method(id = "pca_linear"),
  parameters = def_parameters(
    integer_parameter(
      id           = "component",
      default      = 1,
      distribution = uniform_distribution(1, 10),
      description  = "PCA component to use as pseudotime axis"
    )
  ),
  wrapper = def_wrapper(
    input_required = "expression",
    input_optional = "start_id"
  )
)

run_fun <- function(expression, priors, parameters, seed, verbose) {
  set.seed(seed)
  pca <- prcomp(as.matrix(expression), scale. = TRUE)
  pt  <- pca$x[, parameters$component]

  if (!is.null(priors$start_id) && mean(pt[priors$start_id]) > 0) {
    pt <- -pt
  }

  wrap_data(cell_ids = rownames(expression)) |>
    add_linear_trajectory(pseudotime = pt)
}

method     <- create_ti_method_r(definition, run_fun, package_loaded = "stats")
trajectory <- infer_trajectory(example_dataset, method(), verbose = TRUE)
```
```

--------------------------------

### wrap_expression()

Source: https://context7.com/dynverse/dynwrap/llms.txt

A convenience constructor that combines `wrap_data()` and `add_expression()` to create a wrapper directly from expression matrices.

```APIDOC
## wrap_expression() — Create a wrapper directly from expression matrices

Convenience constructor that combines `wrap_data()` and `add_expression()` in one step. Derives cell and feature IDs from matrix row/column names. Accepts sparse (`dgCMatrix`) or dense matrices.

### Parameters

- **id** (string) - Required - A unique identifier for the dataset.
- **counts** (matrix) - Optional - A matrix of raw counts.
- **expression** (matrix) - Required - A matrix of normalised expression values.
- **expression_future** (matrix) - Optional - A matrix of RNA-velocity projected expression values.

### Request Example
```r
library(Matrix)

# Simulate sparse count and normalised expression matrices
set.seed(42)
counts     <- Matrix(matrix(rpois(200 * 50, 2), 200, 50), sparse = TRUE)
expression <- log1p(counts)
rownames(counts) <- rownames(expression) <- paste0("Cell", 1:200)
colnames(counts) <- colnames(expression) <- paste0("Gene", 1:50)

# Optionally include RNA-velocity projected expression
expression_future <- expression * 1.05

dataset <- wrap_expression(
  id                = "my_dataset",
  counts            = counts,
  expression        = expression,
  expression_future = expression_future
)
```

### Response

Returns a list of class `dynwrap::data_wrapper` with expression data attached.

### Response Example
```r
dim(dataset$expression)        # 200 x 50
class(dataset$expression)      # "dgCMatrix"
dataset$expression[1:3, 1:4]
```
```

--------------------------------

### wrap_data()

Source: https://context7.com/dynverse/dynwrap/llms.txt

Creates the foundational wrapper object for downstream functions. It accepts cell IDs and optionally cell/feature metadata.

```APIDOC
## wrap_data() — Create a base data wrapper

Creates the foundational wrapper object that all downstream `add_*` functions build upon. Accepts cell IDs (and optionally feature IDs plus metadata) and returns a list of class `dynwrap::data_wrapper`.

### Parameters

- **id** (string) - Required - A unique identifier for the dataset.
- **cell_ids** (vector of strings) - Required - A vector of cell identifiers.
- **cell_info** (data.frame or tibble) - Optional - A data frame containing metadata for each cell.
- **feature_ids** (vector of strings) - Optional - A vector of feature identifiers.
- **feature_info** (data.frame or tibble) - Optional - A data frame containing metadata for each feature.

### Request Example
```r
library(dynwrap)
library(tibble)

# Minimal wrapper from a vector of cell IDs
dataset <- wrap_data(
  id       = "pbmc_3k",
  cell_ids = paste0("Cell", 1:200)
)

# With optional cell and feature metadata
cell_info <- tibble(
  cell_id   = paste0("Cell", 1:200),
  condition = rep(c("ctrl", "treat"), 100)
)
feature_info <- tibble(feature_id = paste0("Gene", 1:50))

dataset <- wrap_data(
  id           = "pbmc_3k",
  cell_ids     = paste0("Cell", 1:200),
  cell_info    = cell_info,
  feature_ids  = paste0("Gene", 1:50),
  feature_info = feature_info
)
```

### Response

Returns a list of class `dynwrap::data_wrapper`.

### Response Example
```r
is_data_wrapper(dataset)  # TRUE
dataset$cell_ids[1:5]     # "Cell1" "Cell2" "Cell3" "Cell4" "Cell5"
```
```

--------------------------------

### Compute Pseudotime with add_pseudotime()

Source: https://context7.com/dynverse/dynwrap/llms.txt

Calculates geodesic distances from the root to each cell along the trajectory. Requires a rooted trajectory. Can compute automatically or accept custom pseudotime values.

```r
trajectory <- example_trajectory |> 
  add_root(root_milestone_id = "milestone_begin")

# Calculate automatically
trajectory <- add_pseudotime(trajectory)
summary(trajectory$pseudotime)
# Min.  1st Qu.  Median  Mean  3rd Qu.  Max.
# 0.00   0.18   0.43   0.45   0.71   1.00

# Or supply your own
custom_pt <- setNames(runif(length(trajectory$cell_ids)), trajectory$cell_ids)
trajectory <- add_pseudotime(trajectory, pseudotime = custom_pt)
```

--------------------------------

### Package an R function as a TI method

Source: https://context7.com/dynverse/dynwrap/llms.txt

Wraps an R function into the standardized dynwrap `ti_*` method format, including parameter schema, package declarations, and metadata. The resulting method can be used with `infer_trajectory()`. Requires `dynparam` library.

```R
library(dynparam)

definition <- definition(
  method     = def_method(id = "pca_linear"),
  parameters = def_parameters(
    integer_parameter(
      id           = "component",
      default      = 1,
      distribution = uniform_distribution(1, 10),
      description  = "PCA component to use as pseudotime axis"
    )
  ),
  wrapper = def_wrapper(
    input_required = "expression",
    input_optional = "start_id"
  )
)

run_fun <- function(expression, priors, parameters, seed, verbose) {
  set.seed(seed)
  pca <- prcomp(as.matrix(expression), scale. = TRUE)
  pt  <- pca$x[, parameters$component]

  if (!is.null(priors$start_id) && mean(pt[priors$start_id]) > 0) {
    pt <- -pt
  }

  wrap_data(cell_ids = rownames(expression)) |>
    add_linear_trajectory(pseudotime = pt)
}

method     <- create_ti_method_r(definition, run_fun, package_loaded = "stats")
trajectory <- infer_trajectory(example_dataset, method(), verbose = TRUE)
head(trajectory$progressions)
```

--------------------------------

### Construct a cyclic trajectory with add_cyclic_trajectory

Source: https://context7.com/dynverse/dynwrap/llms.txt

Use `add_cyclic_trajectory` for periodic processes, dividing pseudotime [0, 1] into three segments on a cycle. `do_scale_minmax` defaults to `FALSE`.

```r
dataset <- wrap_data(cell_ids = paste0("Cell", 1:60))

pseudotime <- tibble(
  cell_id   = dataset$cell_ids,
  pseudotime = seq(0, 1, length.out = 60)
)

trajectory <- add_cyclic_trajectory(
  dataset,
  pseudotime      = pseudotime,
  directed        = TRUE,
  do_scale_minmax = FALSE
)

trajectory$milestone_network
#  from  to  length  directed
#  A     B    1      TRUE
#  B     C    1      TRUE
#  C     A    1      TRUE
```

--------------------------------

### Construct a linear trajectory with add_linear_trajectory

Source: https://context7.com/dynverse/dynwrap/llms.txt

Use `add_linear_trajectory` to create a linear trajectory from pseudotime. Pseudotime is automatically scaled to [0, 1] by default. Accepts a named numeric vector for pseudotime.

```r
dataset <- wrap_data(cell_ids = paste0("Cell", 1:50))

# Named numeric vector
set.seed(7)
pseudotime <- setNames(runif(50), dataset$cell_ids)

trajectory <- add_linear_trajectory(
  dataset,
  pseudotime      = pseudotime,
  directed        = TRUE,
  do_scale_minmax = TRUE
)

trajectory$milestone_network
# from             to  length directed
# milestone_begin  milestone_end  1  TRUE
range(trajectory$pseudotime)  # 0 1
```

--------------------------------

### add_trajectory()

Source: https://context7.com/dynverse/dynwrap/llms.txt

Attaches a full milestone-network trajectory by accepting an arbitrary milestone network and either progressions or milestone percentages, then validating all inputs.

```APIDOC
## add_trajectory() — Attach a full milestone-network trajectory

The most general trajectory constructor. Accepts an arbitrary milestone network (data frame with `from`, `to`, `length`, `directed`) plus either `progressions` (cell-level edge positions) or `milestone_percentages` (cell-level milestone proximities), and validates all inputs.

```r
library(dplyr)
library(tibble)

dataset <- wrap_data(cell_ids = letters)  # 26 cells a–z

milestone_network <- tribble(
  ~from, ~to, ~length, ~directed,
  "M1",  "M2",    1,    TRUE,
  "M2",  "M3",    2,    TRUE,
  "M2",  "M4",    1,    TRUE
)

divergence_regions <- tribble(
  ~divergence_id, ~milestone_id, ~is_start,
  "div1",         "M2",          TRUE,
  "div1",         "M3",          FALSE,
  "div1",         "M4",          FALSE
)

set.seed(1)
progressions <- milestone_network |
  sample_n(length(dataset$cell_ids), replace = TRUE, weight = length) |
  mutate(
    cell_id    = dataset$cell_ids,
    percentage = runif(n())
  ) |
  select(cell_id, from, to, percentage)

trajectory <- add_trajectory(
  dataset,
  milestone_network  = milestone_network,
  divergence_regions = divergence_regions,
  progressions       = progressions
)

trajectory$trajectory_type        # e.g. "bifurcation"
head(trajectory$milestone_network)
head(trajectory$progressions)
```
```

--------------------------------

### add_linear_trajectory()

Source: https://context7.com/dynverse/dynwrap/llms.txt

Constructs a linear trajectory from pseudotime values, wrapping them into the two-milestone linear form `milestone_begin → milestone_end`. Pseudotime is automatically scaled to [0, 1] unless `do_scale_minmax = FALSE`.

```APIDOC
## add_linear_trajectory() — Construct a linear trajectory from pseudotime

Wraps pseudotime values into the two-milestone linear form `milestone_begin → milestone_end`. Pseudotime is automatically scaled to [0, 1] unless `do_scale_minmax = FALSE`.

```r
dataset <- wrap_data(cell_ids = paste0("Cell", 1:50))

# Named numeric vector
set.seed(7)
pseudotime <- setNames(runif(50), dataset$cell_ids)

trajectory <- add_linear_trajectory(
  dataset,
  pseudotime      = pseudotime,
  directed        = TRUE,
  do_scale_minmax = TRUE
)

trajectory$milestone_network
# from             to  length directed
# milestone_begin  milestone_end  1  TRUE
range(trajectory$pseudotime)  # 0 1
```
```

--------------------------------

### Construct a general milestone network trajectory with add_trajectory

Source: https://context7.com/dynverse/dynwrap/llms.txt

Use `add_trajectory` to create a trajectory from a detailed milestone network and cell progressions. Ensure `dataset`, `milestone_network`, and `progressions` are correctly formatted. This function validates all inputs.

```r
library(dplyr)
library(tibble)

dataset <- wrap_data(cell_ids = letters)  # 26 cells a–z

milestone_network <- tribble(
  ~from, ~to, ~length, ~directed,
  "M1",  "M2",    1,    TRUE,
  "M2",  "M3",    2,    TRUE,
  "M2",  "M4",    1,    TRUE
)

divergence_regions <- tribble(
  ~divergence_id, ~milestone_id, ~is_start,
  "div1",         "M2",          TRUE,
  "div1",         "M3",          FALSE,
  "div1",         "M4",          FALSE
)

set.seed(1)
progressions <- milestone_network |
  sample_n(length(dataset$cell_ids), replace = TRUE, weight = length) |
  mutate(
    cell_id    = dataset$cell_ids,
    percentage = runif(n())
  ) |
  select(cell_id, from, to, percentage)

trajectory <- add_trajectory(
  dataset,
  milestone_network  = milestone_network,
  divergence_regions = divergence_regions,
  progressions       = progressions
)

trajectory$trajectory_type        # e.g. "bifurcation"
head(trajectory$milestone_network)
head(trajectory$progressions)
```

--------------------------------

### Construct a trajectory from a branch network with add_branch_trajectory

Source: https://context7.com/dynverse/dynwrap/llms.txt

Use `add_branch_trajectory` to convert a branch network representation into a standard milestone network. Requires `branch_network`, `branches`, and `branch_progressions`.

```r
dataset <- wrap_data(cell_ids = letters)

branch_network <- tibble(from = c("trunk", "trunk"), to = c("arm1", "arm2"))
branches       <- tibble(branch_id = c("trunk","arm1","arm2"), length = 1, directed = TRUE)

set.seed(3)
branch_progressions <- tibble(
  cell_id    = dataset$cell_ids,
  branch_id  = sample(c("trunk","arm1","arm2"), 26, replace = TRUE),
  percentage = runif(26)
)

trajectory <- add_branch_trajectory(
  dataset,
  branch_network      = branch_network,
  branches            = branches,
  branch_progressions = branch_progressions
)

trajectory$trajectory_type  # "bifurcation" or "linear" depending on topology
```

--------------------------------

### Attach Expression Data with add_expression()

Source: https://context7.com/dynverse/dynwrap/llms.txt

Use add_expression() to add count and normalised expression matrices to an existing data wrapper. Matrices are internally coerced to dgCMatrix format. Verify the addition using is_wrapper_with_expression().

```r
dataset <- wrap_data(cell_ids = paste0("Cell", 1:100))

counts     <- matrix(rpois(100 * 30, 3), nrow = 100)
rownames(counts) <- paste0("Cell", 1:100)
colnames(counts) <- paste0("Gene", 1:30)
expression <- log1p(counts)
rownames(expression) <- rownames(counts)
colnames(expression) <- colnames(counts)

dataset <- add_expression(
  dataset,
  counts     = counts,
  expression = expression
)

is_wrapper_with_expression(dataset)  # TRUE
str(dataset$counts)                  # Formal class 'dgCMatrix'
```

--------------------------------

### add_pseudotime() / calculate_pseudotime()

Source: https://context7.com/dynverse/dynwrap/llms.txt

Calculates geodesic distances from the root milestone to every cell along the trajectory topology. Requires the trajectory to be rooted (`add_root()`). Returns a named numeric vector stored as `trajectory$pseudotime`.

```APIDOC
## `add_pseudotime()` / `calculate_pseudotime()` — Compute pseudotime

Calculates geodesic distances from the root milestone to every cell along the trajectory topology. Requires the trajectory to be rooted (`add_root()`). Returns a named numeric vector stored as `trajectory$pseudotime`.

```r
trajectory <- example_trajectory |>
  add_root(root_milestone_id = "milestone_begin")

# Calculate automatically
trajectory <- add_pseudotime(trajectory)
summary(trajectory$pseudotime)
# Min.  1st Qu.  Median  Mean  3rd Qu.  Max.
# 0.00   0.18   0.43   0.45   0.71   1.00

# Or supply your own
custom_pt <- setNames(runif(length(trajectory$cell_ids)), trajectory$cell_ids)
trajectory <- add_pseudotime(trajectory, pseudotime = custom_pt)
```
```

--------------------------------

### add_cyclic_trajectory()

Source: https://context7.com/dynverse/dynwrap/llms.txt

Constructs a cyclic (circular) trajectory by dividing pseudotime [0, 1] into three equal segments placed on a cycle `A → B → C → A`. Suitable for cell-cycle or other periodic processes.

```APIDOC
## add_cyclic_trajectory() — Construct a cyclic (circular) trajectory

Divides pseudotime [0, 1] into three equal segments placed on a cycle `A → B → C → A`. Suitable for cell-cycle or other periodic processes.

```r
dataset <- wrap_data(cell_ids = paste0("Cell", 1:60))

pseudotime <- tibble(
  cell_id   = dataset$cell_ids,
  pseudotime = seq(0, 1, length.out = 60)
)

trajectory <- add_cyclic_trajectory(
  dataset,
  pseudotime      = pseudotime,
  directed        = TRUE,
  do_scale_minmax = FALSE
)

trajectory$milestone_network
#  from  to  length  directed
#  A     B    1      TRUE
#  B     C    1      TRUE
#  C     A    1      TRUE
```
```

--------------------------------

### add_branch_trajectory()

Source: https://context7.com/dynverse/dynwrap/llms.txt

Constructs a trajectory from a branch network by accepting a higher-level branch representation (`branch_network`, `branches`, `branch_progressions`) and internally converting it into the standard milestone-network format.

```APIDOC
## add_branch_trajectory() — Construct a trajectory from a branch network

Accepts a higher-level branch representation (`branch_network`, `branches`, `branch_progressions`) and internally converts it into the standard milestone-network format by assigning start and end milestones to each branch and merging shared endpoints.

```r
dataset <- wrap_data(cell_ids = letters)

branch_network <- tibble(from = c("trunk", "trunk"), to = c("arm1", "arm2"))
branches       <- tibble(branch_id = c("trunk","arm1","arm2"), length = 1, directed = TRUE)

set.seed(3)
branch_progressions <- tibble(
  cell_id    = dataset$cell_ids,
  branch_id  = sample(c("trunk","arm1","arm2"), 26, replace = TRUE),
  percentage = runif(26)
)

trajectory <- add_branch_trajectory(
  dataset,
  branch_network      = branch_network,
  branches            = branches,
  branch_progressions = branch_progressions
)

trajectory$trajectory_type  # "bifurcation" or "linear" depending on topology
```
```

--------------------------------

### Infer trajectory from a dataset

Source: https://context7.com/dynverse/dynwrap/llms.txt

Executes one or more trajectory inference methods on datasets. Handles in-memory R objects, method name strings, or container paths. `infer_trajectory()` returns a single trajectory, while `infer_trajectories()` returns a tibble for multiple dataset/method combinations. Ensure dataset and method objects are correctly prepared.

```R
# Single dataset, single in-memory method
dataset   <- example_dataset
method    <- get_ti_methods(as_tibble = FALSE)[[1]]$fun
trajectory <- infer_trajectory(dataset, method(), seed = 42, verbose = FALSE)

head(trajectory$milestone_network)
head(trajectory$progressions)

# Multiple datasets × methods (returns a tibble)
results <- infer_trajectories(
  dataset  = list(example_dataset, example_dataset),
  method   = list(method(), method()),
  verbose  = FALSE
)
results[, c("dataset_id","method_id","model")]
# Access individual trajectories
results$model[[1]]$trajectory_type
```

--------------------------------

### Add Prior Information with add_prior_information()

Source: https://context7.com/dynverse/dynwrap/llms.txt

Manually attaches or automatically derives prior biological knowledge such as start/end cells, groupings, and important features for trajectory inference methods. Priors are inferred automatically if a dataset contains a trajectory and expression.

```r
# Manual priors for inference
dataset <- wrap_expression(
  counts     = example_dataset$counts,
  expression = example_dataset$expression
)
dataset <- add_prior_information(
  dataset,
  start_id   = "Cell1",
  end_id     = c("Cell45", "Cell90"),
  features_id = c("Gene3", "Gene7", "Gene12")
)
names(dataset$prior_information)  # "start_id" "end_id" "features_id"
```

--------------------------------

### Calculate Geodesic Distances with calculate_geodesic_distances()

Source: https://context7.com/dynverse/dynwrap/llms.txt

Computes shortest-path distances between waypoint cells and all other cells, respecting trajectory topology and directionality. Returns a matrix of distances.

```r
# All-vs-all geodesic distances
geo <- calculate_geodesic_distances(example_trajectory)
geo[1:4, 1:4]

# Directed distances from specific waypoint cells
waypoints <- example_trajectory$cell_ids[1:5]
geo_dir   <- calculate_geodesic_distances(
  example_trajectory,
  waypoint_cells = waypoints,
  directed       = TRUE
)
dim(geo_dir)          # 5 × n_cells
is.infinite(geo_dir)  # TRUE where cell is unreachable from that waypoint
```

--------------------------------

### R Code Dependency Check Note

Source: https://github.com/dynverse/dynwrap/blob/master/revdep/problems.md

This note indicates an issue with the 'Imports' field in the R package's DESCRIPTION file, where 'magrittr' is declared but not used. Ensure all imported packages are utilized.

```text
Namespace in Imports field not imported from: ‘magrittr’
  All declared Imports should be used.
```

--------------------------------

### add_expression()

Source: https://context7.com/dynverse/dynwrap/llms.txt

Attaches count and normalised expression matrices (and optionally RNA-velocity projected expression) to an existing data wrapper.

```APIDOC
## add_expression() — Attach expression data to an existing wrapper

Adds count and normalised expression matrices (and optionally RNA-velocity projected expression) to any existing data wrapper. Matrices are coerced to sparse `dgCMatrix` format internally.

### Parameters

- **dataset** (list) - Required - The existing data wrapper object.
- **counts** (matrix) - Optional - A matrix of raw counts.
- **expression** (matrix) - Required - A matrix of normalised expression values.
- **expression_future** (matrix) - Optional - A matrix of RNA-velocity projected expression values.

### Request Example
```r
dataset <- wrap_data(cell_ids = paste0("Cell", 1:100))

counts     <- matrix(rpois(100 * 30, 3), nrow = 100)
rownames(counts) <- paste0("Cell", 1:100)
colnames(counts) <- paste0("Gene", 1:30)
expression <- log1p(counts)
rownames(expression) <- rownames(counts)
colnames(expression) <- colnames(counts)

dataset <- add_expression(
  dataset,
  counts     = counts,
  expression = expression
)
```

### Response

Returns the updated data wrapper object with expression data attached.

### Response Example
```r
is_wrapper_with_expression(dataset)  # TRUE
str(dataset$counts)                  # Formal class 'dgCMatrix'
```
```

--------------------------------

### Construct a trajectory from cell cluster assignments with add_cluster_graph

Source: https://context7.com/dynverse/dynwrap/llms.txt

Use `add_cluster_graph` to place cells on a milestone network based on cluster assignments. Useful when TI methods provide clustering and a coarse network. `explicit_splits = TRUE` adds explicit split nodes.

```r
library(tibble)

dataset <- wrap_data(cell_ids = letters)

milestone_network <- tibble(
  from     = c("S", "S", "A"),
  to       = c("A", "B", "C"),
  directed = TRUE,
  length   = 1
)

set.seed(9)
grouping <- sample(c("S","A","B","C"), 26, replace = TRUE)
names(grouping) <- dataset$cell_ids

trajectory <- add_cluster_graph(
  dataset,
  milestone_network = milestone_network,
  grouping          = grouping,
  explicit_splits   = TRUE   # adds explicit split node
)

head(trajectory$progressions)
```

--------------------------------

### infer_trajectory / infer_trajectories

Source: https://context7.com/dynverse/dynwrap/llms.txt

Executes one or more trajectory inference methods on one or more datasets.

```APIDOC
## infer_trajectory() / infer_trajectories()

### Description
Executes one or more trajectory inference methods on one or more datasets. Handles method dispatch from in-memory R objects, method name strings, or Docker/Singularity container paths. `infer_trajectory()` returns a single trajectory; `infer_trajectories()` returns a tibble with one row per dataset × method combination.

### Single dataset, single in-memory method
```r
dataset   <- example_dataset
method    <- get_ti_methods(as_tibble = FALSE)[[1]]$fun
trajectory <- infer_trajectory(dataset, method(), seed = 42, verbose = FALSE)
```

### Multiple datasets × methods (returns a tibble)
```r
results <- infer_trajectories(
  dataset  = list(example_dataset, example_dataset),
  method   = list(method(), method()),
  verbose  = FALSE
)
```
```

--------------------------------

### Simplify trajectory by removing redundant milestones

Source: https://context7.com/dynverse/dynwrap/llms.txt

Strips out intermediate milestones that are neither leaves nor branching points, simplifying the trajectory network. Cell positions are preserved. Useful for cleaning up trajectories with excessive nodes. Requires a tibble for milestone network and progressions.

```R
# Build a trajectory with an unnecessary intermediate milestone
dataset <- wrap_data(cell_ids = letters)
mn <- tibble::tribble(
  ~from, ~to, ~length, ~directed,
  "A",   "B",      1,    FALSE,
  "B",   "C",      1,    FALSE,   # B is a passthrough — will be removed
  "C",   "D",      1,    FALSE
)
set.seed(2)
prog <- mn |>
  dplyr::sample_n(26, replace = TRUE, weight = length) |>
  dplyr::mutate(cell_id = letters, percentage = runif(26)) |>
  dplyr::select(cell_id, from, to, percentage)

traj      <- add_trajectory(dataset, milestone_network = mn, progressions = prog)
traj_simp <- simplify_trajectory(traj)
traj_simp$milestone_network  # now only A → D (B and C merged)
```

--------------------------------

### label_milestones / label_milestones_markers

Source: https://context7.com/dynverse/dynwrap/llms.txt

Assigns human-readable labels to milestones either manually or automatically by matching expression profiles against marker genes.

```APIDOC
## label_milestones() / label_milestones_markers()

### Description
Assigns human-readable labels to milestones either manually (by name) or automatically by matching the average expression profile of nearby cells against a dictionary of marker genes.

### Manual labelling
```r
trajectory <- label_milestones(
  trajectory,
  labelling = c("milestone_begin" = "Progenitor", "milestone_end" = "Mature")
)
```

### Marker-gene-based labelling
```r
trajectory <- label_milestones_markers(
  trajectory,
  markers = list(
    Progenitor = c("Gene1", "Gene2"),
    Mature     = c("Gene8", "Gene9")
  ),
  n_nearest_cells = 30
)
```
```

--------------------------------

### add_cluster_graph()

Source: https://context7.com/dynverse/dynwrap/llms.txt

Constructs a trajectory from cell cluster assignments by placing cells on the edges of a user-supplied milestone network according to their cluster assignment. Useful when a TI method outputs a clustering and a coarse network rather than continuous progressions.

```APIDOC
## add_cluster_graph() — Construct a trajectory from cell cluster assignments

Places cells on the edges of a user-supplied milestone network according to their cluster assignment. Useful when a TI method outputs a clustering and a coarse network rather than continuous progressions.

```r
library(tibble)

dataset <- wrap_data(cell_ids = letters)

milestone_network <- tibble(
  from     = c("S", "S", "A"),
  to       = c("A", "B", "C"),
  directed = TRUE,
  length   = 1
)

set.seed(9)
grouping <- sample(c("S","A","B","C"), 26, replace = TRUE)
names(grouping) <- dataset$cell_ids

trajectory <- add_cluster_graph(
  dataset,
  milestone_network = milestone_network,
  grouping          = grouping,
  explicit_splits   = TRUE   # adds explicit split node
)

head(trajectory$progressions)
```
```

--------------------------------

### simplify_trajectory

Source: https://context7.com/dynverse/dynwrap/llms.txt

Removes redundant intermediate milestones from a trajectory, preserving cell positions.

```APIDOC
## simplify_trajectory()

### Description
Strips out milestones that are neither leaves nor branching points (e.g. collapses `A → B → C` to `A → C`). Cell positions within the trajectory are preserved exactly. Useful to clean up method output with excessive intermediate nodes.

### Example
```r
# Build a trajectory with an unnecessary intermediate milestone
dataset <- wrap_data(cell_ids = letters)
mn <- tibble::tribble(
  ~from, ~to, ~length, ~directed,
  "A",   "B",      1,    FALSE,
  "B",   "C",      1,    FALSE,   # B is a passthrough — will be removed
  "C",   "D",      1,    FALSE
)
set.seed(2)
prog <- mn |> 
  dplyr::sample_n(26, replace = TRUE, weight = length) |> 
  dplyr::mutate(cell_id = letters, percentage = runif(26)) |> 
  dplyr::select(cell_id, from, to, percentage)

traj      <- add_trajectory(dataset, milestone_network = mn, progressions = prog)
traj_simp <- simplify_trajectory(traj)
```
```

--------------------------------

### add_grouping()

Source: https://context7.com/dynverse/dynwrap/llms.txt

Associates each cell with a group identifier (e.g. cell type, cluster label). The grouping can be a named character vector or a two-column data frame (`cell_id`, `group_id`).

```APIDOC
## `add_grouping()` — Attach a cell grouping

Associates each cell with a group identifier (e.g. cell type, cluster label). The grouping can be a named character vector or a two-column data frame (`cell_id`, `group_id`).

```r
dataset <- example_dataset

set.seed(5)
grouping <- sample(c("typeA","typeB","typeC"),
                   length(dataset$cell_ids), replace = TRUE)
names(grouping) <- dataset$cell_ids

dataset <- add_grouping(dataset, grouping)

head(dataset$grouping)
is_wrapper_with_grouping(dataset)  # TRUE

# Derive groupings from an existing trajectory
edge_groups      <- group_onto_trajectory_edges(example_trajectory)
milestone_groups <- group_onto_nearest_milestones(example_trajectory)
head(edge_groups)      # "M1->M2" per cell
head(milestone_groups) # nearest milestone per cell
```
```

--------------------------------

### add_dimred()

Source: https://context7.com/dynverse/dynwrap/llms.txt

Attaches a 2-D (or higher) embedding to the dataset. Accepts a pre-computed matrix, a data frame with a `cell_id` column, or a function (e.g. from `dyndimred`). If the dataset already contains a trajectory, the milestone positions and trajectory segments are automatically projected into the embedding.

```APIDOC
## `add_dimred()` — Add or compute a dimensionality reduction

Attaches a 2-D (or higher) embedding to the dataset. Accepts a pre-computed matrix, a data frame with a `cell_id` column, or a function (e.g. from `dyndimred`). If the dataset already contains a trajectory, the milestone positions and trajectory segments are automatically projected into the embedding.

```r
if (requireNamespace("dyndimred", quietly = TRUE)) {
  dataset <- example_dataset  # bundled example with expression + trajectory

  dataset <- add_dimred(
    dataset,
    dimred             = dyndimred::dimred_landmark_mds,
    project_trajectory = TRUE,
    expression_source  = "expression"
  )

  head(dataset$dimred)            # cells × comp_1, comp_2
  head(dataset$dimred_milestones) # milestones in the same space
}

# Alternatively pass a pre-computed matrix
dimred_mat <- matrix(rnorm(length(example_dataset$cell_ids) * 2),
                     nrow = length(example_dataset$cell_ids))
rownames(dimred_mat) <- example_dataset$cell_ids

example_dataset <- add_dimred(example_dataset, dimred = dimred_mat)
```
```

--------------------------------

### calculate_geodesic_distances()

Source: https://context7.com/dynverse/dynwrap/llms.txt

Computes shortest-path distances between waypoint cells (or all cells) and every other cell, respecting edge lengths and optional directionality. Returns a `waypoints × cells` numeric matrix.

```APIDOC
## `calculate_geodesic_distances()` — Pairwise geodesic distances along the trajectory

Computes shortest-path distances between waypoint cells (or all cells) and every other cell, respecting edge lengths and optional directionality. Returns a `waypoints × cells` numeric matrix.

```r
# All-vs-all geodesic distances
geo <- calculate_geodesic_distances(example_trajectory)
geo[1:4, 1:4]

# Directed distances from specific waypoint cells
waypoints <- example_trajectory$cell_ids[1:5]
geo_dir   <- calculate_geodesic_distances(
  example_trajectory,
  waypoint_cells = waypoints,
  directed       = TRUE
)
dim(geo_dir)          # 5 × n_cells
is.infinite(geo_dir)  # TRUE where cell is unreachable from that waypoint
```
```

--------------------------------

### Add Dimensionality Reduction Embedding with add_dimred()

Source: https://context7.com/dynverse/dynwrap/llms.txt

Attaches a 2-D or higher embedding to the dataset. Can accept pre-computed matrices, data frames, or functions. Automatically projects trajectory elements if they exist.

```r
if (requireNamespace("dyndimred", quietly = TRUE)) {
  dataset <- example_dataset  # bundled example with expression + trajectory

  dataset <- add_dimred(
    dataset,
    dimred             = dyndimred::dimred_landmark_mds,
    project_trajectory = TRUE,
    expression_source  = "expression"
  )

  head(dataset$dimred)            # cells × comp_1, comp_2
  head(dataset$dimred_milestones) # milestones in the same space
}
```

```r
# Alternatively pass a pre-computed matrix
dimred_mat <- matrix(rnorm(length(example_dataset$cell_ids) * 2),
                     nrow = length(example_dataset$cell_ids))
rownames(dimred_mat) <- example_dataset$cell_ids

example_dataset <- add_dimred(example_dataset, dimred = dimred_mat)
```

--------------------------------

### Attach Cell Grouping with add_grouping()

Source: https://context7.com/dynverse/dynwrap/llms.txt

Associates each cell with a group identifier. The grouping can be a named character vector or a two-column data frame. Can also derive groupings from trajectory edges or milestones.

```r
dataset <- example_dataset

set.seed(5)
grouping <- sample(c("typeA","typeB","typeC"),
                   length(dataset$cell_ids), replace = TRUE)
names(grouping) <- dataset$cell_ids

dataset <- add_grouping(dataset, grouping)

head(dataset$grouping)
is_wrapper_with_grouping(dataset)  # TRUE

# Derive groupings from an existing trajectory
edge_groups      <- group_onto_trajectory_edges(example_trajectory)
milestone_groups <- group_onto_nearest_milestones(example_trajectory)
head(edge_groups)      # "M1->M2" per cell
head(milestone_groups) # nearest milestone per cell
```

--------------------------------

### Label milestones in a trajectory

Source: https://context7.com/dynverse/dynwrap/llms.txt

Assigns human-readable labels to milestones. Can be done manually by providing a named vector of milestone IDs to labels, or automatically using marker genes and nearest cells. Ensure the trajectory object is correctly prepared.

```R
trajectory <- example_trajectory

# Manual labelling
trajectory <- label_milestones(
  trajectory,
  labelling = c("milestone_begin" = "Progenitor", "milestone_end" = "Mature")
)
get_milestone_labelling(trajectory)

# Marker-gene-based labelling
trajectory <- label_milestones_markers(
  trajectory,
  markers = list(
    Progenitor = c("Gene1", "Gene2"),
    Mature     = c("Gene8", "Gene9")
  ),
  n_nearest_cells = 30
)
get_milestone_labelling(trajectory)
is_wrapper_with_milestone_labelling(trajectory)  # TRUE
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.