Metadata-Version: 2.4
Name: unibm
Version: 0.3.1
Summary: Block-maxima inference methods for heavy-tailed time series under serial dependence.
Author-email: Tuoyuan Cheng <tuoyuan.cheng@nus.edu.sg>
Maintainer-email: Tuoyuan Cheng <tuoyuan.cheng@nus.edu.sg>
License-Expression: MIT
Project-URL: Homepage, https://github.com/TY-Cheng/UniBM/
Project-URL: Repository, https://github.com/TY-Cheng/UniBM/
Project-URL: Documentation, https://ty-cheng.github.io/UniBM/
Project-URL: Issues, https://github.com/TY-Cheng/UniBM/issues
Project-URL: Changelog, https://github.com/TY-Cheng/UniBM/releases
Keywords: block maxima,block-maximum quantiles,design-life levels,environmental extremes,extreme value theory,extremal index,heavy tails,serial dependence,sliding blocks
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: matplotlib>=3.8
Requires-Dist: numpy>=2
Requires-Dist: pandas>=2
Requires-Dist: pillow>=12.3.0
Requires-Dist: scipy>=1.13
Dynamic: license-file

# UniBM

UniBM is a Python package for dependence-aware block-maxima inference in
heavy-tailed time series.

It exposes two complementary inferential targets:

- severity via the extreme value index (EVI) and design-life levels
- persistence via the extremal index (EI)

The installable package lives under `src/unibm`. Repository-level benchmark,
application, report, and static-site workflows are orchestrated through the
root `justfile`.

UniBM is developed and maintained by Tuoyuan Cheng under the project supervision
of Kan Chen. It is distributed under the MIT License.

## Package surface

The public package is organized around four entrypoints:

- `unibm` for the core EVI, pooled EI, and design-life workflows
- `unibm.evi` for the severity-side workflow
- `unibm.ei` for the persistence-side workflow
- `unibm.cdf` for the public empirical CDF helper

