Movatterモバイル変換

eFCM: Exponential Factor Copula Model

Description

Implements the exponential Factor Copula Model (eFCM) of Castro-Camilo and Huser (2020) for spatial extremes, with tools for dependence estimation, tail inference,and visualization. The package supports likelihood-based inference, Gaussian process modeling via Matérn covariance functions, and bootstrap uncertainty quantification.

References

Castro-Camilo, D. & Huser, R. (2020).Local likelihood estimation of complex tail dependence structures, with applicationto U.S. precipitation extremes.Journal of the American Statistical Association,115(531), 1037–1054.doi:10.1080/01621459.2019.1611584

Li, M. & Castro-Camilo, D. (2025).On the importance of tail assumptions in climate extreme event attribution.arXiv.doi:10.48550/arXiv.2507.14019

Akaike Information Criterion (AIC) for fcm objects

Description

Compute the AIC value for a fittedfcm model using the formula:

\mathrm{AIC} = -2 \cdot \log L + k \cdot p

whereL is the likelihood,p is the number of parameters, andk is a penalty parameter.

Usage

## S3 method for class 'fcm'AIC(object, ..., k = 2)

Arguments

Value

A numeric scalar giving the AIC value for the fitted model.

See Also

logLik.fcm(),BIC.fcm(),AICc.fcm()

Corrected Akaike Information Criterion (AICc) for fcm objects

Description

Compute the AICc value for a fittedfcm model using the formula:

\mathrm{AICc} = \mathrm{AIC} + \frac{2p(p+1)}{n - p - 1}

wheren is the number of observations andp is the number of parameters.

Usage

AICc(object, ...)## S3 method for class 'fcm'AICc(object, ...)

Arguments

Value

A numeric scalar giving the AICc value for the fitted model.

See Also

AIC.fcm(),BIC.fcm()

Bayesian Information Criterion (BIC) for fcm objects

Description

Compute the BIC value for a fittedfcm model using the formula:

\mathrm{BIC} = -2 \cdot \log L + \log(n) \cdot p

wheren is the number of observations andp is the number of parameters.

Usage

## S3 method for class 'fcm'BIC(object, ...)

Arguments

Value

A numeric scalar giving the BIC value for the fitted model.

See Also

AIC.fcm(),AICc.fcm()

Spatial coordinates of European stations

Description

A dataset containing the longitude and latitude of monitoring stations usedin the eFCM examples and vignettes.

Usage

data(LonLat)

Format

A data frame withn rows and 2 variables:

lon

Longitude (decimal degrees, WGS84).

lat

Latitude (decimal degrees, WGS84).

Examples

data(LonLat)head(LonLat)

Counterfactual daily precipitation data

Description

An example dataset stored as an object of class"fdata",suitable for direct use withfcm

Usage

data(cf_data)

Format

An object of class"fdata"

Examples

data(cf_data)dim(cf_data)

Tail Dependence Coefficient (Chi Statistic)

Description

Compute the conditional exceedance probability\chi_h(u),either from a fitted eFCM model (chi.fcm) or empirically (Echi).\chi_h(u) measures the probability of simultaneous exceedances at high but finite thresholds.

Usage

## S3 method for class 'fcm'chi(object, h, u = 0.95, ...)Echi(object, which = c(1, 2), u = 0.95)

Arguments

Details

For two locationss_1 ands_2 separated by distanceh,with respective vector componentsW(s_1) andW(s_2),the conditional exceedance probability is defined as

\chi_h(u) \;=\; \lim_{u \to 1} \Pr\!\big( F_{s_1}(W(s_1)) > u \;\mid\; F_{s_2}(W(s_2)) > u \big).

For the eFCM, the conditional exceedance probability\chi_{\mathrm{eFCM}}(u)can be computed as

\chi_{\mathrm{eFCM}}(u) =\frac{1 - 2u + \Phi_2\big(z(u), z(u); \rho\big)- 2 \exp\!\left( \frac{\lambda^2}{2} - \lambda\, z(u)\, \Phi_2\big(q; 0, \Omega\big) \right)}{1 - u}.

Here,z(u) = F_1^{-1}(u; \lambda) is the marginal quantile function,\Phi_2(\cdot,\cdot;\rho) denotes the bivariate standard normal CDF with correlation\rho,q = \lambda(1-\rho), and\Omega is the correlation matrix.

Value

A named numeric value, the chi statistic for givenh andu.

Methods

• chi.fcm(): Model-based estimate from an object of class"fcm".

• Echi(): Empirical estimate.

References

Castro-Camilo, D. and Huser, R. (2020).Local likelihood estimation of complex tail dependence structures,applied to US precipitation extremes.Journal of the American Statistical Association, 115(531), 1037–1054.

Examples

fit <- fcm(...)chi(fit, h = 150, u = 0.95)

Chi Plot for Fitted eFCM Model

Description

Plots the eFCM conditional exceedance probability\chi_h(u).

Usage

