deploy: 74f2e54

Author: rollingstorms

.nojekyll

@@ -0,0 +1,32 @@
+# API Reference
+
+## compute_operating_profile
+
+```python
+from opproplot import compute_operating_profile
+profile = compute_operating_profile(y_true, y_score, bins=40, score_range=(0, 1))
+```
+
+- `y_true`: array-like of shape (n_samples,), binary labels.
+- `y_score`: array-like of shape (n_samples,), predicted scores or probabilities.
+- `bins`: number of score bins (default 40).
+- `score_range`: tuple or None. If None, uses min/max of scores.
+- `show_key`: display combined legend for bars and lines (default True).
+- `key_location`: `"inside"` (axis legend) or `"outside"` (fig-level, right dock).
+- `show_grid`: draw a background grid on the metric axis (default False).
+- `grid_kwargs`: dict passed to `ax_metric.grid`, e.g., `{"alpha": 0.2, "linestyle": "--"}`.
+
+Returns an `OperatingProfile` dataclass with:
+- `edges`, `mids`, `pos_hist`, `neg_hist`, `tpr`, `fpr`, `accuracy`.
+
+## operating_profile_plot
+
+```python
+from opproplot import operating_profile_plot
+fig, ax_hist, ax_metric = operating_profile_plot(y_true, y_score, bins=30, show_accuracy=True)
+```
+
+- `show_accuracy`: include the dashed accuracy curve (default True).
+- `ax`: optional Matplotlib axis to draw on; otherwise creates a new figure.
+
+Returns `(fig, ax_hist, ax_metric)` for further styling or saving.

api.md

@@ -0,0 +1,26 @@
+# Examples
+
+Use these patterns to compare models and datasets.
+
+## Breast cancer (scikit-learn)
+
+- Load `sklearn.datasets.load_breast_cancer`.
+- Train a logistic regression or gradient boosting model.
+- Plot the operating profile on the test split to inspect separability.
+
+## Fraud-like imbalance
+
+- Simulate or load an imbalanced dataset.
+- Compare a calibrated model vs an overconfident one.
+- Observe how class imbalance alters histogram heights and accuracy peaks.
+
+## Good vs bad model
+
+- Train two models on the same data.
+- Plot both operating profiles side by side.
+- Look for:
+  - Separation of score distributions.
+  - Lower FPR for the same TPR.
+  - Stability of accuracy across thresholds.
+
+Swap in your own datasets; the plotting API stays the same.

assets/opproplot_breast_cancer.png

@@ -0,0 +1,66 @@
+# Getting Started
+
+This page shows how to generate an operating profile in a notebook and how to interpret it for common binary classifiers.
+
+## Setup
+
+```bash
+pip install -e .
+```
+
+```python
+import numpy as np
+from opproplot import operating_profile_plot
+```
+
+## Basic example
+
+```python
+rng = np.random.default_rng(0)
+y_true = rng.integers(0, 2, size=5000)
+scores = rng.random(size=5000)
+
+fig, ax_hist, ax_metric = operating_profile_plot(y_true, scores, bins=30)
+```
+
+- Left axis: stacked histogram of scores by class.
+- Right axis: TPR, FPR, and Accuracy evaluated at each bin midpoint threshold.
+- Choose thresholds where TPR/FPR trade-offs make sense for your application.
+
+![Opproplot simulated example](assets/opproplot_example.png)
+
+## Detailed example (scikit-learn)
+
+```python
+from sklearn.datasets import load_breast_cancer
+from sklearn.model_selection import train_test_split
+from sklearn.linear_model import LogisticRegression
+
+data = load_breast_cancer()
+X_train, X_test, y_train, y_test = train_test_split(
+    data.data, data.target, test_size=0.3, random_state=0, stratify=data.target
+)
+
+clf = LogisticRegression(max_iter=500)
+clf.fit(X_train, y_train)
+
+y_score = clf.predict_proba(X_test)[:, 1]
+
+fig, ax_hist, ax_metric = operating_profile_plot(y_test, y_score, bins=30)
+ax_hist.set_title("Breast cancer classifier operating profile")
+```
+
+![Opproplot breast cancer example](assets/opproplot_breast_cancer.png)
+
+Pattern applies to other models:
+
+- Random forest / gradient boosting: use `model.predict_proba(X)[:, 1]`.
+- XGBoost / LightGBM: use `predict` outputs as scores.
+
+## Interpreting the plot
+
+- Separability: wider gap between class histograms indicates better discrimination.
+- Threshold effects: steep TPR drops highlight sensitive regions.
+- Accuracy peak: dashed accuracy curve shows the maximizer without trial-and-error.
+
+For deeper theory and metric formulas, see [Theory](theory.md).

