Detect the strongest certified vertical-gradient candidate

Reduce a current certified C4 vertical-gradient cube to the strongest generic gradient candidate per profile and variable without recalculating gradients.

Usage

depth_feature(
  x,
  polarity = c("absolute", "positive", "negative"),
  support = c("local", "all")
)

Arguments

x: A memory-backed <ocean_cube> produced by depth_gradient(), or a supported selection of one, with a current certified C4 vertical-gradient descriptor.
polarity: Candidate direction. "absolute" ranks gradient magnitude, "positive" ranks positive gradients, and "negative" ranks negative gradients.
support: Support policy. "local" excludes explicitly gapped secants. "all" also ranks them but preserves a gapped-candidate label.

Value

A base data.frame with one row per longitude, latitude, time, and variable, ordered with longitude fastest. Each row contains either one resolved candidate and its C4 diagnostics or a conservative status explaining why no candidate was certified.

Details

Absolute, positive, and negative polarity use one scale-aware tolerance for effective zero and ties. Tied strongest candidates remain ambiguous. Missing eligible gradients reduce gradient_completeness; a returned candidate from an incomplete profile is explicitly only the strongest observed candidate.

Local support admits contiguous cell support and point brackets but excludes GAPPED_SUPPORT. An explicit support = "all" request may select a gapped secant only as GAPPED_SECANT_CANDIDATE. Gaps are never filled.

Feature depth is the C4 midpoint. Canonical depth is positive-down metres, and localization_half_span_m = spacing_m / 2 is a vertical resolution scale, not statistical uncertainty. The result is a generic candidate, not a thermocline, oxycline, halocline, mixed-layer depth, or other physics-aware interpretation. No smoothing, threshold, prominence, feature width, or second derivative is applied.

Examples

if (FALSE) { # \dontrun{
# Offline synthetic examples; `cube` must have certified vertical metadata.
gradient <- depth_gradient(cube)
depth_feature(gradient, polarity = "absolute")
depth_feature(gradient, polarity = "negative")

# Default local support excludes explicitly gapped secants.
depth_feature(gradient, support = "local")
} # }