## S3 method for class 'fcm'chiplot(  object,  h = NULL,  method = c("default", "hessian", "boot"),  ci = 0.95,  emp = TRUE,  which = c(1, 2),  ...)chiplot(object, ...)

Arguments

Value

A (invisible) list containing chi estimates and confidence bounds:

chi.u

Estimated chi values.

chi.lower

Lower confidence bounds (if applicable).

chi.upper

Upper confidence bounds (if applicable).

chi.emp

Empirical chi curve (ifemp = TRUE).

h

Distance used.

References

Castro-Camilo, D. and Huser, R. (2020).Local likelihood estimation of complex tail dependence structures,applied to US precipitation extremes.Journal of the American Statistical Association, 115(531), 1037–1054.

See Also

chi(),Echi()

Extract Model Coefficients

Description

Extract estimated model parameters from objects returned byfcm().Optionally computes confidence intervals via either the observed Hessian(Delta method, on the log scale) or bootstrap sampling.

Usage

## S3 method for class 'fcm'coef(object, ..., method = c("default", "hessian", "boot"), ci = 0.95)

Arguments

Details

Ifmethod = "hessian", confidence intervals are constructed on the log scaleusing the Delta method, then exponentiated to return to the original parameter scale.Ifmethod = "boot", confidence intervals are computed as empirical quantiles ofthe bootstrap replicates.

Value

Ifmethod = "default", returns a named vector of parameter estimates.Ifmethod = "hessian" ormethod = "boot", returns adata.frame with columns:

• par: the estimated parameter

• lower: lower bound of the CI

• upper: upper bound of the CI

See Also

fcm()

Examples

data(fit)coef(fit)coef(fit, method = "hessian", ci = 0.95)coef(fit, method = "boot", ci = 0.95)

Weekly Maxima of Counterfactual Precipitation in Europe

Description

Weekly maxima of precipitation under natural-only forcing over a European domain.This processed dataset is used in the vignettes and examples to illustratemodel fitting and attribution mapping with eFCM.

Usage

data(counterfactual)

Format

A numeric matrix or data frame with dimensions (weeks × stations).Rows index consecutive winter-season weeks; columns correspond to stations.Units are millimetres.

Details

This dataset is derived from daily-resolution counterfactual simulations(not included in the package due to size constraints) by aggregating to weeklymaxima. It is intended for examples, tests, and vignettes where a lightweightdataset is preferred.

Examples

data(counterfactual)dim(counterfactual)plot(apply(counterfactual, 1, mean), type = "l",     xlab = "Week", ylab = "Mean precipitation (mm)")

Fit the exponential Factor Copula Model (eFCM)

Description

Fits the eFCM at a specified grid point using local neighborhood data.

Usage

fcm(  s,  object,  theta0 = c(2, 100),  thres = 0.9,  nu = 0.5,  hessian = TRUE,  control = list(),  censorL = TRUE,  boot = FALSE,  R = 1000,  progress = TRUE,  lower = c(1, 1),  upper = Inf,  sample_prop = 0.9,  sample_ids = NULL,  parallel = FALSE,  ncpus = 4,  mc.set.seed = TRUE,  ...)

Arguments

Details

The exponential Factor Copula Model (eFCM) assumes that the processW(s) = Z(s) + V, whereZ(s) is a zero-mean Gaussian process with correlation\rho(h) = \exp(-h/\delta) andV \sim \mathrm{Exp}(\lambda) is a latent common factor independent ofZ(s) ands. This leads to nontrivial tail dependence between spatial locations.

Value

An object of class"fcm", which is a list including:

References

Castro-Camilo, D. and Huser, R. (2020). Local likelihood estimation of complex tail dependence structures, applied to US precipitation extremes.JASA, 115(531), 1037–1054.

See Also

fdata,coef,summary

Examples

# Load precipitation data for counterfactual scenariosdata("counterfactual")data("LonLat")coord = LonLat  # station coordinates (longitude-latitude)cf_data <- fdata(counterfactual, coord, cellsize = c(1, 1))fit = fcm(s = 1, cf_data, boot = T, R = 1000)

Transform datasets for factor copula modeling

Description

Prepares and organizes datasets for use with the exponential Factor Copula Model (eFCM). The function converts raw station-level observations and their spatial coordinates into an "fdata" object, which contains the data, grid structure, and neighborhood information required for model fitting withfcm().

Usage

fdata(  data,  coord,  grid = NULL,  neigh = NULL,  theta0 = NULL,  cellsize = c(0.5, 0.5),  parallel = TRUE,  ncpus = 4,  mc.set.seed = TRUE,  ...)

Arguments

Value

An object of class"fdata", which is a list with elements:

See Also

fcm(),neighborhood_HT()

Examples

# Load precipitation data for counterfactual scenariosdata("counterfactual")data("LonLat")coord = LonLat  # station coordinates (longitude-latitude)cf_data <- fdata(counterfactual, coord, cellsize = c(1, 1))

Example fitted eFCM object

Description

An example output of thefcm function, obtained by fittingthe exponential Factor Copula Model to a subset of precipitation data.

Usage

