Skip to content

API Overview

Choose an entrypoint by the quantity you want to estimate. EVI and EI estimators are public through unibm.evi and unibm.ei. UniBM also exposes six core workflow functions directly from unibm. These convenience imports refer to the same function objects; their placement does not select a default estimator for every task. See the version note below when using PyPI 0.1.0.

Estimator map

Task Public entrypoints
EVI from block-maxima quantiles, including the median estimate_evi_quantile
Scaling from block-maxima means or modes estimate_target_scaling with target="mean" or "mode"
EVI comparator estimators estimate_hill_evi, estimate_pickands_evi, estimate_dedh_moment_evi, estimate_max_spectrum_evi
EI pooled across a stable block-size window prepare_ei_bundle, then estimate_pooled_bm_ei; FGLS also requires bootstrap_bm_ei_path
Native Northrop or BB EI at a selected block size estimate_native_bm_ei
EI from threshold exceedances estimate_ferro_segers, estimate_k_gaps
Design-life levels and their intervals estimate_design_life_level, estimate_design_life_level_interval
Quantile at a specified block size predict_block_quantile
Empirical ranks empirical_cdf

The EVI namespace and EI namespace contain the full signatures, result types, bootstrap, selection, and plotting helpers. Estimator-specific assumptions and CI methods are documented there; bootstrap is not a common default for all estimators. Mean/mode scaling fits require their own scaling assumptions and cannot be passed to the quantile design-life helpers.

Defaults and explicit choices

EVI

estimate_evi_quantile defaults to quantile=0.5 (median) and sliding=True. regression has no default: choose "OLS", "FGLS", or "AUTO" explicitly.

  • With "FGLS" or "AUTO", omitting bootstrap_reps uses adaptive bootstrap when no bootstrap_result is supplied. An integer requests a fixed budget.
  • "OLS" does not bootstrap. "FGLS" requires usable covariance; "AUTO" permits missing internally generated covariance to fall back to OLS.
  • Omitted covariance_shrinkage=None resolves to 0.73 for FGLS/AUTO. OLS rejects an explicit shrinkage value because it does not use covariance weights. random_state defaults to 0.
  • Supply only one grid source: min_block_size/max_block_size/num_step, an explicit block_sizes, or a reused curve. Reused curves reject additional grid arguments; explicit grids reject generation controls.
  • Automatic EVI bounds are max(5, ceil(n**(1/3))) through min(floor(n**(1 - 1/e)), floor(n/17)). An infeasible range raises; a feasible range with fewer than five positive summaries cannot select a window.
  • Explicit grid bounds are valid integer sizes with max_block_size strictly greater than min_block_size. They are not silently expanded. Explicit EVI super_block_size is honored unchanged when valid; see bootstrap length rules.

Thus, estimate_evi_quantile(sample, regression="FGLS") selects median + sliding + adaptive FGLS. The lower-level bootstrap backbone and multi-target helpers instead take fixed integer repetition budgets. See the EVI example and covariance reuse example.

EI

There is no single default EI estimator. Native BM, pooled BM, Ferro--Segers, and K-gaps are separate entrypoints. The pooled workflow is:

  1. Call prepare_ei_bundle with an explicit allow_zeros choice appropriate to the observation clock. It prepares Northrop and BB paths with both block schemes by default. path_keys=(("bb", True),) prepares only BB-sliding; path_keys=() skips BM preparation for threshold-only use. Its threshold candidates default to (0.90, 0.95). Its automatic BM grid uses max(5, ceil(n**(1/3))) through min(floor(sqrt(n)), floor(n/17)); EVI retains the upper exponent 1 - 1/e. Bounds are never widened to satisfy an estimator's minimum window size.
  2. For FGLS, call bootstrap_bm_ei_path with explicit base_path, sliding, block_sizes, and allow_zeros. Its reps defaults to "adaptive".
  3. Call estimate_pooled_bm_ei with explicit base_path="northrop" or "bb", sliding=True or False, and regression="OLS" or "FGLS". FGLS requires the matching bootstrap result; OLS rejects one and also rejects an explicit covariance_shrinkage.

