EVI Namespace

The exported unibm.evi namespace groups the severity-side workflow: block extraction and summaries, plateau selection, covariance-aware fitting, design-life-level helpers, plotting helpers, and the public comparator families that remain part of the public package surface.

Start with estimate_evi_quantile for the median/quantile path or estimate_target_scaling for mean and mode summaries. A custom block_sizes grid must contain unique, strictly increasing integers between 2 and the sample size; it is not silently sorted or truncated. Quantile targets require a finite, non-boolean value strictly between 0 and 1.

FGLS covariance reuse must match the summary target, quantile, and sliding/disjoint scheme; a supplied plateau must match its curve slice. See Worked Examples for a complete reuse call and Reading Returned Objects for actual-regression and adaptive-R metadata.

evi

Canonical EVI-facing UniBM subpackage.

DEFAULT_MIN_DISJOINT_BLOCKS = 17 module-attribute

DEFAULT_COVARIANCE_SHRINKAGE = 0.73 module-attribute

DEFAULT_CURVATURE_PENALTY = 2.0 module-attribute

Z_CRIT_95 = 1.96 module-attribute

ThresholdWindow = SelectionWindow module-attribute

__all__ = ['BlockSummaryBootstrapBackbone', 'BlockSummaryCurve', 'DEFAULT_COVARIANCE_SHRINKAGE', 'DEFAULT_CURVATURE_PENALTY', 'DEFAULT_MIN_DISJOINT_BLOCKS', 'ExternalXiEstimate', 'PlateauWindow', 'ScalingFit', 'SelectionWindow', 'ThresholdWindow', 'Z_CRIT_95', 'block_maxima', 'block_summary_curve', 'build_block_summary_bootstrap_backbone', 'candidate_max_spectrum_scales', 'candidate_tail_counts', 'circular_block_summary_bootstrap', 'circular_block_summary_bootstrap_multi_target', 'estimate_sample_mode', 'estimate_dedh_moment_evi', 'estimate_design_life_level', 'estimate_design_life_level_interval', 'estimate_evi_quantile', 'estimate_hill_evi', 'estimate_max_spectrum_evi', 'estimate_pickands_evi', 'estimate_target_scaling', 'evaluate_block_summary_bootstrap_backbone', 'generate_block_sizes', 'predict_block_quantile', 'plot_scaling_fit', 'select_penultimate_window', 'select_stable_integer_window', 'summarize_block_maxima', 'target_stability_summary', 'wald_confidence_interval'] module-attribute

BlockSummaryBootstrapBackbone dataclass

Cached maxima and common segment draws for resampling summary targets.

segment_draws has shape (replicates, segments). Each maxima bank has shape (segments, maxima_per_segment) for its block size. Reusing the backbone makes different summary targets share the same resampled data.

BlockSummaryCurve dataclass

Aligned block-size summaries, including values excluded from log fitting.

All array fields share the full grid length. positive_mask identifies finite, strictly positive summaries with nonzero counts; filtered and log properties use that mask without changing the stored full arrays.

positive_block_sizes property

Return block sizes whose summaries pass positive_mask.

positive_values property

Return finite positive summaries selected for log-log fitting.

positive_counts property

Return maxima counts aligned with the positive summary subset.

log_block_sizes property

Return natural logs of the block sizes in the positive subset.

log_values property

Return natural logs of the positive block-summary values.

PlateauWindow dataclass

Selected contiguous slice of the positive-summary log-log curve.

start is inclusive and stop exclusive. mask indexes the full positive subset, while x and y contain only the selected slice. A lower score indicates the preferred window under the selection rule.

ScalingFit dataclass

Fitted log-summary intercept, slope, uncertainty, and selection diagnostics.

cov_beta orders coefficients as (intercept, slope). The slope is the headline EVI estimate when the chosen summary obeys the assumed scaling law. confidence_interval is its nominal 95% Wald interval conditional on the selected plateau; it omits window-selection and model uncertainty. regression_policy records the request, while regression and ci_variant describe the fit actually used. bootstrap_precision_met reports Monte Carlo precision, not statistical interval coverage.