assets/opproplot_example.png

@@ -0,0 +1,44 @@
+# Opproplot
+
+A compact operating profile plot for binary classifiers: stacked score histograms by class plus TPR/FPR/Accuracy curves at bin-midpoint thresholds. One view to understand every possible cutoff.
+
+![Opproplot hero](assets/opproplot_hero.png)
+
+## Why Opproplot
+
+- See score separation between classes directly.
+- Trace how recall and false positives move as you slide the threshold.
+- Spot the accuracy peak without losing visibility into the distribution.
+
+## Install
+
+```bash
+pip install -e .
+```
+
+## Quickstart
+
+```python
+import numpy as np
+from opproplot import operating_profile_plot
+
+rng = np.random.default_rng(0)
+y_true = rng.integers(0, 2, size=5000)
+scores = rng.random(size=5000)
+
+operating_profile_plot(y_true, scores, bins=30)
+```
+
+![Opproplot simulated example](assets/opproplot_example.png)
+
+## Detailed example (scikit-learn)
+
+![Opproplot breast cancer](assets/opproplot_breast_cancer.png)
+
+## Learn more
+
+- [Getting started](getting_started.md): notebook-friendly walkthroughs.
+- [Theory](theory.md): decision rules, distributions, and threshold geometry.
+- [Examples](examples.md): real datasets and comparisons.
+- [API](api.md): function reference and parameters.
+- [Roadmap](roadmap.md): upcoming features.

assets/opproplot_hero.png

@@ -0,0 +1,14 @@
+# Roadmap
+
+Feature | Status
+--- | ---
+Base Opproplot (TPR/FPR/Accuracy) | ✅ in v0.1.0
+MCC / Balanced Accuracy overlays | 🔜
+Plotly interactive version | 🔜
+Custom binning (score or segment axis) | 🔜
+Multi-class (one-vs-rest + small multiples) | 🔜
+Threshold selection heuristics (maximize metric) | 🔜
+Dash app for validation workflows | Future
+Integration into sklearn-like pipeline | Future
+
+Ideas and contributions are welcome; file issues or PRs to shape the next release.

examples.md

@@ -0,0 +1,24 @@
+# Theory: The Geometry of Thresholds
+
+Opproplot treats thresholding as a geometric object over score space. For a scoring function f(x) and threshold t, the decision rule is
+
+h_t(x) = 1{f(x) >= t}.
+
+## Distributions
+
+- p(s | Y=1) and p(s | Y=0) are estimated with class-conditional histograms.
+- Midpoints of bins act as candidate thresholds.
+
+## Metrics as cumulative integrals
+
+- True Positive Rate: TPR(t) = P(f(X) >= t | Y=1).
+- False Positive Rate: FPR(t) = P(f(X) >= t | Y=0).
+- Accuracy: Acc(t) = [TP(t) + TN(t)] / (P + N).
+
+These are computed in a single pass over scores by sorting once and evaluating cumulative counts at the bin midpoints.
+
+## Why this view
+
+- Links the score distribution to threshold outcomes directly.
+- Shows the full family of operating points without switching plots.
+- Works for imbalanced data: histogram heights reveal prevalence while TPR/FPR curves show trade-offs.