The adaptive bootstrap monitors a pooled fit with shrinkage 0.37 by default (covariance_shrinkage=None). An explicit value only configures that adaptive monitor and is rejected with fixed integer reps. Both bootstrap modes return the raw sample covariance; estimate_pooled_bm_ei applies shrinkage when fitting FGLS, also defaulting to 0.37. The bootstrap seed defaults to 0. Native BM and threshold estimators do not automatically run this covariance bootstrap. See the complete pooled EI example.

For fixed-b native inference, prepare a single block_sizes=[b] and the required path_keys. No stable-window selection is performed, and stable_window is None. Multilevel native fits retain the smallest size in their selected window. use_adjusted_chandwich=True is supported only for native Northrop; BB rejects it.

The repository application workflow selects quantile-sliding adaptive FGLS for EVI and both Northrop-sliding and BB-sliding adaptive FGLS for pooled EI. These are application configurations, not additional defaults imposed by the package.

Design-life levels

estimate_design_life_level takes an existing quantile-based fit and an explicit horizon years. It does not refit the data, bootstrap, or select an EI estimator. It maps the fitted scaling law to the horizon's observation count:

  • observations_per_year=365.25 is a daily-clock default. Set it to match the fitted series' actual observation clock.
  • fit.quantile determines the probability; there is no separate post-fit tau argument. A median fit yields the median of the horizon maximum, not a return level whose return period equals years.
  • estimate_design_life_level_interval uses the fit's coefficient covariance for a log-scale delta-method interval, nominally 95% with z_crit=1.96. This is a conditional interval for the fitted quantile, not a prediction interval for a future maximum.

Adaptive EVI and EI bootstrap check precision at 128, 256, 512, 768, and 1024 draws. Reaching the cap can leave bootstrap_precision_met=False. EVI's precision diagnostic monitors the EVI estimate and its CI endpoints, not the extrapolated design-life levels. See Reading Returned Objects.

API migration

The 0.3.1 source checkout preserves the 0.3.0 public API and inference defaults. Version 0.3.0 introduced the following API changes from 0.2.0. Review the current defaults above as well:

Earlier call Current call or behavior
Design-life helpers with tau=fit.quantile Omit tau; choose the quantile when fitting.
Plot helpers with save=True, file_path=path Pass file_path=path; saving follows the path.
Plot helpers with save=False Omit both save and file_path to avoid saving.
OLS with covariance_shrinkage=... Omit shrinkage; it only applies to covariance-weighted fits.
Native BB with use_adjusted_chandwich=True Omit this Northrop-only adjustment.
Conflicting bounds, duplicated grid sources, or infeasible explicit bootstrap lengths Correct the arguments; these now raise ValueError.
Max-spectrum with min_scale_count < 3, a boolean, or a fractional value Supply an integer of at least 3.

Top-level convenience imports

Since 0.2.0, EVI estimation and EVI/EI bootstrap calls accept n_threads. Optional native kernels preserve the same public API. See thread budgets and native acceleration for defaults, nested parallelism, and the NumPy fallback. These additions are not in PyPI 0.1.0.

UniBM 0.3.x supports:

from unibm import (
    estimate_evi_quantile,
    prepare_ei_bundle,
    bootstrap_bm_ei_path,
    estimate_pooled_bm_ei,
    estimate_design_life_level,
    estimate_design_life_level_interval,
)

The EVI and pooled EI estimators return fit objects containing both the point estimate and its CI. Design-life point estimates and intervals remain separate calls. All six imports load lazily and resolve to the original subpackage functions. Comparator estimators and other helpers remain in the grouped namespaces above.

Version note: the four additional root imports were added in 0.2.0. Version 0.1.0 exports only estimate_evi_quantile and estimate_design_life_level at the root. On that release, import the other four functions as follows; these paths also remain supported in current versions:

from unibm.ei import prepare_ei_bundle, bootstrap_bm_ei_path, estimate_pooled_bm_ei
from unibm.evi import estimate_design_life_level_interval

unibm

Public UniBM package facade.