block_sizes property

Return all positive-summary block sizes, including those outside the plateau.

counts property

Return maxima counts for all positive summaries, before plateau selection.

values property

Return all positive summary values, before plateau selection.

log_block_sizes property

Return natural-log block sizes for all positive summaries.

log_values property

Return natural-log summary values for all positive summaries.

plateau_mask property

Return the plateau mask aligned with the positive-summary subset.

plateau_block_sizes property

Return only the block sizes used in the selected regression window.

plateau_bounds property

Return the first and last selected block sizes, both inclusive.

ExternalXiEstimate dataclass

Selected tail-index estimate with its retained finite diagnostic path.

selected_level is a tail count or start-scale exponent according to tuning_axis. confidence_interval is a nominal 95% Wald interval using the method's SE; it does not propagate automatic window selection. The ci_method label describes construction, not a coverage guarantee.

selected_k property

Alias for selected_level; a scale-based estimator still returns a scale.

path_k property

Alias for path_level without converting scale exponents to tail counts.

SelectionWindow dataclass

Selected stable window on one integer-indexed estimator path.

generate_block_sizes(n_obs, num_step=None, min_block_size=None, max_block_size=None, geom=True, min_disjoint_blocks=DEFAULT_MIN_DISJOINT_BLOCKS)

Build a rounded, unique geometric or linear grid for a series of length n.

At least 32 observations are required. By default the lower bound is max(5, ceil(n_obs**(1 / 3))); the upper bound is min(floor(n_obs**(1 - 1 / e)), floor(n_obs / 17)). Set min_disjoint_blocks=None to omit the disjoint-block cap, or supply a positive integer to change it. This cap applies only to the automatic upper bound, not an explicit max_block_size. Bounds are never expanded to provide extra grid points; estimators check their own minimum usable point counts. Bounds must increase and fit within the series.

num_step counts grid points before rounding and deduplication, so the returned 1D integer array can be shorter. Size bounds are integers of at least two; supplied num_step and min_disjoint_blocks are positive integers.

block_maxima(vec, block_size, sliding=True)

Return maxima of complete windows in a one-dimensional series.

block_size must be an integer at least two. Sliding windows advance one observation at a time; disjoint windows discard the incomplete tail. Windows containing any nonfinite observation are omitted without joining observations across the gap. Return an empty array if no window fits.

block_summary_curve(vec, block_sizes, *, sliding=True, quantile=0.5, target='quantile')

Compute one block-maxima summary for each validated block size.

target is "quantile", "mean", or "mode"; quantiles use 0 < quantile < 1. Return aligned sizes, maxima counts, and summary values, including unavailable values as NaN. Zeros remain in quantile and mean calculations. positive_mask selects only finite, positive summaries with at least one maximum for subsequent log-log regression; it does not filter the original observations.

build_block_summary_bootstrap_backbone(vec, block_sizes, *, sliding=True, reps=200, super_block_size=None, random_state=0)

Cache segment maxima and draw segment indices with replacement.

Split the 1D series into equal complete super-blocks, discarding the incomplete tail. Sliding maxima wrap within each segment; disjoint maxima discard each segment's incomplete block. The default length is max(2 * B, floor(sqrt(N))), where B is the largest supplied block size and N is the series length. This length is used without adjustment. An explicit super_block_size must be an integer above B, no greater than N, and allow at least two complete segments; it is never adjusted. Return None if an automatic length yields fewer than two segments or reps < 2. A fixed random_state reproduces segment draws.

circular_block_summary_bootstrap(vec, block_sizes, *, target='quantile', quantile=0.5, sliding=True, reps=200, super_block_size=None, random_state=0, n_threads=None)

Estimate log-summary covariance by resampling time-series super-blocks.

Return valid log-summary rows, covariance, block-size labels, and target metadata. sliding=True wraps windows within each original segment; False uses disjoint maxima. Invalid log-summary rows are removed jointly across scales. Fewer than two requested draws or usable segments gives empty samples and no covariance. See the backbone builder for how the automatic super-block lengths are chosen and explicit lengths validated. n_threads follows the backbone evaluator's per-call thread budget.

