unibm 0.1.0__tar.gz

unibm-0.1.0/.gitignore

@@ -0,0 +1,108 @@
+# Project-generated outputs
+scratch*
+/tmp/
+/.python-version
+/doc/
+/site/
+/out/
+*.pkl
+*.csv.gz
+*.npz
+CONTEXT.md
+
+# Canonical provider snapshots (derived data and download chunks stay ignored)
+/data/*
+!/data/README.md
+!/data/raw/
+/data/raw/*
+!/data/raw/cpi/
+/data/raw/cpi/*
+!/data/raw/cpi/cpi_u_monthly.csv
+!/data/raw/fema/
+/data/raw/fema/*
+!/data/raw/fema/nfip_claims_fl.csv.gz
+!/data/raw/fema/nfip_claims_tx.csv.gz
+!/data/raw/ghcn/
+/data/raw/ghcn/*
+!/data/raw/ghcn/USW00012918.csv.gz
+!/data/raw/ghcn/USW00023183.csv.gz
+!/data/raw/usgs/
+/data/raw/usgs/*
+!/data/raw/usgs/usgs_02236000.csv.gz
+!/data/raw/usgs/usgs_02320500.csv.gz
+!/data/raw/usgs/usgs_02366500.csv.gz
+!/data/raw/usgs/usgs_08066500.csv.gz
+!/data/raw/usgs/usgs_08114000.csv.gz
+!/data/raw/usgs/usgs_08158000.csv.gz
+!/data/metadata/
+/data/metadata/*
+!/data/metadata/sources.json
+!/data/metadata/application/
+/data/metadata/application/*
+!/data/metadata/application/usgs_candidate_sites.json
+!/data/metadata/application/usgs_frozen_sites.json
+
+# Python runtime
+__pycache__/
+*.py[codz]
+*$py.class
+*.so
+
+# Packaging / build
+.Python
+MANIFEST
+build/
+dist/
+*.egg
+*.egg-info/
+
+# Environments / secrets
+.env
+.envrc
+.venv/
+ENV/
+env/
+venv/
+
+# Testing / coverage
+.coverage
+.coverage.*
+.hypothesis/
+.nox/
+.tox/
+.cache/
+cover/
+coverage.xml
+htmlcov/
+nosetests.xml
+*.cover
+*.py.cover
+
+# Tool caches
+.serena/
+.dmypy.json
+.mypy_cache/
+dmypy.json
+
+# IPython
+ipython_config.py
+profile_default/
+
+# Editors
+.vscode/*
+!.vscode/*.code-snippets
+!.vscode/extensions.json
+!.vscode/launch.json
+!.vscode/settings.json
+!.vscode/tasks.json
+!*.code-workspace
+*.vsix
+
+# macOS
+**/.DS_Store
+
+# Misc
+*.log
+.pypirc
+pip-delete-this-directory.txt
+pip-log.txt

unibm-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024- Tuoyuan Cheng, Kan Chen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

unibm-0.1.0/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.5
+Name: unibm
+Version: 0.1.0
+Summary: Block-maxima inference methods for heavy-tailed time series under serial dependence.
+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
+Author-email: Tuoyuan Cheng <tuoyuan.cheng@nus.edu.sg>
+Maintainer-email: Tuoyuan Cheng <tuoyuan.cheng@nus.edu.sg>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: block maxima,block-maximum quantiles,design-life levels,environmental extremes,extremal index,extreme value theory,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
+Requires-Dist: matplotlib>=3.8
+Requires-Dist: numpy>=2
+Requires-Dist: pandas>=2
+Requires-Dist: pillow>=12.3.0
+Requires-Dist: scipy>=1.13
+Description-Content-Type: text/markdown
+
+# UniBM
+
+UniBM is a Python package for dependence-aware block-maxima inference in
+environmental extremes.
+
+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 headline EVI and design-life-level calls
+- `unibm.evi` for the severity-side workflow
+- `unibm.ei` for the persistence-side workflow
+- `unibm.cdf` for the public empirical CDF helper
+
+## Quick start
+
+Install the package from a source checkout with Python 3.11 or later:
+
+```bash
+git clone https://github.com/TY-Cheng/UniBM.git
+python -m pip install ./UniBM
+```
+
+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
+cd UniBM
+just check
+```
+
+No `.env` or external project is required. Defaults are `data/`, `out/reports/`,
+and uv's normal project environment. Copy `.env.example` only to override the
+report destination or environment location. 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/`.
+
+## 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
+
+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 only networked data
+entrypoint; it refreshes the 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. Both EVI/EI FGLS defaults use fixed shrinkage 0.37.

unibm-0.1.0/README.md

@@ -0,0 +1,158 @@
+# UniBM
+
+UniBM is a Python package for dependence-aware block-maxima inference in
+environmental extremes.
+
+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 headline EVI and design-life-level calls
+- `unibm.evi` for the severity-side workflow
+- `unibm.ei` for the persistence-side workflow
+- `unibm.cdf` for the public empirical CDF helper
+
+## Quick start
+
+Install the package from a source checkout with Python 3.11 or later:
+
+```bash
+git clone https://github.com/TY-Cheng/UniBM.git
+python -m pip install ./UniBM
+```
+
+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
+cd UniBM
+just check
+```
+
+No `.env` or external project is required. Defaults are `data/`, `out/reports/`,
+and uv's normal project environment. Copy `.env.example` only to override the
+report destination or environment location. 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/`.
+
+## 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
+
+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 only networked data
+entrypoint; it refreshes the 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. Both EVI/EI FGLS defaults use fixed shrinkage 0.37.

