Package 'margEVT'

Extract names of non-seasonal covariates from a fitted model

Description

Returns the covariate names that appear in the model with a non-negligible coefficient — i.e. those that actually affect the parameters and need to be supplied during marginalization.

Usage

active_covariates(fit, free_cols = NULL, tol = 1e-04)

Arguments

fit	An nhpp_fit object.
free_cols	Character vector of column names to always exclude from the result (intercept and seasonality terms are always excluded). Default NULL.
tol	Numeric. Coefficients smaller than this in absolute value are treated as zero (LASSO shrinkage). Default 1e-4.

Value

Character vector of active covariate names, or NULL if the model has no active non-seasonal covariates.

---

Walk-forward backtesting for NHPP extreme value models

Description

Evaluates predictive performance of a fitted nhpp_fit model via walk-forward cross-validation. For each window, the model is refit on training data at the original penalty and lambda, return levels are computed, and exceedance rates are compared to nominal rates via binomial tests. Probabilistic calibration is assessed via a Kolmogorov-Smirnov test on the PIT values.

Usage

backtest(
  fit,
  data,
  varname,
  TRs = c(2, 5, 10),
  n_obs = 365L,
  window_years = 5L,
  min_train_years = 10L,
  n_boot = 200L,
  interactions = list(),
  year_col = "year",
  min_obs_year = NULL,
  verbose = TRUE
)

Arguments

fit	An nhpp_fit object.
data	The data frame used to fit fit. Must contain columns y, year (or year_col), and all active covariates.
varname	Character. Name of the column in data containing the raw (non-declustered) series, used to compute observed annual maxima for validation.
TRs	Numeric vector of return periods to evaluate. Default c(2, 5, 10).
n_obs	Integer. Observations per year. Default 365L.
window_years	Integer. Width of each validation window in years. Default 5L.
min_train_years	Integer. Minimum number of training years before the first validation window. Default 10L.
n_boot	Integer. Bootstrap years for covariate marginalization within each window. Default 200L.
interactions	Named list of interactions passed to build_cov_annual. Default list().
year_col	Character. Name of the year column. Default "year".
min_obs_year	Integer. Minimum observations in a validation year for it to be included. Default as.integer(n_obs * 0.8).
verbose	Logical. Print progress. Default TRUE.

Value

A list with three elements:

results	Data frame with one row per validation year, containing the observed annual maximum, PIT value, and exceedance indicators for each return period.
binom_tests	Data frame with binomial test results for each TR.
ks_test	Data frame with KS test result for PIT calibration, or NULL if fewer than 5 validation years had events.

---

Compute BIC for a fitted nhpp_fit model

Description

Compute BIC for a fitted nhpp_fit model

Usage

bic_nhpp(fit, tol = 0.01)

Arguments

fit	An nhpp_fit object.
tol	Numeric. Coefficients smaller than this are counted as zero for the active parameter count. Default 1e-2.

Value

Numeric scalar. BIC value.

---

Parametric bootstrap confidence intervals for model coefficients

Description

Simulates R bootstrap samples, refits at the original penalty and lambda, and returns empirical quantile CIs for each coefficient.

Usage

bootstrap_coef(fit, data, R = 200L, level = 0.95, seed = 42L, verbose = TRUE)

Arguments

fit	An nhpp_fit object.
data	The data frame used to fit fit. Must contain column y and all covariates.
R	Integer. Number of bootstrap replicates. Default 200L.
level	Numeric. Confidence level. Default 0.95.
seed	Integer. Random seed. Default 42L.
verbose	Logical. Print progress. Default TRUE.

Value

A data frame with columns parameter, estimate, CI_low, CI_high, n_ok. Only parameters with non-negligible estimates (|estimate| > 1e-4) are returned.

---

Parametric bootstrap confidence intervals for return levels

Description

Simulates R bootstrap samples from the fitted model, refits at the original penalty and lambda, recomputes return levels via marginalize, and returns empirical quantile CIs.

Usage

bootstrap_rl(
  fit,
  data,
  TRs = c(2, 5, 10, 20, 50, 100),
  R = 200L,
  approach = "C",
  marginalize_args = list(),
  level = 0.95,
  seed = 42L,
  verbose = TRUE
)

Arguments

