Label Extremality-Based Local Extrema in 3D Plot

Adds labeled line segments to a 3D plot at positions of local extrema identified via Riemannian extremality analysis. This function works with the output of extremality.summary() to visualize extrema detected using the full Riemannian metric structure.

Usage

label.extremality.3d(
  graph.3d,
  extremality.df,
  extrema.type = c("both", "maxima", "minima"),
  offset = c(0, 0, 0.25),
  with.labels = TRUE,
  lab.cex = 1.5,
  lab.adj = c(0, 0),
  C = -1,
  pwd = 5,
  separate.colors = TRUE,
  col.max = "red",
  col.min = "blue",
  col = "black",
  ...
)

Arguments

graph.3d

A matrix or data frame with 3 columns representing 3D coordinates. Each row corresponds to a vertex.

extremality.df

Data frame from extremality.summary() with required columns: vertex, label, type. The 'type' column should contain "max" for maxima and "min" for minima.

extrema.type

Character string specifying which extrema to plot: "both" (default) plots both maxima and minima, "maxima" plots only maxima, "minima" plots only minima.

offset

Numeric vector of length 3 specifying the offset for line segments relative to vertex positions. Default c(0, 0, 0.25) creates vertical line segments above vertices.

with.labels

Logical. Whether to display text labels. Default TRUE.

lab.cex

Character expansion factor for labels. Default 1.5.

lab.adj

Adjustment parameter for label positioning. Numeric vector of length 2. Default c(0, 0) centers labels.

C

Scaling factor for label position relative to stick center. Default -1 places labels at the top of segments.

pwd

Line width for segments. Default 5.

separate.colors

Logical. If TRUE and extrema.type="both", plot maxima and minima with different colors (col.max and col.min). If FALSE, use single color from 'col' parameter. Default TRUE.

col.max

Color for maxima when separate.colors=TRUE. Default "red".

col.min

Color for minima when separate.colors=TRUE. Default "blue".

col

Color for all extrema when separate.colors=FALSE or when plotting only one type. Default "black".

...

Additional arguments passed to bin.segments3d().

Value

Invisibly returns NULL. Function is called for its side effect of adding labeled segments to the current 3D plot.

Details

This function is designed to work with extremality analysis results from extremality.summary(), which provides Riemannian extremality-based extremum detection. It extends the functionality of label.extrema.3d() to work with the richer extremality data structure.

The function uses the 'type' column to distinguish maxima from minima (values "max" and "min"), rather than the binary 'is_max' column used in classical extrema detection.

See also

extremality.summary for generating extremality-based extrema summaries, label.extrema.3d for labeling classical extrema, The private bin.segments3d() helper provides segment rendering.

Examples

if (FALSE) { # \dontrun{
# Fit model with extremality analysis
fit <- gflowx::fit.rdgraph.regression(X, y, k = 50,
                              compute.extremality = TRUE,
                              p.threshold = 0.90)

# Get extremality summary
extremality_df <- extremality.summary(fit)

# Create 3D projection for visualization
library(rgl)
pca_result <- prcomp(X, center = TRUE, scale. = TRUE)
graph_3d <- pca_result$x[, 1:3]

# Plot fitted surface
plot3d(graph_3d, col = rainbow(100)[cut(fit$fitted.values, 100)],
       size = 5, main = "Fitted Surface with Extrema")

# Label both maxima and minima with different colors (default)
label.extremality.3d(graph_3d, extremality_df)

# Label only maxima
label.extremality.3d(graph_3d, extremality_df,
                     extrema.type = "maxima",
                     col.max = "darkred")

# Label only minima
label.extremality.3d(graph_3d, extremality_df,
                     extrema.type = "minima",
                     col.min = "darkblue")

# Label both with same color
label.extremality.3d(graph_3d, extremality_df,
                     separate.colors = FALSE,
                     col = "purple")

# Customize offset and label size for persistent extrema
persistent <- subset(extremality_df, extremality.radius >= 5)
label.extremality.3d(graph_3d, persistent,
                     offset = c(0, 0, 0.5),
                     lab.cex = 2.0)
} # }