unibm-0.1.0/pyproject.toml

@@ -0,0 +1,108 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "unibm"
+dynamic = ["version"]
+description = "Block-maxima inference methods for heavy-tailed time series under serial dependence."
+requires-python = ">=3.11"
+authors = [{ name = "Tuoyuan Cheng", email = "tuoyuan.cheng@nus.edu.sg" }]
+maintainers = [{ name = "Tuoyuan Cheng", email = "tuoyuan.cheng@nus.edu.sg" }]
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "block maxima",
+    "block-maximum quantiles",
+    "design-life levels",
+    "environmental extremes",
+    "extreme value theory",
+    "extremal index",
+    "heavy tails",
+    "serial dependence",
+    "sliding blocks",
+]
+classifiers = [
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering",
+]
+dependencies = ["matplotlib>=3.8", "numpy>=2", "pandas>=2", "pillow>=12.3.0", "scipy>=1.13"]
+
+[project.urls]
+Homepage = "https://github.com/TY-Cheng/UniBM/"
+Repository = "https://github.com/TY-Cheng/UniBM/"
+Documentation = "https://ty-cheng.github.io/UniBM/"
+Issues = "https://github.com/TY-Cheng/UniBM/issues"
+Changelog = "https://github.com/TY-Cheng/UniBM/releases"
+
+[dependency-groups]
+dev = [
+    "mkdocs>=1.6,<2",
+    "mkdocs-autorefs>=1.4",
+    "mkdocs-material>=9.7.7",
+    "mkdocstrings[python]>=0.29",
+    "pymdown-extensions>=11.0.1",
+    "pytest",
+    "pytest-cov",
+    "pytest-testmon",
+    "pytest-xdist",
+    "python-dotenv",
+    "ruff",
+]
+
+[tool.hatch.build]
+exclude = ["/**/__pycache__", "/**/.DS_Store"]
+
+[tool.hatch.version]
+path = "src/unibm/__about__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/unibm"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/LICENSE", "/README.md", "/pyproject.toml", "/src/unibm"]
+
+[[tool.uv.index]]
+name = "testpypi"
+url = "https://test.pypi.org/simple/"
+publish-url = "https://test.pypi.org/legacy/"
+explicit = true
+
+[tool.pytest.ini_options]
+cache_dir = ".cache/pytest"
+pythonpath = ["src", "scripts"]
+
+[tool.ruff]
+cache-dir = ".cache/ruff"
+line-length = 99
+extend-exclude = ["site", "justfile"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+docstring-code-format = true
+docstring-code-line-length = 99
+
+[tool.ruff.lint.pycodestyle]
+max-doc-length = 99
+max-line-length = 99
+
+[tool.coverage.run]
+branch = true
+source = ["src/unibm"]
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = false
+precision = 2
+fail_under = 89
+exclude_also = ["if __name__ == .__main__.:", "pragma: no cover"]
+
+[tool.coverage.html]
+directory = "htmlcov"

unibm-0.1.0/src/unibm/__about__.py

@@ -0,0 +1,3 @@
+"""Package version metadata for the installable UniBM library."""
+
+__version__ = "0.1.0"

unibm-0.1.0/src/unibm/__init__.py

@@ -0,0 +1,39 @@
+"""Public UniBM package facade.
+
+The package exposes grouped public namespaces under ``unibm.evi`` and
+``unibm.ei`` together with the standalone helper module ``unibm.cdf``.
+Repo-local benchmark, application,
+and repository orchestration code lives outside the package under
+``scripts/``.
+"""
+
+from typing import TYPE_CHECKING
+
+from .__about__ import __version__
+
+if TYPE_CHECKING:
+    from . import ei, evi
+    from .evi.design import estimate_design_life_level
+    from .evi.estimation import estimate_evi_quantile
+
+__all__ = ["__version__", "ei", "evi", "estimate_design_life_level", "estimate_evi_quantile"]
+
+
+def __getattr__(name: str):
+    """Import a public namespace or estimator on first access and cache it.
+
+    Unknown names raise ``AttributeError``, as for an ordinary module attribute.
+    Deferring these imports keeps ``import unibm`` lightweight.
+    """
+    import importlib
+
+    if name in {"ei", "evi"}:
+        value = importlib.import_module(f"{__name__}.{name}")
+    elif name == "estimate_evi_quantile":
+        value = importlib.import_module(f"{__name__}.evi.estimation").estimate_evi_quantile
+    elif name == "estimate_design_life_level":
+        value = importlib.import_module(f"{__name__}.evi.design").estimate_design_life_level
+    else:
+        raise AttributeError(f"module 'unibm' has no attribute {name!r}")
+    globals()[name] = value
+    return value