AGCA4extremes

Author: Alberto Quaini

AGCA4extremes implements anchored geodesic component analysis (AGCA) for multivariate extremes. AGCA summarizes how extreme angular profiles vary around a benchmark direction, most often the canonical balanced-dependence anchor.

The package provides:

• rank-Pareto marginal standardization;
• Pareto standardization from user-supplied CDFs;
• top-k angular extraction and optional runs declustering;
• canonical, spherical Frechet, and principal anchors;
• AGCA scores, loadings, eigenvalues, explained variation, reconstruction, and residual risk;
• bootstrap, threshold, and anchor-sensitivity diagnostics;
• base R plotting methods and functional approximation summaries.

The numerical core is implemented with Rcpp and RcppArmadillo; the R layer provides validation, S3 methods, diagnostics, plotting, and documentation.

Installation

During development, install from the package directory:

install.packages(c("Rcpp", "RcppArmadillo"))
devtools::install("AGCA4extremes")

After public release:

install.packages("AGCA4extremes")

Basic Use

library(AGCA4extremes)

data(agca_10d_simulation)

x <- agca_10d_simulation[paste0("X", 1:10)]
fit <- agca(x, k = 250, p = 5)

fit
summary(fit)
plot(fit, type = "variation")

The default marginal transformation is rank-Pareto. Larger observations in each margin are treated as more extreme, so financial return data should be converted to losses before calling agca().

Example Diagnostics

The bundled agca_10d_simulation data set is generated from a 10-dimensional heavy-tailed design. Variables X1–X8 share a low-dimensional extremal mechanism, while X9 and X10 contain independent Pareto sources that create near-axis extreme regimes.

data(agca_10d_simulation)

x <- agca_10d_simulation[paste0("X", 1:10)]
fit <- agca(x, k = 500, p = 4, seed = 1)

agca_rank_summary(fit)

Explained variation:

plot(fit, type = "variation")

Scores for the first two anchored geodesic components:

cols <- c(shared_low_rank = "#1B9E77", axis_9 = "#5B3A29", axis_10 = "#7570B3")
plot(
  fit$scores[, 1], fit$scores[, 2],
  col = cols[agca_10d_simulation$regime[fit$tail$index]],
  pch = 16,
  xlab = "AGC1 score",
  ylab = "AGC2 score"
)
legend("topright", legend = names(cols), col = cols, pch = 16, bty = "n")

Loadings:

plot(fit, type = "loadings", p = 1)
plot(fit, type = "loadings", p = 2)

Threshold and anchor diagnostics:

threshold_stability(x, k = c(250, 350, 500, 750), p = 4)
anchor_sensitivity(x, k = 500, p = 4)

Bootstrap uncertainty for rank summaries:

boot <- bootstrap_agca(fit, B = 99, ranks = c(1, 2, 4), seed = 1)
summary(boot)
plot(boot, statistic = "variation_explained")

Main Functions

• agca() fits the full workflow from data to an AGCA object.
• rank_pareto() and pareto_from_cdf() perform marginal standardization.
• tail_directions() extracts large-radius angular observations.
• decluster_runs() performs simple runs declustering for radial extremes.
• agca_fit_directions() fits AGCA directly to angular directions.
• agca_reconstruct() maps leading anchored coordinates back to the sphere.
• agca_rank_summary() reports residual risk and anchored variation explained.
• bootstrap_agca() resamples angular directions to quantify sampling uncertainty.
• threshold_stability() and anchor_sensitivity() provide diagnostics.

Paper Replication

The CRAN package is intentionally lean. Large raw data, generated results, figures, and full paper workflows should live in a separate replicateAGCApaper repository that depends on AGCA4extremes.

Development Assistance

OpenAI Codex was used as a programming assistant during development, mainly for code scaffolding, refactoring, documentation, and tests. All methodological choices, validation, final code, and responsibility for the package remain with the author.

mirror server hosted at Truenetwork, Russian Federation.