probcal 0.1.0__tar.gz

probcal-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    name: Test on Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.11', '3.12', '3.13']
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv pip install --system -e ".[dev,viz]"
+
+      - name: Lint
+        run: ruff check .
+
+      - name: Type-check
+        if: matrix.python-version == '3.11'
+        run: mypy
+
+      - name: Run tests
+        run: pytest -q

probcal-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,40 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - 'src/probcal/**'
+      - 'CHANGELOG.md'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Install dependencies
+        run: uv pip install --system -e ".[docs,viz]"
+
+      - name: Configure git identity
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - name: Build and deploy
+        run: mkdocs gh-deploy --force

probcal-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,94 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  test:
+    name: Test before release
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: uv pip install --system -e ".[dev,viz]"
+
+      - name: Run tests
+        run: pytest -q
+
+  build:
+    name: Build distribution
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Verify tag matches package version
+        run: |
+          VERSION="$(uvx hatchling version)"
+          [ "$VERSION" = "${GITHUB_REF_NAME#v}" ] || { echo "tag ${GITHUB_REF_NAME} does not match version ${VERSION}"; exit 1; }
+
+      - name: Build package
+        run: uv build --sdist --wheel
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: publish-testpypi
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

probcal-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+site/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.cache/
+.superpowers/
+.claude/
+.plan/

