Gradient Flow Correlation Analysis

Computes symmetric association measures between two fitted surfaces using gradient flow complex structure. The analysis quantifies how the gradient flow partitions of two functions relate to each other, providing measures of association at global, basin, and vertex levels.

Usage

gfcor(
  y.hat,
  z.hat,
  y.basins,
  z.basins,
  vertex.mass = NULL,
  polarity.scale = c("value", "rank"),
  epsilon = 1e-10,
  support.stage = NULL
)

Arguments

y.hat: Numeric vector of fitted values for the first surface. Length must equal the number of vertices in the graph.
z.hat: Numeric vector of fitted values for the second surface. Must have the same length as y.hat.
y.basins, z.basins: Successful trajectory_flow objects from create.basin.complex(), constructed with direction = "both", or two compatible archived basins_of_attraction objects. Do not mix these input families.
vertex.mass: Optional nonnegative finite vertex weights. Canonical inputs normalize these to total mass one (NULL gives uniform mass 1/n); stored construction masses are not used implicitly. Archived inputs retain the original unnormalized mass convention.
polarity.scale: Character string specifying the polarity computation mode. Either "value" (default) for normalized height based on function values, or "rank" for rank-based computation within cells.
epsilon: Numeric threshold for detecting flat regions where polarity is undefined. Vertices with dynamic range smaller than epsilon are marked as invalid. Default is 1e-10.
support.stage: For canonical inputs, explicitly choose "raw" or "retained". Raw supports precede refinement. Retained supports allow support filtering only; other refinements require using raw supports. Leave NULL for archived inputs, whose behavior is unchanged.

Value

An object of class "gfcor" containing:

global

List of global association measures:

A_pol: Polarity concordance in \([-1, 1]\)
kappa_pol: Sign concordance in \([-1, 1]\)
n_positive: Count of vertices with positive association
n_negative: Count of vertices with negative association
n_zero: Count of vertices with zero association
n_invalid: Count of vertices with undefined polarity

vertex

List of vertex-level results:

a_pol: Association score p_y * p_z in \([-1, 1]\)
sign_pol: Sign of association in \(\{-1, 0, +1\}\)
confidence: Absolute value |a_pol| as an association-magnitude proxy, not a calibrated probability
is_valid: Logical indicating valid polarity

polarity_y

Polarity structure for y (theta, polarity, range, is_valid)

polarity_z

Polarity structure for z

basin_character

Basin association characters:

chi_y_max: Character of each y-maximum basin
chi_y_min: Character of each y-minimum basin
chi_z_max: Character of each z-maximum basin
chi_z_min: Character of each z-minimum basin
mass_*: Corresponding basin masses

overlap

Soft overlap matrices:

O_pp: y-max with z-max overlap
O_mm: y-min with z-min overlap
O_pm: y-max with z-min overlap
O_mp: y-min with z-max overlap
total_mass: Sum of vertex masses

membership

List containing y and z membership structures

Details

The gradient flow correlation framework addresses a fundamental question: given two fitted surfaces y and z on a graph, in what regions do they exhibit positive association (both increase together) versus negative association (one increases while the other decreases)?

The key insight is that gradient flow partitions the graph into basins of attraction. Each basin consists of vertices whose gradient flow trajectories converge to the same local extremum. By analyzing how the basin partitions of y and z overlap and how the functions vary within those overlapping regions, we obtain descriptive association measures conditional on the supplied basin construction and filtering.

The polarity coordinate p(v) in \([-1, 1]\) measures where vertex v sits within its accessible dynamic range. A vertex with p(v) near +1 sits close to a local maximum of its gradient flow cell, while p(v) near -1 indicates proximity to a local minimum. The vertex-level association a_pol(v) is the product \(p_y(v) \cdot p_z(v)\), which is positive when v occupies similar relative positions in both landscapes.

Two global summaries aggregate vertex-level association. The polarity concordance A_pol is the mass-weighted average of a_pol(v), while the sign concordance kappa_pol counts the mass-weighted proportion of vertices with positive minus negative association signs.

Basin association character chi provides a basin-level summary. For each y-basin, chi measures the average z-polarity within that basin. Values near +1 indicate that high-y regions coincide with high-z regions, while values near -1 indicate opposite association.

Polarity Scale

Two polarity computation modes are available. The value-based mode (default) uses raw function values to compute normalized height within cells. The rank-based mode uses ranks within each cell, providing invariance under monotone transformations of the functions. Rank-based polarity is recommended for cross-cohort comparisons where absolute scales may differ.

Basin Multiplicity

In discrete Morse theory, gradient trajectories are not unique. A vertex may belong to multiple basins simultaneously when it has multiple neighbors with lower (or higher) function values. The implementation handles this multiplicity through soft membership vectors that distribute unit mass across containing basins. All statistics properly account for this multiplicity.

Canonical support contract

Both complexes must use identical graph adjacency, edge lengths, external vertex IDs and vertex order. Supply their construction fields, including any tie perturbation, as y.hat and z.hat. Hierarchical and other method families are deliberately rejected: their supports do not yet have the same validated association interpretation. The returned canonical metadata records the support stage, vertex IDs, basin IDs in kernel order, and normalized masses. Kernel basin indices are zero-based; their positions map to these basin IDs.

Membership is uniform across containing basins within each direction. A vertex uncovered in either direction has undefined polarity. Flat cells (range below epsilon) also have undefined polarity. Check is_valid: numeric zero is a placeholder for invalid vertices. Global association averages use only valid vertices; an entirely invalid result has zero as a placeholder. Overlap total mass includes all vertices, so uncovered mass need not appear in its matrices. Value polarity uses (y - minimum)/(maximum - minimum + epsilon) before conversion to [-1, 1]. Consequently self-association averages squared polarity and is generally less than one; this is not a Pearson correlation.

Examples

adj <- list(2L, c(1L, 3L), c(2L, 4L), c(3L, 5L), 4L)
lengths <- lapply(adj, function(v) rep(1, length(v)))
y <- c(0, 3, 1, 2, 0)
z <- -y
by <- create.basin.complex(adj, lengths, y, method = "trajectory_flow",
                           direction = "both")
bz <- create.basin.complex(adj, lengths, z, method = "trajectory_flow",
                           direction = "both")
association <- gfcor(y, z, by, bz, support.stage = "raw")
association$global # Negative polarity concordance for reversed fields.