circular_block_summary_bootstrap_multi_target(vec, block_sizes, *, targets=('quantile', 'mean', 'mode'), quantile=0.5, sliding=True, reps=200, super_block_size=None, random_state=0, n_threads=None)

Bootstrap targets using identical segment draws and cached maxima.

Return a dictionary keyed by target (quantile, mean, or mode), with each value following evaluate_block_summary_bootstrap_backbone. Targets may retain different replicate counts because invalid log summaries are removed separately for each target. n_threads follows the backbone evaluator's per-call thread budget.

evaluate_block_summary_bootstrap_backbone(backbone, *, target='quantile', quantile=0.5, n_threads=None)

Return log-summary samples and covariance from cached segment draws.

For target quantile, mean, or mode, evaluate every block-size column on the same replicates. Drop a whole replicate if any summary is nonfinite or nonpositive. samples is (valid_replicates, block_sizes); covariance is its sample covariance, or None with fewer than two valid rows. A None backbone returns empty arrays and no covariance. n_threads=None selects up to eight threads from CPUs and workload; a positive integer caps the pool, and 1 is serial. BLAS is not reconfigured.

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.

predict_block_quantile(fit, block_size)

Evaluate exp(intercept + slope * log(block_size)) for a quantile fit.

block_size must be positive and finite; it need not be an integer. The probability is fixed by fit.quantile. This extrapolates the fitted power law when the requested size is outside the selected window.

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.

estimate_target_scaling(vec, *, regression, target='quantile', 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)

Fit the UniBM log-log scaling model for quantile, mean, or mode summaries.

The regression, covariance-reuse, and adaptive-R contracts are the same as estimate_evi_quantile. quantile is used only for the quantile target. Mean/mode fits are not accepted by quantile design-life mapping helpers. Means use all finite maxima; the KDE mode surrogate uses only positive maxima. Interpreting the fitted slope as xi requires the selected summary to obey the assumed power law, which is a separate modeling assumption. n_threads has the same per-call bootstrap budget as estimate_evi_quantile.

select_penultimate_window(log_block_sizes, log_values, *, min_points=5, curvature_penalty=2.0)

Select the lowest-scoring contiguous window of paired log summaries.

Inputs must be finite one-dimensional arrays of equal length, with strictly increasing log_block_sizes. Search the full supplied range, scoring every contiguous window of at least min_points by (OLS MSE + curvature_penalty * curvature) / sqrt(length). Curvature is the mean absolute change between adjacent local slopes. Return a PlateauWindow whose start/stop and mask index the input arrays; stop is exclusive. This is a heuristic selection rule, not a statistical test for a true scaling plateau.

candidate_max_spectrum_scales(n_obs, *, min_scale=1, min_blocks=2)

Return integer exponents j with at least min_blocks blocks of size 2**j.

The grid starts at min_scale and is empty when the series is too short. These are scale exponents, not block sizes themselves.

estimate_max_spectrum_evi(sample, *, scales=None, min_scale_count=3)

Estimate xi from weighted slopes of mean log2 block maxima versus scale.

Preserve the finite series' time order and require positive maxima at every chosen dyadic scale. min_scale_count must be an integer at least three. Fit suffixes of at least min_scale_count scales, then choose a stable start-scale window and its lower-middle observed start. Return the selected slope, path, and a nominal 95% Wald interval using a scale-regression HC1 SE. That SE does not explicitly adjust for dependence between scales or start-scale selection.

estimate_sample_mode(sample, *, warn=True)

Approximate a positive-sample mode using a Gaussian KDE on log1p(x).

Nonfinite and nonpositive observations are removed; warn controls warnings about the latter. Evaluate 256 evenly spaced transformed points and apply the Jacobian before maximizing density on the original scale. Return NaN for no retained values and the value itself for a singleton. This grid-based surrogate is not an exact density mode.

