debiased-inference 0.1.0__tar.gz

debiased_inference-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+.DS_Store
+.Rhistory
+.RData
+.Rproj.user/
+*.Rcheck/
+/*.tar.gz
+python/.pytest_cache/
+python/.coverage
+python/.mypy_cache/
+python/.ruff_cache/
+python/.venv/
+python/build/
+python/dist/
+python/src/*.egg-info/
+__pycache__/
+*.py[cod]

debiased_inference-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gang Cheng and Yen-Chi 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.

debiased_inference-0.1.0/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.5
+Name: debiased-inference
+Version: 0.1.0
+Summary: Bootstrap inference with debiased nonparametric estimators
+Project-URL: Homepage, https://github.com/mathcg/debiased-inference
+Project-URL: Repository, https://github.com/mathcg/debiased-inference.git
+Project-URL: Issues, https://github.com/mathcg/debiased-inference/issues
+Project-URL: Paper, https://doi.org/10.1214/19-EJS1575
+Author: Gang Cheng, Yen-Chi Chen
+License: MIT License
+        
+        Copyright (c) 2026 Gang Cheng and Yen-Chi 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.
+License-File: LICENSE
+Keywords: bootstrap,confidence-bands,kernel-density,nonparametric-regression
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.23
+Provides-Extra: dev
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: test
+Requires-Dist: pytest-cov>=4; extra == 'test'
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# debiased-inference (Python)
+
+Python implementation of the procedures in Cheng and Chen,
+[“Nonparametric Inference via Bootstrapping the Debiased
+Estimator”](https://projecteuclid.org/journalArticle/Download?urlId=10.1214%2F19-EJS1575).
+
+If you use these methods or this software, please cite the paper (Electronic
+Journal of Statistics 13(1), 2019; doi:10.1214/19-EJS1575).
+
+```python
+import numpy as np
+from debiased_inference import kde_confidence_band
+
+rng = np.random.default_rng(2026)
+sample = rng.normal(size=300)
+band = kde_confidence_band(sample, n_boot=499, random_state=2026)
+print(band)
+```
+
+The package also provides debiased local-linear regression, density level-set
+and inverse-regression confidence sets, normal-reference and cross-validated
+bandwidth selectors, and a studentized density band. The project repository
+contains the full statistical specification and cross-language API guide.

debiased_inference-0.1.0/README.md

@@ -0,0 +1,23 @@
+# debiased-inference (Python)
+
+Python implementation of the procedures in Cheng and Chen,
+[“Nonparametric Inference via Bootstrapping the Debiased
+Estimator”](https://projecteuclid.org/journalArticle/Download?urlId=10.1214%2F19-EJS1575).
+
+If you use these methods or this software, please cite the paper (Electronic
+Journal of Statistics 13(1), 2019; doi:10.1214/19-EJS1575).
+
+```python
+import numpy as np
+from debiased_inference import kde_confidence_band
+
+rng = np.random.default_rng(2026)
+sample = rng.normal(size=300)
+band = kde_confidence_band(sample, n_boot=499, random_state=2026)
+print(band)
+```
+
+The package also provides debiased local-linear regression, density level-set
+and inverse-regression confidence sets, normal-reference and cross-validated
+bandwidth selectors, and a studentized density band. The project repository
+contains the full statistical specification and cross-language API guide.

debiased_inference-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "debiased-inference"
+version = "0.1.0"
+description = "Bootstrap inference with debiased nonparametric estimators"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {file = "LICENSE"}
+authors = [
+  {name = "Gang Cheng"},
+  {name = "Yen-Chi Chen"},
+]
+keywords = ["bootstrap", "confidence-bands", "kernel-density", "nonparametric-regression"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Scientific/Engineering :: Mathematics",
+]
+dependencies = ["numpy>=1.23"]
+
+[project.optional-dependencies]
+test = ["pytest>=7", "pytest-cov>=4"]
+dev = ["ruff>=0.6"]
+
+[project.urls]
+Homepage = "https://github.com/mathcg/debiased-inference"
+Repository = "https://github.com/mathcg/debiased-inference.git"
+Issues = "https://github.com/mathcg/debiased-inference/issues"
+Paper = "https://doi.org/10.1214/19-EJS1575"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/debiased_inference"]
+
+[tool.hatch.build]
+exclude = ["/.coverage"]
+
+[tool.pytest.ini_options]
+addopts = "-ra --strict-markers"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"

debiased_inference-0.1.0/src/debiased_inference/__init__.py

@@ -0,0 +1,36 @@
+"""Bootstrap inference with debiased nonparametric estimators."""
+
+from ._results import ConfidenceBandResult, EstimateResult, SetEstimateResult
+from .bandwidth import density_bandwidth, regression_bandwidth
+from .kde import debiased_kde, kde_confidence_band
+from .regression import debiased_local_linear, regression_confidence_band
+from .sets import (
+    density_level_set,
+    density_level_set_confidence,
+    hausdorff_distance,
+    inverse_regression,
+    inverse_regression_confidence,
+    invert_confidence_band,
+    level_set,
+)
+
+__all__ = [
+    "ConfidenceBandResult",
+    "EstimateResult",
+    "SetEstimateResult",
+    "debiased_kde",
+    "debiased_local_linear",
+    "density_bandwidth",
+    "density_level_set",
+    "density_level_set_confidence",
+    "hausdorff_distance",
+    "inverse_regression",
+    "inverse_regression_confidence",
+    "invert_confidence_band",
+    "kde_confidence_band",
+    "level_set",
+    "regression_bandwidth",
+    "regression_confidence_band",
+]
+
+__version__ = "0.1.0"

debiased_inference-0.1.0/src/debiased_inference/_results.py

@@ -0,0 +1,90 @@
+"""Immutable result containers for the public API."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+from numpy.typing import NDArray
+
+FloatArray = NDArray[np.float64]
+
+
+@dataclass(frozen=True)
+class EstimateResult:
+    """A nonparametric estimate evaluated on a finite grid."""
+
+    points: FloatArray
+    estimate: FloatArray
+    bandwidth: float
+    tau: float
+    method: str
+
+    def __repr__(self) -> str:
+        return (
+            f"EstimateResult(method={self.method!r}, points={len(self.points)}, "
+            f"bandwidth={self.bandwidth:.6g}, tau={self.tau:.6g})"
+        )
+
+
+@dataclass(frozen=True)
+class ConfidenceBandResult:
+    """A simultaneous bootstrap confidence band on a finite grid."""
+
+    points: FloatArray
+    estimate: FloatArray
+    lower: FloatArray
+    upper: FloatArray
+    critical_value: float
+    bandwidth: float
+    tau: float
+    confidence: float
+    n_boot: int
+    bootstrap_statistics: FloatArray
+    method: str
+    studentized: bool = False
+    standard_error: FloatArray | None = None
+
+    @property
+    def width(self) -> FloatArray:
+        """Pointwise width of the simultaneous band."""
+        return self.upper - self.lower
+
+    def __repr__(self) -> str:
+        return (
+            f"ConfidenceBandResult(method={self.method!r}, points={len(self.points)}, "
+            f"confidence={self.confidence:.3g}, n_boot={self.n_boot}, "
+            f"bandwidth={self.bandwidth:.6g})"
+        )
+
+
+@dataclass(frozen=True)
+class SetEstimateResult:
+    """A grid-based estimate or confidence region for a level set.
+
+    ``roots`` is a vector for a one-dimensional level set and an ``(k, 2)``
+    contour point cloud for a two-dimensional level set.
+    """
+
+    points: FloatArray
+    mask: NDArray[np.bool_]
+    roots: FloatArray
+    level: float
+    method: str
+    radius: float | None = None
+    confidence: float | None = None
+    n_boot: int | None = None
+    bootstrap_statistics: FloatArray | None = None
+
+    @property
+    def geometry(self) -> FloatArray:
+        """Return the interpolated level-set geometry."""
+        return self.roots
+
+    def __repr__(self) -> str:
+        size = len(self.roots)
+        detail = f", radius={self.radius:.6g}" if self.radius is not None else ""
+        return (
+            f"SetEstimateResult(method={self.method!r}, level={self.level:.6g}, "
+            f"geometry_points={size}{detail})"
+        )

debiased_inference-0.1.0/src/debiased_inference/_validation.py

@@ -0,0 +1,81 @@
+"""Shared input validation helpers."""
+
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+FloatArray = NDArray[np.float64]
+
+
+def as_samples(x: ArrayLike, *, name: str = "x") -> FloatArray:
+    """Return observations as an ``(n, d)`` float array."""
+    values = np.asarray(x, dtype=float)
+    if values.ndim == 1:
+        values = values[:, None]
+    if values.ndim != 2 or values.shape[0] < 2 or values.shape[1] < 1:
+        raise ValueError(f"{name} must contain at least two observations")
+    if not np.all(np.isfinite(values)):
+        raise ValueError(f"{name} must contain only finite values")
+    if np.all(np.ptp(values, axis=0) == 0):
+        raise ValueError(f"{name} must contain at least two distinct observations")
+    return values
+
+
+def as_vector(x: ArrayLike, *, name: str) -> FloatArray:
+    """Return a finite, non-empty one-dimensional float array."""
+    values = np.asarray(x, dtype=float)
+    if values.ndim != 1 or values.size == 0:
+        raise ValueError(f"{name} must be a non-empty one-dimensional array")
+    if not np.all(np.isfinite(values)):
+        raise ValueError(f"{name} must contain only finite values")
+    return values
+
+
+def as_evaluation_points(
+    points: ArrayLike | None, samples: FloatArray, *, grid_size: int = 200
+) -> FloatArray:
+    """Validate or generate evaluation points with the samples' dimension."""
+    dimension = samples.shape[1]
+    if points is None:
+        if dimension != 1:
+            raise ValueError("evaluation points are required for multivariate data")
+        if not isinstance(grid_size, (int, np.integer)) or grid_size < 2:
+            raise ValueError("grid_size must be an integer of at least 2")
+        spread = float(np.std(samples[:, 0], ddof=1))
+        pad = 0.05 * max(float(np.ptp(samples[:, 0])), spread)
+        if pad == 0:
+            pad = 1.0
+        return np.linspace(samples[:, 0].min() - pad, samples[:, 0].max() + pad, grid_size)[:, None]
+
+    result = np.asarray(points, dtype=float)
+    if dimension == 1 and result.ndim == 1:
+        result = result[:, None]
+    if result.ndim != 2 or result.shape[1] != dimension or result.shape[0] == 0:
+        raise ValueError(f"evaluation points must have shape (m, {dimension})")
+    if not np.all(np.isfinite(result)):
+        raise ValueError("evaluation points must contain only finite values")
+    return result
+
+
+def positive_scalar(value: float, *, name: str) -> float:
+    """Validate a finite positive scalar."""
+    result = float(value)
+    if not np.isfinite(result) or result <= 0:
+        raise ValueError(f"{name} must be a finite positive scalar")
+    return result
+
+
+def bootstrap_parameters(confidence: float, n_boot: int) -> tuple[float, int]:
+    """Validate confidence level and bootstrap count."""
+    confidence = float(confidence)
+    if not 0 < confidence < 1:
+        raise ValueError("confidence must be strictly between 0 and 1")
+    if not isinstance(n_boot, (int, np.integer)) or n_boot < 1:
+        raise ValueError("n_boot must be a positive integer")
+    return confidence, int(n_boot)
+
+
+def public_points(points: FloatArray) -> FloatArray:
+    """Represent one-dimensional grids as vectors in public results."""
+    return points[:, 0].copy() if points.shape[1] == 1 else points.copy()

debiased_inference-0.1.0/src/debiased_inference/bandwidth.py

@@ -0,0 +1,144 @@
+"""Bandwidth selectors for ordinary KDE and local-linear regression."""
+
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import ArrayLike
+
+from ._validation import as_samples, as_vector, positive_scalar
+
+
+def density_bandwidth(
+    x: ArrayLike,
+    *,
+    method: str = "normal_reference",
+    candidates: ArrayLike | None = None,
+    block_size: int = 512,
+) -> float:
+    """Select an isotropic bandwidth for the ordinary KDE.
+
+    ``method="normal_reference"`` uses Silverman's robust rule
+    ``0.9 min(sd, IQR / 1.34) n^(-1/5)``. In higher dimensions the scalar
+    scale is the geometric mean of positive marginal robust scales and the
+    normal-reference dimension adjustment is used.
+
+    ``method="cv"`` minimizes the least-squares cross-validation criterion
+    over ``candidates``. If candidates are omitted, a geometric grid centered
+    on the normal-reference choice is used. Pairwise calculations are blocked
+    to use ``O(n * block_size)`` rather than ``O(n^2)`` memory.
+    """
+    samples = as_samples(x)
+    if method not in {"normal_reference", "cv"}:
+        raise ValueError("method must be 'normal_reference' or 'cv'")
+    n, dimension = samples.shape
+    standard_deviation = np.std(samples, axis=0, ddof=1)
+    quartiles = np.percentile(samples, [25, 75], axis=0)
+    robust = (quartiles[1] - quartiles[0]) / 1.34
+    scales = np.minimum(standard_deviation, robust)
+    scales = np.where(scales > 0, scales, standard_deviation)
+    positive = scales[scales > 0]
+    if positive.size == 0:
+        raise ValueError("cannot select bandwidth from zero-scale data")
+    scale = float(np.exp(np.mean(np.log(positive))))
+    if dimension == 1:
+        factor = 0.9 * n ** (-1.0 / 5.0)
+    else:
+        factor = (4.0 / (dimension + 2.0)) ** (1.0 / (dimension + 4.0))
+        factor *= n ** (-1.0 / (dimension + 4.0))
+    reference = positive_scalar(scale * factor, name="selected bandwidth")
+    if method == "normal_reference":
+        if candidates is not None:
+            raise ValueError("candidates are only used when method='cv'")
+        return reference
+
+    if candidates is None:
+        candidate_values = reference * np.geomspace(0.35, 2.5, 31)
+    else:
+        candidate_values = as_vector(candidates, name="candidates")
+        if np.any(candidate_values <= 0):
+            raise ValueError("candidates must be positive")
+    if not isinstance(block_size, (int, np.integer)) or block_size < 1:
+        raise ValueError("block_size must be a positive integer")
+    scores = np.empty(candidate_values.size, dtype=float)
+    for index, candidate in enumerate(candidate_values):
+        h = float(candidate)
+        integrated_normalizer = (4.0 * np.pi * h**2) ** (-0.5 * dimension)
+        ordinary_normalizer = (2.0 * np.pi * h**2) ** (-0.5 * dimension)
+        integrated_sum = 0.0
+        ordinary_sum = 0.0
+        for start in range(0, n, int(block_size)):
+            stop = min(start + int(block_size), n)
+            differences = samples[start:stop, None, :] - samples[None, :, :]
+            distances_squared = np.sum(differences**2, axis=-1)
+            integrated_sum += integrated_normalizer * float(
+                np.sum(np.exp(-distances_squared / (4.0 * h**2)))
+            )
+            ordinary_sum += ordinary_normalizer * float(
+                np.sum(np.exp(-distances_squared / (2.0 * h**2)))
+            )
+        ordinary_off_diagonal = ordinary_sum - n * ordinary_normalizer
+        scores[index] = (
+            integrated_sum / n**2
+            - 2.0 * ordinary_off_diagonal / (n * (n - 1))
+        )
+    return float(candidate_values[int(np.argmin(scores))])
+
+
+def regression_bandwidth(
+    x: ArrayLike,
+    y: ArrayLike,
+    *,
+    candidates: ArrayLike | None = None,
+    n_folds: int = 5,
+    random_state: int | None = 0,
+) -> float:
+    """Select a local-linear bandwidth by deterministic K-fold CV.
+
+    Candidate loss is mean squared prediction error from the ordinary
+    local-linear smoother. Failed boundary fits are excluded; a candidate is
+    eligible only if every held-out point can be predicted.
+    """
+    from .regression import _local_polynomial
+
+    x_values = as_vector(x, name="x")
+    y_values = as_vector(y, name="y")
+    if x_values.size != y_values.size:
+        raise ValueError("x and y must have the same length")
+    if np.ptp(x_values) == 0:
+        raise ValueError("x must contain at least two distinct values")
+    n = x_values.size
+    if not isinstance(n_folds, (int, np.integer)) or not 2 <= n_folds <= n:
+        raise ValueError("n_folds must be an integer between 2 and len(x)")
+
+    if candidates is None:
+        scale = min(float(np.std(x_values, ddof=1)), float(np.ptp(x_values)) / 4.0)
+        base = max(scale * n ** (-1.0 / 5.0), np.finfo(float).eps)
+        candidate_values = base * np.geomspace(0.35, 2.5, 21)
+    else:
+        candidate_values = as_vector(candidates, name="candidates")
+        if np.any(candidate_values <= 0):
+            raise ValueError("candidates must be positive")
+
+    generator = np.random.default_rng(random_state)
+    order = generator.permutation(n)
+    folds = np.array_split(order, n_folds)
+    losses = np.full(candidate_values.size, np.inf)
+    for candidate_index, candidate in enumerate(candidate_values):
+        squared_errors: list[np.ndarray] = []
+        valid = True
+        for held_out in folds:
+            keep = np.ones(n, dtype=bool)
+            keep[held_out] = False
+            predicted = _local_polynomial(
+                x_values[keep], y_values[keep], x_values[held_out],
+                float(candidate), degree=1, derivative=0,
+            )
+            if np.any(~np.isfinite(predicted)):
+                valid = False
+                break
+            squared_errors.append((y_values[held_out] - predicted) ** 2)
+        if valid:
+            losses[candidate_index] = float(np.mean(np.concatenate(squared_errors)))
+    if not np.any(np.isfinite(losses)):
+        raise RuntimeError("all candidate bandwidths produced singular local fits")
+    return float(candidate_values[int(np.argmin(losses))])