The package exposes the core EVI, pooled EI, and design-life workflows here. Grouped public namespaces unibm.evi and unibm.ei contain the full estimator and helper APIs; unibm.cdf provides empirical ranks. Repository benchmark, application, and orchestration code lives under scripts/, outside the installable package.

estimate_evi_quantile(vec, *, regression, quantile=0.5, sliding=True, block_sizes=None, num_step=None, min_block_size=None, max_block_size=None, bootstrap_reps=None, super_block_size=None, random_state=0, n_threads=None, plateau_points=5, curvature_penalty=DEFAULT_CURVATURE_PENALTY, covariance_shrinkage=None, curve=None, plateau=None, bootstrap_result=None)

Estimate EVI from a quantile of block maxima on a selected log-log plateau.

vec is a one-dimensional series with at least 32 finite observations. quantile lies strictly between zero and one. Zeros enter the block quantiles; only positive summaries enter the log regression. Sliding windows overlap, while disjoint windows discard the incomplete tail. Supply an increasing integer block_sizes grid or let num_step and the size bounds control its generation, but not both. A supplied curve owns its grid and cannot be combined with any grid arguments. plateau_points is the minimum window length. The selector scores windows across the full positive-summary grid; the supplied bounds are not narrowed before selection.

regression is explicit: OLS uses HC0 uncertainty; strict FGLS requires usable bootstrap covariance. AUTO permits an internally generated missing covariance to fall back to OLS, but never accepts malformed supplied covariance. The result records both requested policy and actual regression.

For FGLS/AUTO without a supplied bootstrap, omitted or "adaptive" reps check 128, 256, 512, 768, and 1024 draws. An integer requests a fixed budget. Adaptive precision monitors xi and its CI endpoints, not design-life levels. A cap warning retains the fit with bootstrap_precision_met=False. covariance_shrinkage=None resolves to the fixed 0.73 weight for FGLS/AUTO. OLS rejects an explicit shrinkage weight because it has no effect. n_threads=None chooses a CPU/workload-aware bootstrap pool (at most 8); a positive integer caps it, and 1 stays serial. This does not change BLAS settings. Callers with an outer process pool should allocate the inner cap. Random draws and adaptive stopping are independent of the thread count.

Supplied covariance must match the target, quantile, and block scheme; block-size labels permit full-grid covariance to serve a selected subset. Reuse remains the caller's responsibility for data identity. Intervals are conditional on the observed plateau and do not include selection uncertainty. Return a ScalingFit with xi in slope, a nominal 95% Wald interval, the full summary curve, selected window, and bootstrap diagnostics.

prepare_ei_bundle(vec, *, allow_zeros, block_sizes=None, path_keys=BM_PATH_KEYS, threshold_quantiles=(0.9, 0.95))

Prepare EI paths and a strictly increasing threshold grid without changing the clock.

vec must be a finite 1D series of at least 32 observations. Values must be positive unless allow_zeros=True; zeros are then retained at their original positions. The caller defines what one observation step represents.

block_sizes is an increasing integer grid from 2 through the sample size, or a generated grid from max(5, ceil(n**(1/3))) through min(floor(sqrt(n)), floor(n/17)) when omitted. The bounds are not expanded when too few levels remain for selection. path_keys selects unique (base_path, sliding) pairs; all four Northrop/BB and sliding/disjoint pairs are prepared by default. Use path_keys=() for threshold-only preparation, without a block grid or BM computation. A single supplied block size fixes native inference at that level without selecting a stable window. Otherwise selection requires at least four finite path levels.

Threshold quantiles must be strictly increasing and in (0, 1), defaulting to (0.90, 0.95). The bundle stores indices strictly above each empirical quantile; ties equal to the threshold are excluded. Estimators consume this order unless the caller requests a validated subset.

bootstrap_bm_ei_path(vec, *, allow_zeros, base_path, sliding, block_sizes, reps='adaptive', random_state=0, bootstrap_block_length=None, covariance_shrinkage=None, n_threads=None)

Bootstrap BM-EI covariance; default adaptive precision targets pooled theta and z.

