extremeloss

Extreme-value tail estimation for large claims: peaks-over-threshold with the generalized Pareto distribution (GPD), tail analytics, and large-claim loading. numpy and scipy only; matplotlib is optional via the plot extra, and lossmodels integration via the splice extra.

The package covers threshold selection, GPD estimation, and the analytics built on a fitted tail — return levels, exceedance probabilities, and excess-layer charges — plus integration helpers for splicing an empirical body to a fitted tail. It composes with lossmodels and the pooling primitives in actuarialpy.

Empirical tail measures follow the ecosystem VaR/TVaR estimators, and simulation-backed quantities accept the shared rng argument — see Conventions.

See the API reference below for the full surface; each object’s docstring carries its own usage.

API reference

class BootstrapResult(estimate: float, bootstrap_estimates: ndarray, method: str = 'percentile', ci: tuple[float, float] | None = None, stderr: float | None = None, alpha: float | None = None)

Bases: object

Bootstrap uncertainty summary for a scalar statistic.

class GEVFit(xi: float, loc: float, scale: float, n_blocks: int, block_size: int | None = None, fit_method: str = 'mle', covariance: ndarray | None = None)

Bases: object

Fitted generalized extreme value distribution for block maxima.

class GPDFit(threshold: float, xi: float, beta: float, exceedance_fraction: float, n_exceedances: int, fit_method: str = 'mle', covariance: ndarray | None = None)

Bases: object

Fitted generalized Pareto distribution above a threshold.

class GPDTail(threshold: float, xi: float, beta: float)

Bases: object

Conditional generalized-Pareto tail on [threshold, inf), for splicing.

A thin distribution object wrapping scipy.stats.genpareto with shape xi, scale beta and location threshold. Unlike GPDFit (which carries the exceedance rate and reports unconditional VaR/TVaR), this represents the tail conditional on X > threshold: cdf(threshold) == 0 and the density integrates to one over [threshold, inf). It exposes the cdf / pdf / sample / quantile / mean / variance interface that lossmodels.SplicedSeverity consumes as a tail. Moments raise when they do not exist (xi >= 1 for the mean, xi >= 1/2 for the variance), mirroring heavy-tailed severities.

classmethod from_fit(fit: GPDFit) → GPDTail

Build a conditional tail from a fitted GPDFit.

class TailEstimateResult(estimate: float, method: str, stderr: float | None = None, ci: tuple[float, float] | None = None, n: int | None = None, effective_n: float | None = None, threshold: float | None = None, quantile: float | None = None, diagnostics: dict[str, ~typing.Any] = <factory>)

Bases: object

Container for tail-estimation results.

class ThresholdScan(thresholds: ndarray, mean_excess: ndarray, xi: ndarray, beta: ndarray, n_exceedances: ndarray)

Bases: object

Threshold-diagnostic results across a grid of thresholds.

empirical_tvar(losses, q)

Empirical TVaR via the average-quantile (Acerbi-Tasche) plug-in.

Implements TVaR_q = (1/(1-q)) * integral_q^1 VaR_u du exactly on the empirical distribution: with sorted losses and k = ceil(n*q),

TVaR_q = [ sum_{i>k} x_(i) + x_(k) * (k - n*q) ] / (n * (1 - q)).

Correct in the presence of ties/atoms and always >= empirical_var. Ecosystem-standard estimator shared with risksim and lossmodels.

q may be scalar (returns float) or array-like (returns array).

empirical_var(losses, q)

Empirical VaR: the order statistic x_(ceil(n*q)).

Implements VaR_q = inf{x : F(x) >= q} on the empirical distribution (identical to np.quantile(..., method="inverted_cdf")). This is the ecosystem-standard estimator shared with risksim and lossmodels; it serves as the crude-Monte-Carlo baseline that the variance-reduced estimators in this subpackage are compared against.

q may be scalar (returns float) or array-like (returns array).

estimate_tail_probability(data, threshold: float, *, size: int | None = None, alpha: float = 0.05) → TailEstimateResult

Estimate P(X > threshold) from simulated or observed losses.

estimate_tail_probability_cmc(conditional_probabilities, *, threshold: float | None = None, alpha: float = 0.05) → TailEstimateResult

Estimate an exceedance probability from conditional exceedance probabilities.

Parameters:

• conditional_probabilities – Samples of P(X > u | Y) from a conditioning variable Y.

• threshold – Optional tail threshold associated with the conditional probabilities.

estimate_tvar_cmc(conditional_tail_expectations, *, q: float, threshold: float | None = None, alpha: float = 0.05) → TailEstimateResult

Estimate TVaR from conditional expectations of tail losses.

conditional_tail_expectations should contain draws of E[X | X >= VaR_q, Y] or another conditionally unbiased TVaR contribution.

estimate_tvar_is(losses, weights, q: float) → TailEstimateResult

Weighted TVaR under the ecosystem average-quantile convention.

Implements the weighted Acerbi-Tasche plug-in for TVaR_q = (1/(1-q)) * integral_q^1 VaR_u du: with values sorted, weights normalized, cumulative weights W_i and k the weighted-VaR index,

TVaR_q = [ sum_{i>k} w_i x_i + x_k (W_k - q) ] / (1 - q).

The atom at VaR contributes only the weight mass above level q, which keeps the estimator coherent with ties and makes it reduce exactly to empirical_tvar when all weights are equal.

fit_gpd(excesses, threshold: float = 0.0, method: str = 'mle') → GPDFit

Fit a generalized Pareto distribution to excess losses.

fit_spliced_gpd(body, data, *, threshold: float, weight: float | None = None)

Fit a GPD tail above threshold (peaks-over-threshold) and splice it onto body, returning a lossmodels.SplicedSeverity.

Parameters:

• body (severity model) – Any fitted body severity (e.g. a lossmodels Lognormal).

• data (array-like) – Loss sample used to fit the tail and, by default, to set the body mass.

• threshold (float) – Peaks-over-threshold cutoff u.

• weight (float, optional) – Body mass P(X <= u). Defaults to 1 - exceedance_fraction from the POT fit (the empirical fraction at or below the threshold), consistent with the fitted exceedance rate.

• package. (Requires the lossmodels)

splice_gpd_tail(body, fit, *, weight: float | None = None)

Splice an already-fitted GPD tail (a GPDFit) onto body.

Returns a lossmodels.SplicedSeverity whose body is body (any fitted body severity) and whose tail is the conditional GPD of fit above its threshold. The mixing weight defaults to the body mass implied by the fit, 1 - fit.exceedance_fraction (i.e. P(X <= threshold)).

sample_lossmodel(model, size: int) → ndarray

Sample losses from a lossmodels-style severity or aggregate model.