Compute Monotonicity Statistics for Cell Trajectories

For each trajectory in a cell.trajectories object, evaluates whether the graph distance from the starting vertex increases monotonically along the trajectory. This diagnostic helps identify trajectories that "wander" away from and back toward the starting extremum rather than progressing smoothly.

Usage

# S3 method for class 'monotonicity'
cell.trajectories(
  x,
  min.id,
  max.id,
  adj.list = x,
  weight.list = min.id,
  cell.trajectories = max.id,
  ...
)

Arguments

x

List of integer vectors. Each element x[[i]] contains the 1-based indices of vertices adjacent to vertex i.

min.id

List of numeric vectors. Each element min.id[[i]] contains edge weights corresponding to x[[i]] (backward compatible alias: weight.list).

max.id

Output from cell.trajectories.gfc.flow(), containing a trajectories element which is a list of trajectory objects each with a vertices field. (backward compatible alias: cell.trajectories).

adj.list

Backward-compatible alias for x.

weight.list

Backward-compatible alias for min.id.

cell.trajectories

Backward-compatible alias for max.id.

...

Additional arguments (currently ignored).

Value

A data frame with one row per trajectory and three columns:

n.mono

Number of consecutive vertex pairs where the distance from the start vertex increases, i.e., where \(d(x_0, v_{j+1}) > d(x_0, v_j)\).

n.vert

Number of consecutive vertex pairs in the trajectory (equal to the number of vertices minus one).

p.mono

Proportion of monotonic transitions: n.mono / n.vert. A value of 1.0 indicates perfect distance monotonicity.

Details

The function computes shortest path distances from each trajectory's starting vertex using igraph's optimized shortest path algorithms. For trajectories sharing the same start vertex (common within a cell), distances are computed once and cached for efficiency.

A trajectory with p.mono = 1.0 is fully monotonic: every step along the trajectory moves further from the starting extremum in terms of graph distance. Lower values indicate trajectories that backtrack or take detours, which may suggest paths through geometrically isolated vertices.

See also

cell.trajectories.gfc.flow, cell.trajectories.max.edge.length

Examples

if (FALSE) { # \dontrun{
cell.trajs <- cell.trajectories.gfc.flow(gfc.flow.res, "m2", "M7")
mono.stats <- cell.trajectories.monotonicity(adj.list, weight.list, cell.trajs)

## Find non-monotonic trajectories
which(mono.stats$p.mono < 1.0)

## Summary of monotonicity across all trajectories
summary(mono.stats$p.mono)
} # }