fit	An nhpp_fit object.
data	The data frame used to fit fit. Must contain column y and all covariates.
TRs	Numeric vector of return periods. Default c(2,5,10,20,50,100).
R	Integer. Number of bootstrap replicates. Default 200L.
approach	Character. Which marginalization approach to use for each replicate: "A", "B", or "C". Default "C".
marginalize_args	Named list of additional arguments passed to marginalize (e.g. n_boot, seed, scenarios, interactions).
level	Numeric. Confidence level. Default 0.95.
seed	Integer. Random seed. Default 42L.
verbose	Logical. Print progress. Default TRUE.

Value

A data frame with columns TR, RL_est, CI_low, CI_high, n_ok (number of successful replicates).

---

Build a covariate data frame for marginalization

Description

Constructs a data frame with n_obs rows containing all columns required by a fitted nhpp_fit model. Seasonality columns (cos1, sen1, cos2, sen2) are computed automatically from n_obs. Any other required column is filled from cov_vals, or set to zero with a warning if absent.

Usage

build_cov_annual(
  fit,
  cov_vals = list(),
  n_obs = 365L,
  period = 365.25,
  interactions = list()
)

Arguments

fit	An nhpp_fit object.
cov_vals	Named list of covariate values. Each element is either a scalar (replicated to n_obs rows) or a vector of length n_obs.
n_obs	Integer. Number of rows (time points) to generate. Typically 365L for one year of daily data.
period	Numeric. Period for the seasonal harmonics in days. Default 365.25.
interactions	Named list of length-2 character vectors declaring interaction columns to compute. Each element is c("col_A", "col_B") and the interaction column is their product. The name of the list element becomes the column name. Example: list(AB = c("A", "B")) adds column AB = A * B.

Value

A data frame with n_obs rows and all columns required by fit.

---

Build design matrices for the NHPP point process model

Description

Build design matrices for the NHPP point process model

Usage

build_design_matrices(
  df,
  loc_vars = NULL,
  scale_vars = NULL,
  shape_vars = NULL,
  free_vars = NULL
)

Arguments

df	A data frame containing all required columns.
loc_vars	Character vector of covariate names for the location (mu) parameter.
scale_vars	Character vector of covariate names for the scale (sigma) parameter.
shape_vars	Character vector of covariate names for the shape (xi) parameter.
free_vars	Character vector of column names that should never be penalized (e.g. seasonality terms like c("cos1", "sen1")). Defaults to NULL.

Value

A list with elements:

X_mu	Design matrix for location.
X_sigma	Design matrix for scale.
X_xi	Design matrix for shape.
idx_pen_mu	Integer indices of penalized columns in X_mu.
idx_pen_sigma	Integer indices of penalized columns in X_sigma.
idx_pen_xi	Integer indices of penalized columns in X_xi.

---

Fit a non-homogeneous point process model for extremes

Description

Fits a peaks-over-threshold point process model via penalized maximum likelihood with BFGS optimization and exact analytical gradients.

Usage

fit_nhpp(
  df,
  threshold,
  loc_vars = NULL,
  scale_vars = NULL,
  shape_vars = NULL,
  free_vars = NULL,
  penalty = c("none", "lasso", "ridge", "elnet"),
  alpha = 0.5,
  lambda = "bic",
  penalize_shape = TRUE,
  obs_per_year = 365.25,
  maxit = 10000L,
  calc_hessian = FALSE,
  verbose = TRUE
)

Arguments

df	A data frame containing the response and all covariates. Must have a column named y (the observations).
threshold	Numeric scalar. The extreme value threshold u.
loc_vars	Character vector of covariate names for the location parameter. NULL for stationary location.
scale_vars	Character vector of covariate names for the scale parameter. NULL for stationary scale.
shape_vars	Character vector of covariate names for the shape parameter. NULL for stationary shape.
free_vars	Character vector of covariate names that are never penalized (e.g. seasonality terms). NULL by default.
penalty	Character. Penalty type: "none" (pure MLE), "lasso" (L1), "ridge" (L2), or "elnet" (elastic net, requires alpha).
alpha	Numeric in [0, 1]. Elastic-net mixing parameter. Only used when penalty = "elnet". 1 = LASSO, 0 = ridge. Scalar or named vector c(mu = , sigma = , xi = ).
lambda	Numeric scalar or named vector c(mu=, sigma=, xi=), or "bic" to select automatically via a two-phase BIC grid search. Ignored when penalty = "none".
penalize_shape	Logical. Penalize shape parameter covariates? Default TRUE.
obs_per_year	Numeric. Observations per year. E.g. 365.25 for daily data, 52 for weekly. Default 365.25.
maxit	Integer. Maximum optimizer iterations. Default 10000L.
calc_hessian	Logical. Compute Hessian at solution? Needed for delta-method standard errors. Default FALSE.
verbose	Logical. Print progress during BIC grid search and convergence warnings. Default TRUE.

