bootstrapx-lib 0.1.3__tar.gz

bootstrapx_lib-0.1.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Artem Erokhin
+
+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.

bootstrapx_lib-0.1.3/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: bootstrapx-lib
+Version: 0.1.3
+Summary: Production-grade uncertainty estimation for Python.
+Author-email: Artem Erokhin <artyerokhin@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/artyerokhin/bootstrapx
+Project-URL: Documentation, https://artyerokhin.github.io/bootstrapx
+Project-URL: Repository, https://github.com/artyerokhin/bootstrapx
+Project-URL: Issues, https://github.com/artyerokhin/bootstrapx/issues
+Keywords: bootstrap,statistics,confidence-interval,resampling,numba
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.23
+Requires-Dist: scipy>=1.10
+Requires-Dist: numba>=0.57
+Requires-Dist: joblib>=1.3
+Provides-Extra: cuda
+Requires-Dist: numba>=0.57; extra == "cuda"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: hypothesis; extra == "dev"
+Requires-Dist: coverage; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs-material; extra == "docs"
+Requires-Dist: mkdocstrings[python]; extra == "docs"
+Provides-Extra: bench
+Requires-Dist: asv; extra == "bench"
+Requires-Dist: virtualenv; extra == "bench"
+Dynamic: license-file
+
+<div align="center">
+
+# bootstrapx
+
+**Production-grade uncertainty estimation for Python.**
+
+[![CI](https://github.com/artyerokhin/bootstrapx/actions/workflows/ci.yml/badge.svg)](https://github.com/artyerokhin/bootstrapx/actions)
+[![PyPI](https://img.shields.io/pypi/v/bootstrapx)](https://pypi.org/project/bootstrapx/)
+[![Python](https://img.shields.io/pypi/pyversions/bootstrapx)](https://pypi.org/project/bootstrapx/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-mkdocs-blue)](https://artyerokhin.github.io/bootstrapx)
+
+*14 bootstrap methods · Numba JIT · Optional CUDA GPU · Memory-safe batching*
+
+</div>
+
+---
+
+## Why bootstrapx?
+
+`scipy.stats.bootstrap` supports only 3 CI methods and has no time-series support.
+The R `boot` package is comprehensive but not accessible from Python.
+**bootstrapx** bridges this gap with 14 methods, Numba acceleration, and a clean API.
+
+| Feature | `scipy` | R `boot` | **bootstrapx** |
+|---|:---:|:---:|:---:|
+| BCa interval | ✅ | ✅ | ✅ |
+| Studentized (bootstrap-t) | ❌ | ✅ | ✅ |
+| Poisson / Bernoulli weights | ❌ | ❌ | ✅ |
+| Time-series (MBB, CBB, Stationary, Sieve, Tapered, Wild) | ❌ | Partial | ✅ |
+| Cluster / Stratified | ❌ | Partial | ✅ |
+| Numba JIT | ❌ | N/A | ✅ |
+| CUDA GPU | ❌ | ❌ | ✅ |
+| Generator batching (constant memory) | ❌ | ❌ | ✅ |
+
+---
+
+## Installation
+
+```bash
+pip install bootstrapx
+
+# With GPU
+pip install "bootstrapx[cuda]"
+```
+
+---
+
+## Quick Start
+
+```python
+import numpy as np
+from bootstrapx import bootstrap
+
+data = np.random.default_rng(42).normal(5, 2, size=200)
+
+result = bootstrap(data, np.mean)
+print(result)
+# BootstrapResult(method='bca', theta_hat=4.94, se=0.13, CI=[4.70, 5.19])
+```
+
+---
+
+## Performance
+
+bootstrapx is significantly faster than `scipy.stats.bootstrap` for large datasets:
+
+| N | Method | Scipy | Bootstrapx | Speedup |
+|---|---|---|---|---|
+| 5,000 | BCa | 0.80s | 0.27s | **3.0x** |
+| 50,000 | Percentile | 7.29s | 2.01s | **3.6x** |
+| 100,000 | Percentile | 54.34s | 3.99s | **13.6x** |
+
+*Benchmark on Apple M1, Python 3.12. See [Benchmarks](https://artyerokhin.github.io/bootstrapx/benchmarks/) for details.*
+
+---
+
+## Coverage Accuracy
+
+Monte Carlo simulation ($N=1000$, 500 runs) confirms correct statistical coverage:
+
+| Distribution | BCa Coverage (Nominal 95%) |
+|---|---|
+| Normal | **94.8%** |
+| Skewed (Exponential) | **95.0%** |
+| Heavy-Tailed (t-dist) | **94.0%** |
+
+---
+
+## Documentation
+
+📖 **Full docs:** [artyerokhin.github.io/bootstrapx](https://artyerokhin.github.io/bootstrapx)
+
+- [Getting Started](https://artyerokhin.github.io/bootstrapx/getting-started/)
+- [Methods Guide](https://artyerokhin.github.io/bootstrapx/methods/) — math behind each method
+- [API Reference](https://artyerokhin.github.io/bootstrapx/reference/)
+- [Benchmarks](https://artyerokhin.github.io/bootstrapx/benchmarks/)
+
+---
+
+## Contributing
+
+```bash
+git clone https://github.com/artyerokhin/bootstrapx.git
+cd bootstrapx
+pip install -e ".[dev,docs]"
+pytest tests/ -v
+mkdocs serve
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

bootstrapx_lib-0.1.3/README.md

@@ -0,0 +1,115 @@
+<div align="center">
+
+# bootstrapx
+
+**Production-grade uncertainty estimation for Python.**
+
+[![CI](https://github.com/artyerokhin/bootstrapx/actions/workflows/ci.yml/badge.svg)](https://github.com/artyerokhin/bootstrapx/actions)
+[![PyPI](https://img.shields.io/pypi/v/bootstrapx)](https://pypi.org/project/bootstrapx/)
+[![Python](https://img.shields.io/pypi/pyversions/bootstrapx)](https://pypi.org/project/bootstrapx/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-mkdocs-blue)](https://artyerokhin.github.io/bootstrapx)
+
+*14 bootstrap methods · Numba JIT · Optional CUDA GPU · Memory-safe batching*
+
+</div>
+
+---
+
+## Why bootstrapx?
+
+`scipy.stats.bootstrap` supports only 3 CI methods and has no time-series support.
+The R `boot` package is comprehensive but not accessible from Python.
+**bootstrapx** bridges this gap with 14 methods, Numba acceleration, and a clean API.
+
+| Feature | `scipy` | R `boot` | **bootstrapx** |
+|---|:---:|:---:|:---:|
+| BCa interval | ✅ | ✅ | ✅ |
+| Studentized (bootstrap-t) | ❌ | ✅ | ✅ |
+| Poisson / Bernoulli weights | ❌ | ❌ | ✅ |
+| Time-series (MBB, CBB, Stationary, Sieve, Tapered, Wild) | ❌ | Partial | ✅ |
+| Cluster / Stratified | ❌ | Partial | ✅ |
+| Numba JIT | ❌ | N/A | ✅ |
+| CUDA GPU | ❌ | ❌ | ✅ |
+| Generator batching (constant memory) | ❌ | ❌ | ✅ |
+
+---
+
+## Installation
+
+```bash
+pip install bootstrapx
+
+# With GPU
+pip install "bootstrapx[cuda]"
+```
+
+---
+
+## Quick Start
+
+```python
+import numpy as np
+from bootstrapx import bootstrap
+
+data = np.random.default_rng(42).normal(5, 2, size=200)
+
+result = bootstrap(data, np.mean)
+print(result)
+# BootstrapResult(method='bca', theta_hat=4.94, se=0.13, CI=[4.70, 5.19])
+```
+
+---
+
+## Performance
+
+bootstrapx is significantly faster than `scipy.stats.bootstrap` for large datasets:
+
+| N | Method | Scipy | Bootstrapx | Speedup |
+|---|---|---|---|---|
+| 5,000 | BCa | 0.80s | 0.27s | **3.0x** |
+| 50,000 | Percentile | 7.29s | 2.01s | **3.6x** |
+| 100,000 | Percentile | 54.34s | 3.99s | **13.6x** |
+
+*Benchmark on Apple M1, Python 3.12. See [Benchmarks](https://artyerokhin.github.io/bootstrapx/benchmarks/) for details.*
+
+---
+
+## Coverage Accuracy
+
+Monte Carlo simulation ($N=1000$, 500 runs) confirms correct statistical coverage:
+
+| Distribution | BCa Coverage (Nominal 95%) |
+|---|---|
+| Normal | **94.8%** |
+| Skewed (Exponential) | **95.0%** |
+| Heavy-Tailed (t-dist) | **94.0%** |
+
+---
+
+## Documentation
+
+📖 **Full docs:** [artyerokhin.github.io/bootstrapx](https://artyerokhin.github.io/bootstrapx)
+
+- [Getting Started](https://artyerokhin.github.io/bootstrapx/getting-started/)
+- [Methods Guide](https://artyerokhin.github.io/bootstrapx/methods/) — math behind each method
+- [API Reference](https://artyerokhin.github.io/bootstrapx/reference/)
+- [Benchmarks](https://artyerokhin.github.io/bootstrapx/benchmarks/)
+
+---
+
+## Contributing
+
+```bash
+git clone https://github.com/artyerokhin/bootstrapx.git
+cd bootstrapx
+pip install -e ".[dev,docs]"
+pytest tests/ -v
+mkdocs serve
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

bootstrapx_lib-0.1.3/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "bootstrapx-lib"
+version = "0.1.3"
+description = "Production-grade uncertainty estimation for Python."
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+authors = [{name = "Artem Erokhin", email = "artyerokhin@gmail.com"}]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Mathematics",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+keywords = ["bootstrap", "statistics", "confidence-interval", "resampling", "numba"]
+
+dependencies = [
+    "numpy>=1.23",
+    "scipy>=1.10",
+    "numba>=0.57",
+    "joblib>=1.3",
+]
+
+[project.urls]
+Homepage = "https://github.com/artyerokhin/bootstrapx"
+Documentation = "https://artyerokhin.github.io/bootstrapx"
+Repository = "https://github.com/artyerokhin/bootstrapx"
+Issues = "https://github.com/artyerokhin/bootstrapx/issues"
+
+[project.optional-dependencies]
+cuda = ["numba>=0.57"]
+dev  = ["pytest>=7", "hypothesis", "coverage", "mypy", "ruff"]
+docs = ["mkdocs-material", "mkdocstrings[python]"]
+bench = ["asv", "virtualenv"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+ignore_missing_imports = true
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "UP", "B"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

bootstrapx_lib-0.1.3/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

bootstrapx_lib-0.1.3/src/bootstrapx/__init__.py

@@ -0,0 +1,8 @@
+"""bootstrapx — Production-grade uncertainty estimation for Python."""
+from __future__ import annotations
+
+# Use relative import to work without installation
+from .api import bootstrap, BootstrapResult
+
+__version__ = "0.1.0"
+__all__ = ["bootstrap", "BootstrapResult"]

bootstrapx_lib-0.1.3/src/bootstrapx/api.py

@@ -0,0 +1,218 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+import numpy as np
+
+from bootstrapx.engine.backend import resolve_backend, apply_statistic_batched
+from bootstrapx.generators.iid import (
+    basic_resample,
+    bernoulli_resample,
+    poisson_resample,
+    subsampling_resample,
+)
+from bootstrapx.generators.timeseries import (
+    cbb_resample,
+    mbb_resample,
+    sieve_resample,
+    stationary_resample,
+    tapered_block_resample,
+    wild_resample,
+)
+from bootstrapx.generators.hierarchical import cluster_resample, strata_resample
+from bootstrapx.stats.confidence import (
+    ConfidenceInterval,
+    basic_interval,
+    bca_interval,
+    percentile_interval,
+    studentized_interval,
+)
+from bootstrapx.utils import auto_batch_size, validate_data
+
+
+@dataclass
+class BootstrapResult:
+    confidence_interval: ConfidenceInterval
+    bootstrap_distribution: np.ndarray
+    theta_hat: float
+    standard_error: float
+    n_resamples: int
+    method: str
+    extra: dict[str, Any] = field(default_factory=dict)
+
+    def __repr__(self) -> str:
+        ci = self.confidence_interval
+        return (
+            f"BootstrapResult(method={self.method!r}, "
+            f"theta_hat={self.theta_hat:.6g}, "
+            f"se={self.standard_error:.6g}, "
+            f"CI=[{ci.low:.6g}, {ci.high:.6g}])"
+        )
+
+
+def _collect(gen, statistic: Callable[[np.ndarray], float]) -> list[float]:
+    results = []
+    for batch in gen:
+        if isinstance(batch, tuple):
+            data_ref, weights = batch
+            # weights is (B, N), iterate over rows
+            for i in range(weights.shape[0]):
+                w = weights[i]
+                mask = w > 0
+                val = statistic(data_ref[mask]) if mask.any() else statistic(data_ref)
+                results.append(float(val))
+        elif isinstance(batch, list):
+            for arr in batch:
+                results.append(float(statistic(arr)))
+        else:
+            # Standard array batch (B, N)
+            for i in range(batch.shape[0]):
+                results.append(float(statistic(batch[i])))
+    return results
+
+
+_IID_METHODS = {
+    "percentile",
+    "basic",
+    "bca",
+    "studentized",
+    "poisson",
+    "bernoulli",
+    "subsampling",
+}
+_TS_METHODS = {"mbb", "cbb", "stationary", "tapered", "sieve", "wild"}
+_HIER_METHODS = {"cluster", "strata"}
+_ALL_METHODS = _IID_METHODS | _TS_METHODS | _HIER_METHODS
+
+
+def bootstrap(
+    data: Any,
+    statistic: Callable[[np.ndarray], float],
+    *,
+    method: str = "bca",
+    n_resamples: int = 9999,
+    batch_size: int | None = None,
+    confidence_level: float = 0.95,
+    backend: str = "auto",
+    random_state: int | np.random.Generator | None = None,
+    n_jobs: int = 1,
+    **kwargs: Any,
+) -> BootstrapResult:
+    method = method.lower().strip()
+    if method not in _ALL_METHODS:
+        valid = sorted(_ALL_METHODS)
+        raise ValueError(f"Unknown method {method!r}. Choose from {valid}.")
+
+    arr = validate_data(data, allow_2d=(method in _HIER_METHODS))
+    n = arr.shape[0]
+
+    if isinstance(random_state, np.random.Generator):
+        rng = random_state
+    else:
+        rng = np.random.default_rng(random_state)
+
+    if batch_size is None:
+        batch_size = auto_batch_size(n, n_resamples)
+
+    backend_kind = resolve_backend(backend)
+    theta_hat = float(statistic(arr))
+
+    if method in {"percentile", "basic", "bca", "studentized"}:
+        boot_stats = apply_statistic_batched(
+            arr, statistic, batch_size, n_resamples, backend_kind, rng
+        )
+
+        if method == "percentile":
+            ci = percentile_interval(boot_stats, confidence_level)
+        elif method == "basic":
+            ci = basic_interval(boot_stats, theta_hat, confidence_level)
+        elif method == "bca":
+            ci = bca_interval(boot_stats, arr, statistic, theta_hat, confidence_level)
+        elif method == "studentized":
+            # Nested bootstrap for SE
+            n_inner = kwargs.get("n_inner", 50)
+            idx_all = rng.integers(0, n, size=(n_resamples, n))
+            boot_se = np.empty(n_resamples, dtype=np.float64)
+
+            for b in range(n_resamples):
+                sample = arr[idx_all[b]]
+                # Inner loop simple bootstrap
+                inner_idx = rng.integers(0, n, size=(n_inner, n))
+                inner_vals = [statistic(sample[inner_idx[k]]) for k in range(n_inner)]
+                boot_se[b] = np.std(inner_vals, ddof=1)
+
+            ci = studentized_interval(
+                arr, statistic, theta_hat, boot_stats, boot_se, confidence_level
+            )
+        else:
+            # Should not happen
+            raise ValueError("Unreachable")
+
+    else:
+        # Generator-based methods
+        if method == "cluster":
+            cids = kwargs.get("cluster_ids")
+            if cids is None:
+                raise ValueError("cluster method requires `cluster_ids` kwarg.")
+            gen = cluster_resample(arr, np.asarray(cids), n_resamples, batch_size, rng)
+
+        elif method == "strata":
+            sids = kwargs.get("strata_ids")
+            if sids is None:
+                raise ValueError("strata method requires `strata_ids` kwarg.")
+            gen = strata_resample(arr, np.asarray(sids), n_resamples, batch_size, rng)
+
+        else:
+            # Map method name to generator function
+            if method == "poisson":
+                gen = poisson_resample(arr, n_resamples, batch_size, rng)
+            elif method == "bernoulli":
+                prob = kwargs.get("prob", 0.5)
+                gen = bernoulli_resample(arr, n_resamples, batch_size, rng, prob=prob)
+            elif method == "subsampling":
+                ss = kwargs.get("subsample_size")
+                gen = subsampling_resample(
+                    arr, n_resamples, batch_size, rng, subsample_size=ss
+                )
+            elif method == "mbb":
+                bl = kwargs.get("block_length", 10)
+                gen = mbb_resample(arr, n_resamples, batch_size, rng, block_length=bl)
+            elif method == "cbb":
+                bl = kwargs.get("block_length", 10)
+                gen = cbb_resample(arr, n_resamples, batch_size, rng, block_length=bl)
+            elif method == "stationary":
+                mb = kwargs.get("mean_block", 10.0)
+                gen = stationary_resample(
+                    arr, n_resamples, batch_size, rng, mean_block=mb
+                )
+            elif method == "tapered":
+                bl = kwargs.get("block_length", 10)
+                tp = kwargs.get("taper", "tukey")
+                gen = tapered_block_resample(
+                    arr, n_resamples, batch_size, rng, block_length=bl, taper=tp
+                )
+            elif method == "sieve":
+                ar = kwargs.get("ar_order")
+                gen = sieve_resample(arr, n_resamples, batch_size, rng, ar_order=ar)
+            elif method == "wild":
+                fit = kwargs.get("fitted")
+                dist = kwargs.get("distribution", "rademacher")
+                gen = wild_resample(
+                    arr, n_resamples, batch_size, rng, fitted=fit, distribution=dist
+                )
+            else:
+                # Should not happen due to check above
+                raise ValueError(f"Method {method} not implemented in dispatcher.")
+
+        boot_stats = np.array(_collect(gen, statistic), dtype=np.float64)
+        ci = percentile_interval(boot_stats, confidence_level)
+
+    return BootstrapResult(
+        confidence_interval=ci,
+        bootstrap_distribution=boot_stats,
+        theta_hat=theta_hat,
+        standard_error=float(np.std(boot_stats, ddof=1)),
+        n_resamples=len(boot_stats),
+        method=method,
+    )