probcal-0.1.0/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versioning: [SemVer](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-08-07
+
+First public release on PyPI.
+
+### Fixed
+
+- `reliability_binned`: Wilson interval bounds are now forced to contain the point estimate (floating-point noise at zero-event bins could push `ci_low` above a 0.0 event rate, breaking error-bar rendering)
+- `plot_reliability(scale="logit")`: bins with an event rate of exactly 0 or 1 (no finite logit) are omitted from the point layer instead of rendering at the clipping floor and crushing the axis; they remain visible in the count margin
+
+### Added
+
+- Packaging and CI: PEP 639 license metadata (SPDX `license = "MIT"` plus `license-files`, replacing the deprecated table form), Python 3.13 classifier, `Development Status :: 4 - Beta`, a tag-vs-version consistency check in the publish workflow, and a `ci.yml` matrix running lint, type-check, and the test suite on Python 3.11/3.12/3.13
+- Documentation: generated example figures in the visualization chapter, "In probcal" code snippets in every concept chapter, and a probcal-vs-netcal guidance note in the FAQ
+
+- Polish: README quickstart with real printed output, feature matrix vs scikit-learn/netcal/single-method packages, performance note on the deliberate absence of Rust acceleration, docs cross-linking pass
+- Datasets, tutorial, and user docs: `make_pd_portfolio` (beta-family generative miscalibration with exact event-rate anchoring), executed tutorial notebook `pd_calibration_walkthrough.ipynb` (diagnose → select → fit → re-anchor → backtest → threshold translation, incl. the counterfactual-engine interop recipe), `getting-started.md` with a runnable quickstart and its printed output, `how-it-works.md` pipeline walkthrough with schema, three-page mkdocstrings API reference, and the FAQ (inverse-map protocol, `Target.probability` trap, selection rules)
+- Automatic selection: `CalibratorSelector` — default 8-candidate menu per spec, inner stratified seeded K-fold with structurally out-of-fold-only scoring, criteria log_loss/brier/ici/smooth_ece/ece_sweep (plain ECE and Hosmer–Lemeshow refused), guardrail flags on pooled out-of-fold predictions, one-standard-error parsimony tie-break, winner refit on the full set, ranked `SelectionReport`; 9 tests incl. a spy-calibrator structural no-leakage check and the parsimony-on-calibrated-data behavior
+- Wrapper flows: `CalibratedModel` — prefit flow (score + calibrate, the credit-risk canon), cv flow with duck-typed cloning (sklearn `clone` if installed, else deepcopy) and stratified seeded folds, `ensemble=False` pooled default (one calibrator on out-of-fold scores, final model refit) vs `ensemble=True` fold averaging; `offset_to` appending inspectable `LogitOffset` stages; composed `interval_inverse` and `affine_logit_coeffs_`; `predict_proba`/`predict_proba_2d`; structural no-leakage tests with a clone-surviving spy model (out-of-fold scoring disjoint from training rows, each row scored exactly once)
+- Inverse maps and thresholds: `interval_inverse(lo, hi, *, space, buffer_logit)` implemented across the catalog — closed forms (Platt, temperature, `LogitOffset`), block-structure searchsorted (isotonic, CIR, histogram, scaling-binning), monotone bisection (beta, spline, Venn–Abers); `UnattainableTargetError` instead of silent clamping; non-monotone calibrators refuse with an explanatory `NotImplementedError`; `thresholds.py` with `calibrated_interval_to_raw` and the masterscale `calibrated_bands_to_raw`; 16 tests covering the full spec §10 list (round-trips, block-edge semantics, offset −δ shift, buffer monotonicity, space consistency)
+- Attribution adjustment: `adjust_attributions` → `AdjustedAttribution` — affine-exact mode (exact composed Shapley values for Platt/temperature/offset via `affine_logit_coeffs_`) and Aumann–Shapley mode (exact additivity for any calibrator, central-difference fallback on degenerate rows); logit and probability scales; shap.Explanation duck-typing without a shap import; 10 tests incl. affine/AS 1e-12 equivalence and sign/rank invariance
+- Logit offset: `LogitOffset` — explicit-delta and target-mean modes (unique bisection root, unit-tested against a brute-force grid), audit trail (`delta_`, `pre_mean_`, `post_mean_`, timestamp), `audit_report()` with pre/post guardrails, `interpret()` with odds-factor and central-tendency readings, affine logit coefficients for attribution composition
+- Curves, belt, and plots: `curves.py` — `reliability_binned` (Wilson CIs, both scales), `reliability_loess`, `reliability_spline`, `calibration_belt` (GiViTI-style: forward LR degree selection ≤4, information-matrix pointwise bands, identity-test p-value; reimplemented from the Nattino papers); `plots.py` ([viz]-guarded) — `plot_reliability` with logit-scale probability-labeled ticks and count margin, `plot_belt`, `plot_comparison`, `plot_interval`, `plot_selection`; `SmoothReliabilityCurve` result dataclass; 11 tests incl. a hand-checked Wilson interval and belt null/alternative behavior
+- Metrics catalog: `probcal.metrics` complete — proper scores (`log_loss`, `brier_score`, `brier_skill_score`, Murphy decomposition with optional bias correction, log-loss calibration/refinement split), binned estimators (`ece` l1/l2/max, `ece_debiased`, `ece_sweep`, `adaptive_ece`, `hosmer_lemeshow`), binning-free estimators (`smooth_ece` with self-consistent bandwidth, `ecce`, `ici`/`e50`/`e90`/`emax`, `spiegelhalter_z`), the recalibration-regression framework (`calibration_intercept`/`_slope`/`_test`, `calibration_guardrails`), per-grade backtests (`binomial_grade_test`, `jeffreys_grade_test` with traffic lights), and `evaluate()` with seeded bootstrap percentile CIs; 38 tests incl. hand-computed cases and sklearn/scipy references
+- Spline calibrator: `SplineCalibrator` — natural cubic basis on the logit scale, penalized IRLS with second-difference roughness penalty, λ by stratified K-fold CV on log loss, effective degrees of freedom reported, post-fit monotonicity check with warning; completes the spec §6 calibrator catalog (11 of 11)
+- Binning + Bayesian calibrators: `HistogramBinningCalibrator` (equal-mass/equal-width, Jeffreys shrinkage, empty-bin fallback, post-fit monotonicity flag), `ScalingBinningCalibrator` (Platt stage + equal-mass binning of fitted values), `BBQCalibrator` (Beta–Binomial marginal likelihood over a B-grid, Jeffreys prior, top-3 reporting), `ENIRCalibrator` (nearly-isotonic mPAVA path from raw data to the isotonic fit, BIC-weighted ensemble, `is_monotone_ = False`); 20 tests incl. hand-computed bin rates and the path-endpoint-equals-PAVA anchor
+- Isotonic family + Venn–Abers: `IsotonicCalibrator` (PAVA step map, tie pooling, clamping, optional linear interpolation, block-structure attributes), `CenteredIsotonicCalibrator` (CIR through weight-centered block points), `VennAbersCalibrator` (IVAP with `predict_interval()`, log-loss-minimax scalarization, width reporting in `interpret()`), `CrossVennAbersCalibrator` (stratified seeded folds, geometric-mean merge, conservative envelope interval); 19 tests incl. direct-refit agreement and width-shrinkage checks
+- Base API + parametric calibrators: `BaseCalibrator` (fit/predict_proba/predict_proba_2d/interpret, manual get_params/set_params, `is_monotone_`, `affine_logit_coeffs_`, `interval_inverse` contract stub), `PlattCalibrator` (Lin–Lin–Weng target smoothing), `TemperatureCalibrator` (safeguarded 1-D NLL solve), `BetaCalibrator` (variants abm/ab/a, betacal negative-coefficient refit, `constraint_active_`); public exports incl. `logit`/`expit`; 30 tests (identity/distortion recovery, monotonicity, small-sample stability, interpret contract)
+- Numerical core: `_math.py` (overflow-safe logit/expit, weighted PAVA with block structure, IRLS logistic regression with ridge stabilization and separation detection, safeguarded 1-D Newton and bisection, vectorized lgamma/erf, regularized incomplete beta and lower incomplete gamma, chi-square and normal quantiles, tricube LOESS, natural cubic spline basis), `_validation.py` (score/target/weight validation with 1e-12 clipping), `_results.py` (frozen result dataclasses with `as_dict()` and aligned-table reprs); 49 unit tests plus 9 reference tests against scipy/scikit-learn/statsmodels (betainc and gammainc within 1e-12, IRLS within rtol 1e-8)
+- Repository scaffold: src layout with docstring-only modules, tooling (uv, ruff, black, mypy, pytest), CI workflows (docs deploy, PyPI publish — tag-gated), documentation skeleton (mkdocs-material + MathJax), MIT license, citation metadata
+- Reference verification: all 12 ⚠ references of the spec verified against primary sources; completed bibliographic records logged in `docs/DECISIONS.md` entries 10–21
+- Theory guidebook, chunk 1: `concepts/why-calibration.md` (definitions, sources of miscalibration, decisioning and regulatory consequences, proper-scoring-rule lens) and `concepts/methods-parametric.md` (Platt, temperature, beta: derivations, parameter interpretation, worked reading)
+- Theory guidebook, chunk 4 (completes the guidebook — ~16,400 words total): `concepts/shap-calibration.md` (identifiability obstacle, affine-exact class, Aumann–Shapley mode, invariance properties), `concepts/inverse-maps.md` (preimage identity, generalized inverses, attainability, buffer_logit drift robustness, masterscale workflow), `concepts/auto-selection.md` (selector protocol, structural no-leakage, report reading), `concepts/visualization.md` (reliability constructions, logit-scale rationale, calibration belt)
+- Theory guidebook, chunk 3: `concepts/metrics.md` (full metric catalog with formulas and pathologies, bootstrap-CI protocol, report-reading order, selection-suitability table), `concepts/data-splitting.md` (prefit vs cv flows, ensemble vs pooled, calibration-set sizing, nested selection), `concepts/offset.md` (uniqueness of the bisection root, King–Zeng/Elkan/Tasche equivalences, worked re-anchoring, audit practice)
+- Theory guidebook, chunk 2: `concepts/methods-nonparametric.md` (PAVA with worked micro-example, CIR, histogram binning, scaling-binning sample-complexity argument, BBQ, ENIR, spline calibration, properties table) and `concepts/methods-distribution-free.md` (IVAP construction, validity guarantee scope, scalarization caveat, exchangeability limits, CVAP geometric-mean merge)
+
+[Unreleased]: https://github.com/wlazlod/probcal/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/wlazlod/probcal/releases/tag/v0.1.0

probcal-0.1.0/CITATION.cff

@@ -0,0 +1,11 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+type: software
+title: "probcal: universal post-hoc probability calibration for binary classifiers"
+authors:
+  - family-names: "Wlazło"
+    given-names: "Daniel"
+version: 0.1.0
+date-released: 2026-08-07
+license: MIT
+repository-code: "https://github.com/wlazlod/probcal"

probcal-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Wlazło
+
+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.

probcal-0.1.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: probcal
+Version: 0.1.0
+Summary: Universal post-hoc probability calibration for binary classifiers: methods, metrics, diagnostics, and auditable offsetting — numpy-only.
+Project-URL: Homepage, https://github.com/wlazlod/probcal
+Project-URL: Documentation, https://wlazlod.github.io/probcal/
+Project-URL: Changelog, https://github.com/wlazlod/probcal/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/wlazlod/probcal/issues
+Author: Daniel Wlazło
+License-Expression: MIT
+License-File: LICENSE
+Keywords: binary-classification,calibration,credit-risk,isotonic-regression,probability,reliability
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.26
+Provides-Extra: dev
+Requires-Dist: black>=24; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: scikit-learn>=1.4; extra == 'dev'
+Requires-Dist: scipy>=1.11; extra == 'dev'
+Requires-Dist: statsmodels>=0.14; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: ipykernel>=6; extra == 'docs'
+Requires-Dist: mkdocs-jupyter>=0.24; extra == 'docs'
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
+Provides-Extra: viz
+Requires-Dist: matplotlib>=3.8; extra == 'viz'
+Description-Content-Type: text/markdown
+
+# probcal
+
+[![PyPI](https://img.shields.io/pypi/v/probcal.svg)](https://pypi.org/project/probcal/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](pyproject.toml)
+
+Universal post-hoc probability calibration for binary classifiers: methods, metrics,
+diagnostics, and auditable offsetting — **numpy-only**.
+
+`probcal` unifies the binary calibration literature (Platt, temperature, beta, isotonic,
+centered isotonic, histogram binning, scaling-binning, BBQ, ENIR, Venn–Abers, spline
+calibration), an extensive catalog of calibration evaluation metrics and statistical tests,
+calibration visualization on both probability and logit scales, an auditable logit-offset
+(central tendency) adjustment, automatic method selection under nested validation, and two
+data flows (prefit and cross-validation). Primary application domain: credit-risk PD models;
+the package is fully general.
+
+**Status:** released on PyPI, beta. The API is stable enough to build on; breaking changes
+bump the minor version until 1.0.
+
+## Installation
+
+```bash
+pip install probcal            # runtime: numpy only
+pip install "probcal[viz]"     # + matplotlib for probcal.plots
+```
+
+Development setup (tests, lint, type-check):
+
+```bash
+git clone https://github.com/wlazlod/probcal && cd probcal
+uv sync --extra dev
+```
+
+## Quickstart
+
+```python
+from probcal import BetaCalibrator, make_pd_portfolio
+from probcal.metrics import calibration_guardrails
+
+port = make_pd_portfolio(n=8000, random_state=42)   # synthetic 3% PD portfolio
+
+g_before = calibration_guardrails(port.y, port.scores)
+print(f"before: slope={g_before.slope:.3f}  intercept={g_before.intercept:+.3f}  ok={g_before.all_ok}")
+
+cal = BetaCalibrator().fit(port.scores, port.y)
+p = cal.predict_proba(port.scores)
+
+g_after = calibration_guardrails(port.y, p)
+print(f"after:  slope={g_after.slope:.3f}  intercept={g_after.intercept:+.3f}  ok={g_after.all_ok}")
+print()
+print(cal.interpret())
+```
+
+Output:
+
+```text
+before: slope=0.968  intercept=-0.765  ok=False
+after:  slope=1.000  intercept=+0.000  ok=True
+
+Interpretation[BetaCalibrator]
+parameter  value
+---------  --------
+a          0.875054
+b          1.58922
+c          -1.15227
+- a = 0.875: sensitivity near s -> 0; a < 1 raises the smallest probabilities (model was overconfident in the low tail), a > 1 deepens them
+- b = 1.589: sensitivity near s -> 1; the mirrored reading for the high tail
+- c = -1.152: base-rate shift of -1.152 log-odds, odds factor 0.316
+- identity map corresponds to (a, b, c) = (1, 1, 0)
+- a != b (gap -0.714): asymmetric tail distortion that no symmetric (Platt/temperature) map could express
+```
+
+Automatic selection, model wrapping, offsetting, and threshold translation:
+
+```python
+from probcal import CalibratedModel, CalibratorSelector, PlattCalibrator
+
+sel = CalibratorSelector().fit(s_cal, y_cal)             # nested CV, log-loss criterion
+wrapped = CalibratedModel(model, PlattCalibrator(), flow="prefit").fit(X_cal, y_cal)
+wrapped.offset_to(target_mean=0.031)                     # auditable central-tendency stage
+lo_z, hi_z = wrapped.interval_inverse(0.0, 0.02, space="logit")   # "PD <= 2%" in raw margins
+```
+
+## Why probcal
+
+| Capability | probcal | scikit-learn | netcal | single-method packages¹ |
+|---|---|---|---|---|
+| Calibration methods | 11 | 2 | many | 1 each |
+| Runtime dependencies | numpy | scipy stack | torch stack | varies |
+| Logit-scale diagnostics (low-PD readable) | yes | — | — | — |
+| First-class auditable offset (central tendency) | yes | — | — | — |
+| Automatic selection under nested validation | yes | — | — | — |
+| Venn–Abers intervals | yes | — | — | venn-abers |
+| Metric catalog with selection-suitability guidance | yes | partial | partial | — |
+| Per-grade regulatory backtests (binomial, Jeffreys) | yes | — | — | — |
+| Calibrated→raw threshold translation (`interval_inverse`) | yes | — | — | — |
+| SHAP additivity repair on the calibrated scale | yes | — | — | — |
+| Parameter interpretation (`interpret()`) on every method | yes | — | — | — |
+
+¹ betacal, venn-abers, ml-insights.
+
+Performance note: the PAVA family and special functions are hand-rolled numpy/stdlib;
+profiling on real workloads has not shown them to be a bottleneck. Rust acceleration is
+deliberately out of scope unless benchmarks on production-sized portfolios say otherwise.
+
+## Documentation
+
+Built with mkdocs-material; run locally with `uv run mkdocs serve`. Start with
+*Getting started*, then the *Concepts* chapters — the package's theoretical foundation —
+and the executed *PD calibration walkthrough* notebook.
+
+## License
+
+MIT. See [LICENSE](LICENSE) and `docs/LICENSING.md` for the conceptual-reference policy on
+GPL-licensed R packages.

probcal-0.1.0/README.md

@@ -0,0 +1,116 @@
+# probcal
+
+[![PyPI](https://img.shields.io/pypi/v/probcal.svg)](https://pypi.org/project/probcal/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](pyproject.toml)
+
+Universal post-hoc probability calibration for binary classifiers: methods, metrics,
+diagnostics, and auditable offsetting — **numpy-only**.
+
+`probcal` unifies the binary calibration literature (Platt, temperature, beta, isotonic,
+centered isotonic, histogram binning, scaling-binning, BBQ, ENIR, Venn–Abers, spline
+calibration), an extensive catalog of calibration evaluation metrics and statistical tests,
+calibration visualization on both probability and logit scales, an auditable logit-offset
+(central tendency) adjustment, automatic method selection under nested validation, and two
+data flows (prefit and cross-validation). Primary application domain: credit-risk PD models;
+the package is fully general.
+
+**Status:** released on PyPI, beta. The API is stable enough to build on; breaking changes
+bump the minor version until 1.0.
+
+## Installation
+
+```bash
+pip install probcal            # runtime: numpy only
+pip install "probcal[viz]"     # + matplotlib for probcal.plots
+```
+
+Development setup (tests, lint, type-check):
+
+```bash
+git clone https://github.com/wlazlod/probcal && cd probcal
+uv sync --extra dev
+```
+
+## Quickstart
+
+```python
+from probcal import BetaCalibrator, make_pd_portfolio
+from probcal.metrics import calibration_guardrails
+
+port = make_pd_portfolio(n=8000, random_state=42)   # synthetic 3% PD portfolio
+
+g_before = calibration_guardrails(port.y, port.scores)
+print(f"before: slope={g_before.slope:.3f}  intercept={g_before.intercept:+.3f}  ok={g_before.all_ok}")
+
+cal = BetaCalibrator().fit(port.scores, port.y)
+p = cal.predict_proba(port.scores)
+
+g_after = calibration_guardrails(port.y, p)
+print(f"after:  slope={g_after.slope:.3f}  intercept={g_after.intercept:+.3f}  ok={g_after.all_ok}")
+print()
+print(cal.interpret())
+```
+
+Output:
+
+```text
+before: slope=0.968  intercept=-0.765  ok=False
+after:  slope=1.000  intercept=+0.000  ok=True
+
+Interpretation[BetaCalibrator]
+parameter  value
+---------  --------
+a          0.875054
+b          1.58922
+c          -1.15227
+- a = 0.875: sensitivity near s -> 0; a < 1 raises the smallest probabilities (model was overconfident in the low tail), a > 1 deepens them
+- b = 1.589: sensitivity near s -> 1; the mirrored reading for the high tail
+- c = -1.152: base-rate shift of -1.152 log-odds, odds factor 0.316
+- identity map corresponds to (a, b, c) = (1, 1, 0)
+- a != b (gap -0.714): asymmetric tail distortion that no symmetric (Platt/temperature) map could express
+```
+
+Automatic selection, model wrapping, offsetting, and threshold translation:
+
+```python
+from probcal import CalibratedModel, CalibratorSelector, PlattCalibrator
+
+sel = CalibratorSelector().fit(s_cal, y_cal)             # nested CV, log-loss criterion
+wrapped = CalibratedModel(model, PlattCalibrator(), flow="prefit").fit(X_cal, y_cal)
+wrapped.offset_to(target_mean=0.031)                     # auditable central-tendency stage
+lo_z, hi_z = wrapped.interval_inverse(0.0, 0.02, space="logit")   # "PD <= 2%" in raw margins
+```
+
+## Why probcal
+
+| Capability | probcal | scikit-learn | netcal | single-method packages¹ |
+|---|---|---|---|---|
+| Calibration methods | 11 | 2 | many | 1 each |
+| Runtime dependencies | numpy | scipy stack | torch stack | varies |
+| Logit-scale diagnostics (low-PD readable) | yes | — | — | — |
+| First-class auditable offset (central tendency) | yes | — | — | — |
+| Automatic selection under nested validation | yes | — | — | — |
+| Venn–Abers intervals | yes | — | — | venn-abers |
+| Metric catalog with selection-suitability guidance | yes | partial | partial | — |
+| Per-grade regulatory backtests (binomial, Jeffreys) | yes | — | — | — |
+| Calibrated→raw threshold translation (`interval_inverse`) | yes | — | — | — |
+| SHAP additivity repair on the calibrated scale | yes | — | — | — |
+| Parameter interpretation (`interpret()`) on every method | yes | — | — | — |
+
+¹ betacal, venn-abers, ml-insights.
+
+Performance note: the PAVA family and special functions are hand-rolled numpy/stdlib;
+profiling on real workloads has not shown them to be a bottleneck. Rust acceleration is
+deliberately out of scope unless benchmarks on production-sized portfolios say otherwise.
+
+## Documentation
+
+Built with mkdocs-material; run locally with `uv run mkdocs serve`. Start with
+*Getting started*, then the *Concepts* chapters — the package's theoretical foundation —
+and the executed *PD calibration walkthrough* notebook.
+
+## License
+
+MIT. See [LICENSE](LICENSE) and `docs/LICENSING.md` for the conceptual-reference policy on
+GPL-licensed R packages.