Value

An object of class nhpp_fit.

---

Fit a generic VAR generator over a model's active covariates

Description

Deseasonalizes each active covariate column in data (regressing on cos1, sen1, cos2, sen2), then fits a multivariate VAR to the standardized residuals. No covariate names are hardcoded: whatever active_covariates returns (or whatever you pass in vars) is treated as a final, ready-to-model column.

Usage

fit_var_generator(fit, data, vars = NULL, period = 365.25, lag_max = NULL)

Arguments

fit	An nhpp_fit object.
data	Data frame used to fit fit (or any data frame containing the same covariate columns, plus seasonal harmonics if you already have them).
vars	Character vector of covariate names to model. Default NULL: uses active_covariates(fit), intersected with names(data).
period	Numeric. Seasonal period in observations. Default 365.25.
lag_max	Integer. Max VAR lag considered by VARselect. Default NULL: min(5, floor(n / (3*K))).

Value

An object of class nhpp_var_generator, or NULL (with a warning) if the model has no active covariates.

---

Check if an object is an nhpp_fit

Description

Check if an object is an nhpp_fit

Usage

is_nhpp_fit(x)

Arguments

x	Any R object.

Value

Logical.

---

Compute unconditional return levels by marginalizing over covariates

Description

Given a fitted nhpp_fit model, computes return levels by integrating out covariate uncertainty under one or more approaches:

Usage

marginalize(
  fit,
  data,
  TRs = c(2, 5, 10, 20, 50, 100),
  n_obs = 365L,
  approaches = c("A", "C"),
  scenarios = NULL,
  mc_sample = NULL,
  interactions = list(),
  year_col = "year",
  n_boot = 500L,
  seed = 2024L,
  tol_root = 1e-04,
  z_hi = NULL
)

Arguments

fit	An nhpp_fit object.
data	The data frame used to fit fit. Required for approach C and for computing z_hi. Must contain a column year (or the name given in year_col) and all active covariates.
TRs	Numeric vector of return periods in years. Default c(2, 5, 10, 20, 50, 100).
n_obs	Integer. Observations per year. Default 365L.
approaches	Character vector. Which approaches to run. Any subset of c("A", "B", "C"). Default c("A", "C").
scenarios	Named list of covariate scenarios for approach A. Each element is itself a named list of scalar covariate values, passed to build_cov_annual. If NULL, a single scenario with all covariates set to zero is used.
mc_sample	List of data frames for approach B. Each element is one simulated year of covariates (n_obs rows). Required if "B" %in% approaches.
interactions	Named list of interactions passed to build_cov_annual. Default list().
year_col	Name of the year column in data. Default "year".
n_boot	Integer. Number of bootstrap years for approach C. Default 500L.
seed	Integer. Random seed for approach C. Default 2024L.
tol_root	Numeric. Root-finding tolerance. Default 1e-4.
z_hi	Numeric. Upper search bound for return levels. If NULL, set to 3 * max(data$y, na.rm = TRUE).

Details

A — conditional

Covariates fixed at user-specified scenarios (e.g. quantiles of observed distributions). Fast; useful for sensitivity analysis.

B — parametric

Covariates drawn from a user-supplied Monte Carlo sample (e.g. from a fitted VAR or any stochastic generator). The sample is a list of n_obs-row data frames, one per simulated year.

C — empirical

Block bootstrap over observed covariate years. Resamples whole years from data to preserve temporal structure.

Value

A data frame with columns approach, scenario, TR, RL.

---

Extract the number of exceedances from a fitted model

Description

Extract the number of exceedances from a fitted model

Usage

n_exceedances(fit, y)

Arguments

fit	An nhpp_fit object.
y	Numeric vector of observations used to fit the model.

Value

Integer. Number of observations exceeding the threshold.

