Compute Polarity Coordinates for a Fitted Surface

Computes the polarity coordinate p(v) in $[-1, 1]$ for each vertex, measuring where the vertex sits within its accessible dynamic range defined by the gradient flow structure.

Usage

gfassoc.polarity(
  y,
  membership,
  polarity.scale = c("value", "rank"),
  epsilon = 1e-10
)

Arguments

y: Numeric vector of function values at vertices.
membership: Object of class "gfassoc_membership" from gfassoc.membership.
polarity.scale: Character string: "value" for normalized height based on function values, "rank" for rank-based computation.
epsilon: Numeric threshold for flat region detection.

Value

An object of class "gfassoc_polarity" containing:

theta: Numeric vector of normalized heights in $[0, 1]$.
polarity: Numeric vector of polarity coordinates in $[-1, 1]$.
range: Numeric vector of dynamic ranges M(v) - m(v).
is_valid: Logical vector indicating valid polarity computation.
epsilon: The epsilon value used.

Details

The polarity coordinate captures the relative position of a vertex within its gradient flow cell. For a vertex v in cell $C_{ij}$ (between maximum M_i and minimum m_j), the normalized height is:

$$ theta(v) = (y(v) - y(m_j)) / (y(M_i) - y(m_j)) $$

This value lies in $[0, 1]$ by the gradient flow property: any vertex reachable from both M_i (via descending flow) and m_j (via ascending flow) must have function value between y(m_j) and y(M_i).

The polarity coordinate rescales to $[-1, 1]$:

$$p(v) = 2 \cdot theta(v) - 1$$

So p(v) = +1 at maxima, p(v) = -1 at minima, and p(v) = 0 at the midpoint.

When a vertex belongs to multiple cells (basin multiplicity), the polarity is computed as the membership-weighted average of cell-specific polarities.

Examples

if (FALSE) { # \dontrun{
## Compute membership and polarity
# basins must be a compatible saved basins_of_attraction object for y.
membership <- gfassoc.membership(basins)
polarity <- gfassoc.polarity(y, membership)

## Identify vertices near maxima (high polarity)
near.max <- which(polarity$polarity > 0.8 & polarity$is_valid)
} # }