summarize_block_maxima(maxima, *, target, quantile=0.5)

Return a quantile, arithmetic mean, or KDE mode of finite maxima.

An empty finite sample returns NaN. Quantiles use NumPy's median_unbiased interpolation with 0 < quantile < 1. Quantiles and means retain zeros and negatives; the mode surrogate uses only positive maxima. An unsupported target raises ValueError for a nonempty finite sample.

candidate_tail_counts(n_obs, *, min_count=8, max_fraction=0.25, num=24)

Return a deduplicated, rounded geometric grid of valid tail counts.

Counts range from min_count through min(floor(max_fraction * n_obs), n_obs - 1); rounding may give fewer than num entries. Raise ValueError for invalid arguments or no feasible count. Estimators may impose additional restrictions, such as Pickands' 4*k <= n_obs.

estimate_dedh_moment_evi(sample, *, k_values=None)

Estimate xi from top-tail log moments at a stability-selected threshold.

Retain at least eight positive finite observations. k_values must satisfy 2 <= k < n after filtering, or is generated automatically. Singular moment corrections are removed before path selection. The returned nominal 95% Wald interval uses the Fréchet-domain formula sqrt(1 + xi**2) / sqrt(k); it is not a general negative-xi interval and does not adjust for serial dependence or threshold selection.

estimate_hill_evi(sample, *, k_values=None)

Estimate a positive heavy-tail index with a stability-selected Hill threshold.

Keep positive finite observations (at least eight) and sort descending. k_values counts upper observations above rank k+1; omit it for the rounded geometric grid. Return the chosen estimate and finite path with a nominal 95% Wald interval based on abs(xi) / sqrt(k). This classical SE assumes the independent-tail regime and omits serial dependence, tail bias, and threshold-selection uncertainty.

estimate_pickands_evi(sample, *, k_values=None)

Estimate xi from order-statistic spacings at ranks k, 2k, and 4k.

This implementation retains only positive finite observations (at least eight). Supplied k_values must satisfy 4*k <= n after filtering; otherwise use the default tail grid. Tied spacings produce invalid path entries, which are dropped before stability selection. Return the selected estimate, retained path, and a classical asymptotic 95% Wald interval without dependence or selection adjustments.

select_stable_integer_window(levels, path_xi, *, min_window=4)

Choose a low-variation path window and its lower-middle observed level.

Require finite paired 1D arrays and strictly increasing integer levels. Score contiguous windows of min_window entries by path variance plus half the mean absolute second difference. If the path is shorter, use all entries. Return the selected level, inclusive level bounds, and selected path values. Levels need not be consecutive integers; this is a stability heuristic, not a hypothesis test.

wald_confidence_interval(xi_hat, standard_error, *, ci_level=0.95)

Return the two-sided normal interval xi_hat +/- z * standard_error.

ci_level must lie strictly between zero and one. Invalid estimates or negative/nonfinite SEs give (NaN, NaN); a zero SE gives equal bounds. The caller is responsible for the validity of the normal approximation.

plot_scaling_fit(fit, *, file_path=None, dpi=150, title=None, close=False, xlabel='log(block size)', ylabel=None)

Plot an EVI scaling fit on the log-log block-size scale.

Return (fig, ax) for customization. No file is saved by default; supply file_path to save. Use close=True for batch jobs. Both axes show natural-log coordinates. Highlight the selected plateau and draw its fitted line; points outside it are shown for context. Saving creates parent directories and replaces an existing output file.

target_stability_summary(vec, block_sizes, *, sliding=True, quantile=0.5)

Return a DataFrame comparing three summaries on a shared block-size grid.

Rows follow block_sizes; columns are block_size, the quantile label (median near 0.5), mean, and mode. Values are on the original response scale and may be NaN. This table reports curves; it does not select or test a stable regression window.

__getattr__(name)

Load plotting or pandas-backed helpers on first attribute access.

Cache the imported helper in module globals for later accesses; unknown names raise AttributeError. Ordinary EVI imports avoid these modules.