---

Analytical gradient of the penalized negative log-likelihood

Description

Analytical gradient of the penalized negative log-likelihood

Usage

pp_grad(
  par,
  dm,
  y,
  threshold,
  lambda = 0.1,
  alpha = 0.5,
  pen_xi = TRUE,
  eps_l1 = 1e-10,
  obs_per_year = 365.25
)

Arguments

par	Numeric vector of parameters: c(beta_mu, beta_sigma, beta_xi).
dm	Design matrix list from build_design_matrices.
y	Numeric vector of observations.
threshold	Numeric scalar. The extreme value threshold u.
lambda	Penalty strength. Either a scalar or named vector c(mu=, sigma=, xi=).
alpha	Elastic-net mixing parameter in [0,1]. 1 = LASSO, 0 = ridge. Either a scalar or named vector c(mu=, sigma=, xi=).
pen_xi	Logical. Should the shape parameter covariates be penalized?
eps_l1	Small positive constant for smooth L1 approximation.
obs_per_year	Number of observations per year (e.g. 365.25 for daily).

Value

Numeric vector of length length(par).

---

Penalized negative log-likelihood for the NHPP model

Description

Penalized negative log-likelihood for the NHPP model

Usage

pp_nllh(
  par,
  dm,
  y,
  threshold,
  lambda = 0.1,
  alpha = 0.5,
  pen_xi = TRUE,
  eps_l1 = 1e-10,
  obs_per_year = 365.25
)

Arguments

par	Numeric vector of parameters: c(beta_mu, beta_sigma, beta_xi).
dm	Design matrix list from build_design_matrices.
y	Numeric vector of observations.
threshold	Numeric scalar. The extreme value threshold u.
lambda	Penalty strength. Either a scalar or named vector c(mu=, sigma=, xi=).
alpha	Elastic-net mixing parameter in [0,1]. 1 = LASSO, 0 = ridge. Either a scalar or named vector c(mu=, sigma=, xi=).
pen_xi	Logical. Should the shape parameter covariates be penalized?
eps_l1	Small positive constant for smooth L1 approximation.
obs_per_year	Number of observations per year (e.g. 365.25 for daily).

Value

Scalar. The penalized negative log-likelihood value.

---

Compute time-varying GEV parameters from a fitted model

Description

Given an nhpp_fit object and a data frame of covariate values, returns the implied location, scale, and shape parameters at each row.

Usage

predict_params(fit, newdata = NULL)

Arguments

fit	An object of class nhpp_fit.
newdata	A data frame with one row per time point. Must contain all columns that appear in the model's design matrices (except the intercept). If NULL, returns the fitted values stored in fit$fitted.

Value

A list with three numeric vectors of length nrow(newdata):

mu	Location parameter.
sigma	Scale parameter (always positive).
xi	Shape parameter.

---

Wide-format return level table from marginalize() output

Description

Converts the long-format output of marginalize into a wide table with one row per scenario and one column per return period.

Usage

rl_table(marg_result)

Arguments

marg_result

Data frame returned by marginalize.

Value

A wide data frame.

---

Simulate stationary covariate trajectories from a VAR generator

Description

Simulate stationary covariate trajectories from a VAR generator

Usage

simulate_covariates(generator, n_mc, n_obs = 365L, burn_in = 300L, seed = NULL)

Arguments

generator	Object from fit_var_generator. If NULL, returns NULL (stationary/no-covariate model).
n_mc	Integer. Number of simulated years.
n_obs	Integer. Observations per simulated year. Default 365L.
burn_in	Integer. Burn-in to discard transient VAR dynamics. Default 300L.
seed	Integer. Random seed. Default NULL (not set).

Value

A list of length n_mc, each element an n_obs-row data frame with one column per active covariate - directly usable as mc_sample in marginalize (approach B).

---

Summarise a fitted nhpp_fit model

Description

Prints a structured summary of a fitted nhpp_fit object, including the penalty used, active coefficients, and basic model diagnostics.

Usage

## S3 method for class 'nhpp_fit'
summary(object, tol = 1e-04, ...)

Arguments

object	An nhpp_fit object.
tol	Numeric. Coefficients smaller than this in absolute value are treated as zero. Default 1e-4.
...	Ignored.

Value

Invisibly returns the input nhpp_fit object.

---