Resample contiguous circular blocks of the observed series. The raw resampling length defaults to min(n, max(16, round(sqrt(n)))) and can be set with bootstrap_block_length; it is separate from the increasing block_sizes grid used to evaluate the EI path. random_state seeds NumPy's generator (default 0); None requests non-reproducible seeding. n_threads=None chooses at most 8 threads from CPU/workload size; a positive integer caps this pool and 1 stays serial. It does not modify BLAS settings. Outer parallel callers should allocate the inner cap. Batch/thread choices preserve draws, path order and adaptive stopping.

An explicit integer of at least two retains fixed-R sampling and rejects an explicit covariance_shrinkage. That parameter only controls the pooled fit monitored by adaptive stopping; None resolves to 0.37. Neither mode shrinks the returned sample covariance. Adaptive precision is conditional on the original stable window and the monitoring shrinkage. Checkpoints are 128, 256, 512, 768, and 1024. The target vector includes theta and its CI endpoints plus the unconstrained z fit and endpoints, so the theta=1 boundary cannot hide Monte Carlo error. The cap retains the result with a warning and bootstrap_precision_met=False if tolerance is unmet. This flag measures Monte Carlo precision, not confidence-interval coverage.

The returned in-memory dictionary contains full-grid covariance, path draws, block-size labels, estimator identity, and sampling/precision metadata. Pass it to estimate_pooled_bm_ei with matching data, path, and block scheme. Reusing adaptive precision metadata also requires matching the monitored shrinkage (default 0.37). This function does not write intermediate files. allow_zeros declares whether observed zeros are legal; non-finite inputs are always rejected rather than removed from the observation clock.

estimate_pooled_bm_ei(bundle, *, base_path, sliding, regression, bootstrap_result=None, covariance_shrinkage=None)

Estimate theta by pooling an observed BM path over a stable window.

bundle comes from prepare_ei_bundle; base_path is "northrop" or "bb" and sliding chooses the prepared block scheme. Each finite path level in the inclusive stable window contributes to the pooled fit. The fitted intercept is constrained to z = log(1 / theta) >= 0. standard_error is delta-transformed to the theta scale, while z_standard_error retains the regression-scale uncertainty.

regression must be OLS or FGLS. OLS rejects a bootstrap result; FGLS requires covariance from the matching base path and sliding/disjoint scheme and never falls back to OLS. Full-grid covariance is subset by block-size labels. Omitted shrinkage uses 0.37 for FGLS. OLS rejects an explicit shrinkage value; it estimates variance from between-level residuals and does not model their dependence. A fixed-b path requires native inference. Return an ExtremalIndexEstimate with a nominal 95% interval and retained path, covariance, and bootstrap diagnostics.

Adaptive precision metadata is retained only when the bootstrap's checked window and shrinkage match this fit. The log-scale interval is clipped to the legal theta upper boundary of 1 and remains conditional on the selected window; it is not a post-selection or bootstrap-percentile interval.

estimate_design_life_level(fit, years, *, observations_per_year=365.25)

Map one fitted quantile-scaling law to horizon-maximum quantiles.

The design block size is ceil(years * observations_per_year) on the caller's observation clock. This does not split observations by calendar year or refit annual maxima. The probability is fixed by fit.quantile. A median fit therefore gives a median design-life level, not a return level whose waiting time equals years.

Accept a positive finite scalar or 1D years array. Return a float for a scalar horizon and an aligned array otherwise. Predictions outside the fitted block-size window assume the same power law continues to hold.

estimate_design_life_level_interval(fit, years, *, observations_per_year=365.25, z_crit=Z_CRIT_95)

Return delta-method design-life intervals on the original response scale.

The fitted scaling law implies

log D(T) = alpha + xi * log(b_T),

so the log-scale variance follows from the fitted 2x2 coefficient covariance matrix cov_beta. The returned interval is pointwise and does not include any post-selection or model-class uncertainty beyond that covariance matrix.

years is a positive finite scalar or 1D array; the probability is fixed by fit.quantile. Return (lower, upper) as floats for a scalar or aligned arrays otherwise. The default z_crit=1.96 gives nominal 95% normal intervals on the log scale; these are intervals for the fitted quantile, not prediction intervals for future observed maxima.