data(fit)

Format

An object of class"fcm"

Examples

data(fit)summary(fit)

Log-likelihood of a fitted factor copula model

Description

Extract the log-likelihood value from a fittedfcm object.

Usage

## S3 method for class 'fcm'logLik(object, ...)

Arguments

Value

A numeric value giving the log-likelihood of the fitted model.

See Also

AIC.fcm(),BIC.fcm(),AICc.fcm()

Homogeneous neighborhood selection

Description

Identifies homogeneous neighbors around a given grid point using a combinationof the Hosking-Wallis (1993) and Anderson-Darling (1987) tests for marginal homogeneity.

Usage

neighborhood_HT(  data,  coord,  s0,  miles = FALSE,  min.neigh = 5,  max.neigh = 20,  pr = 0.9,  alpha = 0.05,  dmax = 150,  which.test = c(1, 2))

Arguments

Value

A vector of station indices considered homogeneous with the grid point.

References

Castro-Camilo, D. and Huser, R. (2020).JASA 115, 1037–1054.Hosking, J. and Wallis, J. (1993).Water Resour. Res. 29, 271–281.Scholz, F.W. and Stephens, M.A. (1987).JASA 82, 918–924.

See Also

fdata()

Examples

neighborhood_HT(counterfactual, coord = LonLat, s0 = c(30, 39), which.test = c(1, 2))

The Distribution of Univariate Factor Copula Model

Description

Density, distribution function, quantile function and random generationfor the distribution of univariate factor copula model with rate parameterequal tolambda.

Usage

pfcm(w, lambda)dfcm(w, lambda)qfcm(u, lambda, tol = 1e-08, niter = 1000L)rfcm(n, lambda)

Arguments

Details

The univariate eFCM distribution is

F(w;\lambda)=\Phi(w)-exp(\lambda^2/2-\lambda w)\Phi(w-\lambda),

where\lambda is the rate parameter.

Value

dfcm gives a numeric value representing the density of the factor copula model evaluated atw,pfcm gives a numeric value representing the CDF evaluated atw,qfcm gives the quantile function (QF) of the factor copula model.andrfcm generate a numeric vector of random samples drawn.

Examples

pfcm(w = 1, lambda = 0.5)dfcm(w = 1, lambda = 0.5)qfcm(u = 0.5, lambda = 0.5)rfcm(n = 1000, lambda = 0.5)

CDF of the exponential Factor Copula Model (vector input)

Description

Computes the eFCM-basedP(W \leq w) for a singled-dimensional vectorw.

Usage

pmfcm(  w,  lambda,  delta,  dist = NULL,  coord = NULL,  smooth = 0.5,  abseps = 1e-05,  releps = 1e-05,  maxpts = 25000,  miles = FALSE)

Arguments

Value

A single numeric CDF value in[0,1].

Examples

data(LonLat)d <- 2w <- rep(0.3, d)pmfcm(w, lambda = 2, delta = 100, coord = LonLat[1:2, ])

Q–Q Plot for Fitted Factor Copula Model

Description

Produce a Q–Q plot comparing empirical exceedances to the fitted eFCM tail,with an optional GPD tail overlay for diagnostic comparison.

Usage

qqplot(object, ...)## S3 method for class 'fcm'qqplot(  object,  which = 1,  gpd = TRUE,  thres = 0.9,  main = "Q-Q plot",  xlab = "Theoretical quantiles (exceedances)",  ylab = "Empirical exceedances",  ...)

Arguments

Details

The function first selects a thresholdu as the empiricalthres-quantile of the selected station seriesx.It then forms exceedancesY = X - u \mid X>u, fits the eFCM(implicitly viaqfcm() and a scalar\lambda estimate),and plots empirical exceedances against theoretical eFCM quantiles in the tail.Ifgpd=TRUE, a GPD is fitted to the exceedances (threshold 0) andits theoretical tail quantiles are added for visual comparison.

Value

A numeric vector of fitted eFCM theoretical tail quantiles, invisibly returned.

Random generation from the exponential Factor Copula Model (eFCM)

Description

Drawsn samples from the eFCM.

Usage

rmfcm(  lambda,  delta,  dist = NULL,  coord = NULL,  nu = 0.5,  n = 5e+05,  miles = FALSE,  seed = NULL)

Arguments

Value

A numeric matrix of sizen x d (rows = samples, cols = stations).

Examples

data(LonLat)sim <- rmfcm(lambda = 2, delta = 100, coord = LonLat[1:2, ], n = 10000)dim(sim)  # 10000 x 2

Summarizing Factor Copula Model Fits

Description

Summary method for objects of class"fcm", returned byfcm().

Usage

## S3 method for class 'fcm'summary(object, ...)

Arguments

Value

Invisibly, a list with summary components:

• grid: the selected grid point

• neighbors: indices and coordinates of neighbors

• coef: parameter estimates with 95\

• objective: negative log-likelihood

• information criteria:c(AIC, BIC, AICc)

• args: fitting arguments

Examples

data(fit)summary(fit)