Fit a generalised Pareto distribution to threshold exceedances.

Use this first when asked how heavy a tail is. The shape parameter is the headline number: above zero means a heavy tail with no upper bound, near zero means exponential decay, below zero means a finite worst case.

Returns: str: JSON with keys threshold, shape, scale, n_observations, n_exceedances, exceedance_rate, log_likelihood and an interpretation string.

Estimate VaR and Expected Shortfall by three methods for comparison.

The EVT estimate extrapolates beyond the observed sample, the historical estimate cannot, and the Gaussian estimate is a deliberately naive baseline. A large gap between the EVT and Gaussian figures is the quantitative case for using a tail model at all.

Returns: str: JSON with an evt object (var, es, shape, threshold), historical and gaussian objects, plus evt_vs_gaussian_ratio and the confidence level. Individual methods report a note instead of a number when undefined.

Estimate the level exceeded once per return period.

This is the same POT quantile as VaR in a different vocabulary: a 100-period return level equals the 99% VaR on data at that frequency. Use it when the question is phrased as a 1-in-N event rather than a confidence level.

Returns: str: JSON with return_period, return_level, equivalent_var_confidence, threshold and shape.

Backtest a VaR model out of sample with Kupiec and Christoffersen tests.

Each forecast uses only trailing data, so the result is a genuine out-of-sample assessment of whether breaches occur at the right rate and without clustering. This is the evidence a model validation report needs.

Returns: str: JSON with n_forecasts, n_breaches, breach_rate, expected_breach_rate, the Kupiec, Christoffersen and conditional coverage statistics with p-values, and a plain-language verdict.

Refit across candidate thresholds to test whether the tail fit is stable.

Threshold choice is the main judgement call in a POT analysis. Call this before trusting a single fit: if the shape parameter drifts steadily with the threshold, the estimate is not yet in the asymptotic regime.

Returns: str: JSON with a scan list (one record per threshold, each with quantile, threshold, shape, scale, modified_scale, n_exceedances), the shape_range across the scan, and a stability verdict.

Read one numeric column from a local CSV so a series can be analysed.

Call this before the analysis tools when the data lives in a file rather than in the conversation. Non-numeric and empty cells are skipped and counted so data quality is visible.

Returns: str: JSON with values (the parsed numbers), count, skipped_rows and truncated.