UniBM exposes six core functions directly from `unibm`.
The four additional root imports are not in PyPI 0.1.0: use `unibm.ei` for
`prepare_ei_bundle`, `bootstrap_bm_ei_path`, and `estimate_pooled_bm_ei`, and
`unibm.evi` for `estimate_design_life_level_interval` on that release.
All existing subpackage import paths remain supported.
When upgrading from 0.2.0, review the
[0.3.0 API migration notes](https://ty-cheng.github.io/UniBM/api/public-api/#api-migration)
for removed arguments and stricter validation.

## Quick start

**Source checkout:** 0.3.1 (unreleased). **Latest published release:** 0.3.0.

Install the [PyPI release](https://pypi.org/project/unibm/0.3.0/) with Python 3.11 or later:

```bash
python -m pip install unibm==0.3.0
```

This installs `unibm`, including its estimators, interval helpers, design-life
levels, and plotting helpers. Research scripts, datasets, and `just full` belong
to the GitHub checkout and are not included in the wheel or source distribution.

For repository development:

```bash
git clone https://github.com/TY-Cheng/UniBM.git
cd UniBM
just check
```

The `just` recipes use zsh. On Windows without zsh, use the direct uv commands
in [Development setup](https://github.com/TY-Cheng/UniBM/blob/main/CONTRIBUTING.md#development-setup).

No `.env` or external project is required. Defaults are `data/`, `out/reports/`,
and uv's normal project environment. `.env.example` documents optional report,
environment, and native-extension settings. Top-level `just` tasks load `.env`
and sync the development environment automatically.

For ad hoc uv commands that should use `.env`, use `just --command`, for example
`just --command uv run pytest -q tests/test_unibm_cdf.py`. A plain `uv sync` or
`uv run` does not automatically load `.env` before choosing its project environment;
without an exported override it uses `.venv/`.

## Acceleration

The source checkout includes NumPy/SciPy optimizations and optional Cython kernels
for EVI mode KDE, bootstrap quantile rank searches, and long-series EI bootstrap
rolling minima. Source builds attempt to
compile these kernels; without a C compiler, the same APIs use NumPy. Set
`UNIBM_NO_EXTENSIONS=1` before building for a pure Python distribution, or before
starting Python to disable an installed extension.

EVI estimation and EVI/EI bootstrap accept `n_threads=None` for automatic thread
selection, or a positive integer cap. Use `n_threads=1` inside an outer process
pool; repository workflows already assign this inner budget to their workers.
NumPy/SciPy BLAS thread settings remain separate. Design-life point estimates
and intervals reuse the EVI fit without another bootstrap.

The additional bootstrap and window-selection optimizations are in the unreleased
0.3.1 source checkout. See
[Getting Started](https://ty-cheng.github.io/UniBM/getting-started/#bootstrap-threads)
for thread and memory behavior, and
[Native acceleration](https://github.com/TY-Cheng/UniBM/blob/main/CONTRIBUTING.md#native-acceleration)
for build instructions.

## Results and reports

Calculation results stay in the code repository:

- `out/benchmark/`: benchmark CSVs and sensitivity summaries
- `out/benchmark/cache/`: reusable simulation caches
- `out/applications/`: application CSVs and JSON

Final PDF figures and LaTeX tables go to `Figure/` and `Table/` inside a single
report destination. `UNIBM_REPORT_DIR` unset or blank means `out/reports/`.
An explicit value selects that destination directly, without an additional local
copy. Relative paths are resolved against the code repository root:

```bash
UNIBM_REPORT_DIR="/path/to/your/report-project" just reports
```

An invalid destination raises an error; it never silently falls back. Report
output directories and files must not redirect writes through symlinks.
Table filenames describe their contents, for example `application_summary.tex`;
direct JoH updates use these names and their matching LaTeX labels.
Benchmark figures and tables use paired `benchmark_evi_*` / `benchmark_ei_*`
names; raw benchmark CSVs use `evi_*` / `ei_*`. Application method comparisons
use `application_evi_methods.csv` / `application_ei_methods.csv`. Combined
application summaries retain the general `application_summary` name.
`report_subset_manifest.json` indexes expected paths, labels, producers, and
placements for the curated four-case report subset. It is not a complete
inventory or a verification of generated files. `manifest_code_commit` and
`manifest_code_worktree_dirty` describe the code checkout when the index was
written, not the version used to calculate the listed results.

The cleanup step in `just full` removes only explicitly named workflow outputs for the
selected benchmark sample size and report destination. Those names are reserved
for generated files. It preserves caches, other sample-size runs, research notes,
historical report folders, and unrecognized files. It never deletes an entire
output directory. Web snapshots under `docs/assets/` are refreshed by the report
workflows separately.

## Documentation

The site presents a [statistical Benchmark](https://ty-cheng.github.io/UniBM/benchmark/)
followed by nine records across six case pages: streamflow, NFIP claims, Houston,
Phoenix, GOES, and SPY/QQQ. Each page defines its raw or normalized observation
scale. GOES reports OLS EVI point diagnostics only; other cases include EVI and EI.

To regenerate just the documented case figures and numerical records without
external report export or network access:

```bash
PYTHONPATH=scripts uv run python -m application.docs_cases
```

GHCN, USGS, and NFIP use archived repository inputs. GOES/finance require the
local snapshots described on their pages. Add `--available` to retain frozen
optional assets when these inputs are absent; corrupt inputs still fail. The
ordinary application workflow uses this optional-input policy. Site builds need
only the tracked static assets, not provider access. Use `just --command` for
these uv commands when relying on environment overrides from `.env`.

Package documentation is available at:

- [https://ty-cheng.github.io/UniBM/](https://ty-cheng.github.io/UniBM/)

Useful local docs command:

```bash
just --command uv run mkdocs serve
```

This builds the static site under `site/` and launches the local preview server.

## Main repo entrypoints

The stable top-level entrypoints are:

- `just check`
- `just check-full`
- `just data`
- `just refresh-data`
- `just benchmark`
- `just application`
- `just reports`
- `just full`

`just check` runs tests affected by local changes in parallel, then checks all
formatting and lint rules. `just check-full` runs the complete parallel test
suite with the coverage gate.
`just data` validates the tracked canonical inputs and prepares the four report
cases without network access. `just refresh-data` is the networked recipe for canonical inputs; the optional
GOES downloader is documented separately. The recipe refreshes fixed-cutoff
provider snapshots and leaves their
Git diff for review. `just reports` reuses valid benchmark summaries, computes
missing ones, and reruns application fits to refresh reports and web snapshots.
`just full` checks the project, cleans named outputs, and rebuilds the benchmark,
application, report, and static-site outputs offline. These research workflows
can be expensive; they are not required to use or install the package.

## Minimal package example

```python
import numpy as np
from unibm import estimate_design_life_level, estimate_evi_quantile

sample = np.random.default_rng(7).pareto(2.0, 4096) + 1.0
fit = estimate_evi_quantile(
    sample,
    regression="FGLS",
    quantile=0.5,
    sliding=True,
    bootstrap_reps="adaptive",
    random_state=7,
)
design_life = estimate_design_life_level(fit, years=np.array([10.0, 50.0]))
```

See the docs site for API details, returned objects, and worked examples.

The example uses the default adaptive policy with checkpoints 128, 256, 512,
768, and 1024. An explicit integer such as `bootstrap_reps=480` instead fixes R. Inspect
`bootstrap_reps_used` and `bootstrap_precision_met`: reaching the cap does not
imply precision was met. Adaptive R controls numerical Monte Carlo error, not
statistical CI width or coverage. FGLS uses fixed shrinkage 0.73 for EVI and 0.37 for EI.
