| Title: | Anchored Geodesic Component Analysis for Extremes |
|---|---|
| Description: | Implements anchored geodesic component analysis for multivariate extremes. The package provides Pareto and rank-Pareto marginal standardization, top-k angular extraction, anchored eigensolutions, reconstruction, diagnostics, nonparametric bootstrap tools, and plotting methods for benchmark-relative angular variation. |
| Authors: | Alberto Quaini [aut, cre] |
| Maintainer: | Alberto Quaini <[email protected]> |
| License: | GPL-3 |
| Version: | 0.1.0 |
| Built: | 2026-07-17 16:54:13 UTC |
| Source: | https://github.com/cran/AGCA4extremes |
agca() is the main user interface. It standardizes margins, extracts
large-radius observations, resolves the anchor, and fits anchored geodesic
components to the resulting angular directions.
agca( x, k = NULL, threshold = NULL, margin = c("rank_pareto", "pareto", "none"), cdf = NULL, anchor = "canonical", p = NULL, decluster = NULL, bootstrap = NULL, keep_data = FALSE, ties_method = "average", seed = NULL )agca( x, k = NULL, threshold = NULL, margin = c("rank_pareto", "pareto", "none"), cdf = NULL, anchor = "canonical", p = NULL, decluster = NULL, bootstrap = NULL, keep_data = FALSE, ties_method = "average", seed = NULL )
x |
Numeric matrix or data frame. Larger values are treated as more extreme in each margin. |
k |
Number of largest radial observations to retain. Specify either
|
threshold |
Radial threshold for selecting extremes. |
margin |
Marginal standardization method. The default |
cdf |
Optional CDF function or list of CDF functions for
|
anchor |
|
p |
Working reconstruction rank. Defaults to the full tangent rank. |
decluster |
Optional. Use |
bootstrap |
Optional integer number of bootstrap resamples. |
keep_data |
Logical. If |
ties_method |
Tie method used by |
seed |
Optional random seed used when |
An object of class "agca_fit".
data(agca_10d_simulation) x <- agca_10d_simulation[paste0("X", 1:10)] fit <- agca(x, k = 100, p = 3) fit agca_rank_summary(fit)data(agca_10d_simulation) x <- agca_10d_simulation[paste0("X", 1:10)] fit <- agca(x, k = 100, p = 3) fit agca_rank_summary(fit)
A package-owned simulated heavy-tailed sample from the 10-dimensional design
used in the AGCA paper. Variables X1–X8 share a low-dimensional
logistic-block extremal mechanism. Variables X9 and X10 contain
independent Pareto sources, creating near-axis extreme regimes alongside the
shared low-rank angular structure.
data(agca_10d_simulation)data(agca_10d_simulation)
A data frame with 10,000 rows and 11 columns. Columns X1, ...,
X10 are positive heavy-tailed observations. Column regime is a latent
factor identifying the dominant source for the observation: shared low-rank,
axis 9, or axis 10.
Simulated by data-raw/simulate_data.R using
simulate_agca_10d().
Fit AGCA to angular directions
agca_fit_directions(g, anchor = "canonical", p = NULL, normalize = TRUE)agca_fit_directions(g, anchor = "canonical", p = NULL, normalize = TRUE)
g |
Matrix of angular directions. |
anchor |
|
p |
Working reconstruction rank. Defaults to the full tangent rank. |
normalize |
Logical. If |
An object of class "agca_fit".
AGCA rank summary
agca_rank_summary(fit)agca_rank_summary(fit)
fit |
An object returned by |
A data frame with rank, residual risk, and variation explained.
Reconstruct angular directions from leading AGCA components
agca_reconstruct(fit, p = fit$p)agca_reconstruct(fit, p = fit$p)
fit |
An object returned by |
p |
Reconstruction rank. |
A matrix of reconstructed angular directions.
Residual risk by AGCA rank
agca_residual_risk(fit, max_rank = length(fit$eigenvalues))agca_residual_risk(fit, max_rank = length(fit$eigenvalues))
fit |
An object returned by |
max_rank |
Maximum rank to report. |
A numeric vector indexed by ranks 0:max_rank.
Marginal standardization for AGCA
agca_standardize( x, margin = c("rank_pareto", "pareto", "none"), cdf = NULL, ties_method = "average" )agca_standardize( x, margin = c("rank_pareto", "pareto", "none"), cdf = NULL, ties_method = "average" )
x |
A numeric matrix or data frame. |
margin |
Standardization method: |
cdf |
Optional CDF function or list of CDF functions for
|
ties_method |
Tie method used by |
A numeric matrix.
Anchored variation explained
agca_variation_explained(fit)agca_variation_explained(fit)
fit |
An object returned by |
Cumulative anchored variation explained by each rank.
Anchor sensitivity diagnostics
anchor_sensitivity(x, k, anchors = c("canonical", "frechet", "principal"), ...)anchor_sensitivity(x, k, anchors = c("canonical", "frechet", "principal"), ...)
x |
Numeric matrix or data frame. |
k |
Number of top radial observations. |
anchors |
Character vector of anchors to compare. |
... |
Additional arguments passed to |
A data frame of rank summaries across anchors.
Computes the anchor coordinate and tangent departure
.
anchored_departures(g, mu, normalize = TRUE)anchored_departures(g, mu, normalize = TRUE)
g |
A numeric matrix of directions. |
mu |
Anchor direction. |
normalize |
Logical. If |
A list with normalized directions, anchor, anchor coordinates, and anchored departures.
Computes mean angular functional values on the fitted and reconstructed directions for a collection of portfolio weights.
angular_functional_error(fit, weights, ranks = fit$p, power = 1, cap = Inf)angular_functional_error(fit, weights, ranks = fit$p, power = 1, cap = Inf)
fit |
An object returned by |
weights |
A numeric vector or matrix. Rows are portfolios. |
ranks |
Integer vector of AGCA ranks. |
power |
Power applied to positive portfolio exposures. |
cap |
Optional finite cap applied to the powered exposure. |
A data frame with original, reconstructed, and relative errors.
Resamples fitted angular directions and recomputes AGCA diagnostics.
bootstrap_agca( fit, B = 199L, ranks = NULL, fixed_anchor = TRUE, anchor = "canonical", seed = NULL )bootstrap_agca( fit, B = 199L, ranks = NULL, fixed_anchor = TRUE, anchor = "canonical", seed = NULL )
fit |
An object returned by |
B |
Number of bootstrap resamples. |
ranks |
Integer ranks to summarize. |
fixed_anchor |
Logical. If |
anchor |
Anchor used when |
seed |
Optional random seed. |
An object of class "agca_bootstrap".
Canonical anchor
canonical_anchor(d)canonical_anchor(d)
d |
Ambient dimension. |
The balanced direction .
Exceedances are split into clusters separated by more than run consecutive
non-exceedances. The representative of each cluster is the observation with
the largest radius.
decluster_runs(x, k = NULL, threshold = NULL, run = 1L)decluster_runs(x, k = NULL, threshold = NULL, run = 1L)
x |
A numeric matrix of standardized observations. |
k, threshold
|
Top-k count or radial threshold used to define exceedances. |
run |
Nonnegative run length. |
A list like tail_directions(), with one index per cluster.
Computes a Karcher-mean approximation to the spherical Frechet mean.
frechet_anchor(g, normalize = TRUE, max_iter = 100L, tol = 1e-10)frechet_anchor(g, normalize = TRUE, max_iter = 100L, tol = 1e-10)
g |
Matrix of angular directions. |
normalize |
Logical. If |
max_iter |
Maximum number of iterations. |
tol |
Convergence tolerance for the tangent update norm. |
A unit vector.
Normalize matrix rows
normalize_rows(x)normalize_rows(x)
x |
A numeric matrix with nonzero rows. |
A numeric matrix whose rows have Euclidean norm one.
Pareto marginal standardization from supplied CDFs
pareto_from_cdf(x, cdf, eps = 1e-12)pareto_from_cdf(x, cdf, eps = 1e-12)
x |
A numeric matrix or data frame. |
cdf |
A function applied to every margin, or a list of one CDF function
per margin. Each CDF must return values in |
eps |
Tail clipping constant used to avoid zero and infinite values. |
A numeric matrix with standard Pareto margins.
Plot AGCA bootstrap summaries
## S3 method for class 'agca_bootstrap' plot(x, statistic = c("variation_explained", "residual_risk"), ...)## S3 method for class 'agca_bootstrap' plot(x, statistic = c("variation_explained", "residual_risk"), ...)
x |
An object returned by |
statistic |
Statistic to plot. |
... |
Additional graphical arguments. |
Invisibly returns x.
Plot AGCA output
## S3 method for class 'agca_fit' plot(x, type = c("variation", "scree", "scores", "loadings"), p = 1L, ...)## S3 method for class 'agca_fit' plot(x, type = c("variation", "scree", "scores", "loadings"), p = 1L, ...)
x |
An object returned by |
type |
Plot type: eigenvalue scree plot, cumulative variation, first two scores, or loadings. |
p |
Component index used for the loadings plot. |
... |
Additional graphical arguments. |
Invisibly returns x.
Principal angular anchor
principal_anchor(g, normalize = TRUE)principal_anchor(g, normalize = TRUE)
g |
Matrix of angular directions. |
normalize |
Logical. If |
The leading eigenvector of the angular second-moment matrix, oriented to have positive sum.
Transforms each margin to empirical standard Pareto scores using
. Larger observations are treated as more
extreme.
rank_pareto(x, ties_method = "average")rank_pareto(x, ties_method = "average")
x |
A numeric matrix or data frame. |
ties_method |
Tie method passed to |
A numeric matrix with standard Pareto-like margins.
Row Euclidean norms
row_norms(x)row_norms(x)
x |
A numeric matrix. |
A numeric vector containing one Euclidean norm per row.
Generates the 10-dimensional heavy-tailed design used as the package example.
Variables X1–X8 share a low-dimensional logistic-block extremal
mechanism. Variables X9 and X10 contain independent Pareto sources, so
selected extremes include near-axis regimes in addition to the shared
low-rank angular structure.
simulate_agca_10d( n = 10000L, seed = NULL, theta = 0.45, tau = 0.25, axis9_scale = 1, axis10_scale = 1 )simulate_agca_10d( n = 10000L, seed = NULL, theta = 0.45, tau = 0.25, axis9_scale = 1, axis10_scale = 1 )
n |
Number of observations. |
seed |
Optional random seed. |
theta |
Logistic dependence parameter in |
tau |
Nonnegative finite-threshold noise scale. |
axis9_scale, axis10_scale
|
Positive scales for the independent Pareto
sources in variables |
A data frame with variables X1, ..., X10 and a factor regime
giving the dominant latent source for each observation.
x <- simulate_agca_10d(n = 500, seed = 1) fit <- agca(x[paste0("X", 1:10)], k = 75, p = 3) agca_rank_summary(fit)x <- simulate_agca_10d(n = 500, seed = 1) fit <- agca(x[paste0("X", 1:10)], k = 75, p = 3) agca_rank_summary(fit)
Computes great-circle distances on the unit sphere. If y has one row and
x has several rows, the single direction in y is recycled.
sphere_distance(x, y, normalize = TRUE)sphere_distance(x, y, normalize = TRUE)
x, y
|
Numeric matrices with the same number of columns. |
normalize |
Logical. If |
A numeric vector of geodesic distances in radians.
Summarize AGCA bootstrap output
## S3 method for class 'agca_bootstrap' summary(object, probs = c(0.025, 0.5, 0.975), ...)## S3 method for class 'agca_bootstrap' summary(object, probs = c(0.025, 0.5, 0.975), ...)
object |
An object returned by |
probs |
Quantile probabilities. |
... |
Unused. |
A data frame of bootstrap summaries by rank.
Top-k angular directions
tail_directions(x, k = NULL, threshold = NULL)tail_directions(x, k = NULL, threshold = NULL)
x |
A numeric matrix of standardized observations. |
k |
Number of largest radii to retain. Specify either |
threshold |
Radial threshold. Observations with radius greater than
|
A list containing angular directions, radii, selected indices, and the threshold.
Threshold stability diagnostics
threshold_stability(x, k, ...)threshold_stability(x, k, ...)
x |
Numeric matrix or data frame. |
k |
Integer vector of top-k values. |
... |
Additional arguments passed to |
A data frame of rank summaries across thresholds.