edgepoint 1.0.0__tar.gz

edgepoint-1.0.0/LICENSE

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

edgepoint-1.0.0/PKG-INFO

@@ -0,0 +1,522 @@
+Metadata-Version: 2.4
+Name: edgepoint
+Version: 1.0.0
+Summary: Find the point in a numeric column above which a binary outcome becomes meaningfully and reliably better.
+Author: Henry
+License: MIT
+Keywords: threshold,decision-threshold,binary-classification,feature-engineering,data-analysis,analytics,statistics,edge,threshold-detection
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+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
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.21
+Requires-Dist: pandas>=1.5
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Dynamic: license-file
+Dynamic: requires-python
+
+# edgepoint
+
+> Find the point in a numeric column above which a binary outcome becomes meaningfully and reliably better.
+
+`edgepoint` is a lightweight Python library for discovering interpretable
+thresholds in numeric data. Given a numeric feature and a binary outcome,
+it answers one practical question:
+
+> **"Where does this variable start becoming good enough?"**
+
+Instead of fitting a predictive model, `edgepoint` searches for the point
+where performance becomes good **without giving up more of the population
+than necessary**. It favors thresholds that stay both **effective** and
+**widely applicable**, rather than isolating a tiny group with exceptional
+results. If no convincing threshold exists, it simply returns `None`.
+
+No charts. No notebook. Hand it a DataFrame, get a number back, built to be
+called by code, not stared at by a human.
+
+```python
+from edgepoint import find
+
+profile = find(
+    df,
+    outcome_col="hit",       # any binary (0/1 or True/False) column
+    compute_fallback=True,   # mandatory: fall back to best-available split, or report None
+)
+# {"score": 66.75, "age": None, ...}
+```
+
+---
+
+## Where this applies
+
+Any continuous metric + binary outcome pair, for example:
+
+- **Marketing**: at what engagement score does churn risk drop off
+- **Credit**: at what score does default rate become acceptable
+- **Healthcare**: at what biomarker level does an outcome rate jump
+- **Product**: at what usage count does upgrade-to-paid rate spike
+- **Manufacturing**: at what sensor reading does defect rate climb
+- **Trading / betting**: at what signal-strength value does a pick's hit
+  rate become reliable (the original use case this was built for)
+
+---
+
+## What you need
+
+You only need:
+
+- One or more **numeric columns** to evaluate.
+- One **binary outcome column** indicating whether each observation was a
+  success or not.
+
+The outcome column may contain `0`/`1`, `True`/`False`, `0.0`/`1.0`, or any
+mixture of the above:
+
+| Numeric column     | Outcome column                 |
+| ------------------ | ------------------------------ |
+| Credit score        | Defaulted (`True` / `False`)   |
+| Engagement score     | Converted (`1` / `0`)          |
+| Biomarker level     | Improved (`True` / `False`)    |
+| Model confidence     | Correct prediction (`1` / `0`) |
+| Betting signal score | Win (`True` / `False`)         |
+| Risk score           | Fraud (`1` / `0`)              |
+
+`edgepoint` searches each numeric column for the point above which the
+outcome rate improves while still retaining a meaningful share of the
+population.
+
+---
+
+## Install
+
+```bash
+pip install edgepoint
+```
+
+```python
+from edgepoint import find
+```
+
+---
+
+## Quick start
+
+```python
+import pandas as pd
+from edgepoint import find
+
+df = pd.DataFrame({
+    "score": [
+         5,  8, 11, 14, 17, 20, 23, 26,
+        29, 32, 35, 38, 41, 44, 47, 50,
+        53, 56, 59, 62, 65, 68, 71, 74,
+        77, 80, 83, 86
+    ],
+    "hit": [
+        0, 0, 1, 0, 1, 1, 0, 1,
+        1, 0, 1, 1, 0, 1, 1, 1,
+        1, 0, 1, 1, 1, 1, 1, 1,
+        0, 1, 1, 1
+    ]
+})
+
+result = find(
+    df,
+    outcome_col="hit",
+    compute_fallback=True,
+    show_progress=True,
+)
+
+print(result)
+```
+
+```
+============================================================
+  edgepoint.find | outcome_col='hit'  columns=['score']
+  range_bins=15  gap_threshold=10%  target_pct=60%  min_coverage_pct=30%  fallback_tolerance_pct=3%  primary_tiebreak='gap'  compute_fallback=True
+============================================================
+
+    [score] n=28  range=[5 .. 86]  edges=14
+      checking every edge (min_coverage_pct=30% floor):
+        edge=10.4   >= 10.4: n=26    rate=76.9%   < 10.4: n=2     rate=0.0%   gap=+76.9%  coverage=93%
+        edge=15.8   >= 15.8: n=24    rate=79.2%   < 15.8: n=4     rate=25.0%   gap=+54.2%  coverage=86%
+        edge=21.2   >= 21.2: n=22    rate=77.3%   < 21.2: n=6     rate=50.0%   gap=+27.3%  coverage=79%
+        edge=26.6   >= 26.6: n=20    rate=80.0%   < 26.6: n=8     rate=50.0%   gap=+30.0%  coverage=71%
+        edge=32     >= 32:   n=19    rate=78.9%   < 32:   n=9     rate=55.6%   gap=+23.4%  coverage=68%
+        edge=37.4   >= 37.4: n=17    rate=82.4%   < 37.4: n=11    rate=54.5%   gap=+27.8%  coverage=61%
+        edge=42.8   >= 42.8: n=15    rate=86.7%   < 42.8: n=13    rate=53.8%   gap=+32.8%  coverage=54%
+        edge=48.2   >= 48.2: n=13    rate=84.6%   < 48.2: n=15    rate=60.0%   gap=+24.6%  coverage=46%
+        edge=53.6   >= 53.6: n=11    rate=81.8%   < 53.6: n=17    rate=64.7%   gap=+17.1%  coverage=39%
+        edge=59     >= 59:   n=10    rate=90.0%   < 59:   n=18    rate=61.1%   gap=+28.9%  coverage=36%
+        edge=64.4   (coverage 29% < min_coverage_pct=30%) -> skipped
+        edge=69.8   (coverage 21% < min_coverage_pct=30%) -> skipped
+        edge=75.2   (coverage 14% < min_coverage_pct=30%) -> skipped
+        edge=80.6   (coverage 7% < min_coverage_pct=30%) -> skipped
+      -> PRIMARY: split at 10.4, gap=76.9%, above_rate=76.9%, coverage=93% (>= gap_threshold=10% AND target_pct=60%; tiebreak=gap)
+```
+
+Output:
+
+```python
+{
+    "score": 10.4
+}
+```
+
+Meaning: scores of **10.4 and above** produce a noticeably higher hit rate
+(76.9%) than scores below 10.4 (0.0%), while still covering 93% of the
+population, well clear of every quality bar.
+
+---
+
+## Using the result correctly
+
+The value returned by `find()` is **not** intended to become a permanent
+threshold. It is simply the best candidate based on the data available at
+the time the function was called.
+
+As more observations arrive, the best threshold may shift, strengthen,
+weaken, or disappear entirely. A threshold that looked convincing today
+may no longer be appropriate once more data has accumulated. This is
+intentional.
+
+`edgepoint` answers exactly one question:
+
+> **"Given the data I have right now, where is the best candidate threshold?"**
+
+It deliberately does **not** answer:
+
+> **"How long should I trust this threshold?"**
+
+That responsibility belongs to the system using this package. A typical
+production workflow:
+
+- recompute thresholds periodically, not once
+- check more frequently while data is limited
+- let tolerance relax as more evidence accumulates
+- monitor performance over time
+- automatically demote or remove thresholds that stop performing
+
+Think of `find()` as proposing a threshold, not certifying one forever.
+
+---
+
+## Multiple columns
+
+By default, every numeric column except the outcome column is scanned.
+
+```python
+result = find(
+    df,
+    outcome_col="converted",
+    compute_fallback=False,
+)
+```
+
+```python
+{
+    "age": None,
+    "income": 42000.0,
+    "engagement_score": 67.14,
+    "rating": 4.10
+}
+```
+
+Each column is evaluated independently.
+
+---
+
+## Scanning selected columns
+
+```python
+result = find(
+    df,
+    outcome_col="converted",
+    columns=["score", "income", "age"],
+    compute_fallback=True,
+)
+```
+
+Pass the full DataFrame and use `columns` as a whitelist, no need to
+pre-slice the data yourself.
+
+---
+
+## Custom parameters
+
+```python
+result = find(
+    df,
+    outcome_col="converted",
+    compute_fallback=True,
+    gap_threshold=15,
+    target_pct=70,
+    min_coverage_pct=35,
+    range_bins=20,
+    primary_tiebreak="gap",
+    show_progress=True,
+)
+```
+
+---
+
+## Parameters
+
+| Parameter                | Required | Description                                        |
+| ------------------------ | -------- | --------------------------------------------------- |
+| `outcome_col`             | Yes      | Binary outcome column                                |
+| `compute_fallback`        | Yes      | Whether weaker fallback thresholds are allowed       |
+| `columns`                  | No       | Columns to scan. Defaults to every numeric column    |
+| `gap_threshold`            | No       | Minimum improvement required, in percentage points   |
+| `target_pct`               | No       | Minimum success rate required, in %                  |
+| `min_coverage_pct`         | No       | Minimum percentage of rows above the threshold       |
+| `range_bins`               | No       | Number of equal-width candidate edges                |
+| `fallback_tolerance_pct`   | No       | Near-tie tolerance, in percentage points              |
+| `primary_tiebreak`         | No       | `"gap"` or `"rate"`                                  |
+| `min_rows`                 | No       | Minimum rows required before scanning a column        |
+| `show_progress`            | No       | Print every candidate edge while scanning            |
+
+See `edgepoint/core.py` for the complete parameter reference and defaults.
+
+---
+
+## Returns
+
+`find()` returns a dictionary whose keys are column names and whose values
+are the detected thresholds:
+
+```python
+{
+    "score": 63.8,
+    "income": 42000,
+    "age": None
+}
+```
+
+A value of `None` means no threshold satisfied the requested criteria.
+This is a legitimate, reportable result, not a gap to be patched over.
+
+---
+
+## Supported outcome values
+
+The outcome column may contain:
+
+- `0` / `1`
+- `True` / `False`
+- `0.0` / `1.0`
+- any mixture of the above
+
+Any other value (strings, `2`, `-1`, etc.) raises a `ValueError` before
+any column is scanned, a full stop, not a per-column skip. One bad value
+hiding anywhere in the outcome column, even among hundreds of otherwise
+clean rows, halts the entire call.
+
+---
+
+## Inspecting a decision
+
+```python
+find(
+    df,
+    outcome_col="hit",
+    compute_fallback=True,
+    show_progress=True,
+)
+```
+
+`show_progress=True` prints every candidate threshold as it is evaluated,
+including coverage, outcome rates above and below the threshold,
+improvement (gap), rejected candidates and why, and whether the primary or
+fallback tier produced the final result. Useful for tuning parameters or
+validating thresholds on new datasets.
+
+---
+
+## How it works
+
+For every numeric column:
+
+1. Determine the column's minimum and maximum values.
+2. Divide that range into equal-width candidate edges.
+3. Evaluate every candidate threshold: outcome rate above, outcome rate
+   below, improvement (gap), and coverage.
+4. Reject candidates that fail the coverage floor.
+5. Among the rest, select the best remaining threshold using a two-tier,
+   coverage-preferring tiebreak.
+6. Return `None` if no convincing threshold exists.
+
+The algorithm is deterministic: the same data with the same parameters
+always produces the same result.
+
+---
+
+## Design journal
+
+This section exists because most packages hide the *why* and only ship
+the *what*. Every decision below was actually argued out before it was
+built, including the ones that almost went a different way.
+
+**Why not just use isotonic regression or a decision-tree split?**
+Both exist and both are more "textbook optimal" in a narrow sense.
+Decision trees optimize prediction; they don't automatically enforce
+minimum coverage, minimum success rate, minimum improvement, or stable
+tiebreaking among near-ties, those are left to whoever builds the model.
+Isotonic regression estimates a monotonic probability curve, but doesn't
+directly answer "where should the operational threshold sit," you still
+have to decide where "good enough" begins. Neither method has a coverage
+guard by default, so both will happily hand you a "great" split sitting
+on 8 rows. If you're fluent enough in ML to reach for `optbinning` or
+`sklearn`, you don't strictly need this package to solve the raw math.
+What you get here instead is the guard logic and the fallback decision
+made explicit, visible, and enforced, not bolted on after the fact.
+
+**Why equal-width bins instead of quantile bins?**
+Quantile (`qcut`) edges are population-based, they guarantee similar row
+count per step, not similar value range. On a column with a lot of
+duplicate or clustered values, quantile edges collapse toward the crowded
+region, and a real effect sitting right at that cluster gets buried inside
+one wide edge alongside completely different values. Equal-width edges
+are spaced evenly across the actual range, so a cluster still gets a
+nearby edge to split on.
+
+**Why coverage instead of range-position as the guard?**
+The first version of this logic used a range-position cutoff (a max
+percentile of the range) to avoid thin slivers. That turned out to be
+only a *proxy* for the real thing being protected against, on a skewed
+column, range-position and actual row coverage decouple. An edge sitting
+at 67% of the way across the range can still cover only 4% of rows, while
+an edge at 20% across can cover 91%. Checking coverage directly, against
+real row counts, is the more honest guard.
+
+**Why is `compute_fallback` mandatory, with no default?**
+Because whether a column should ever settle for a "best available, but
+weaker" split instead of reporting `None` is a modeling decision, not
+something that should silently default one way forever. Omitting it
+raises a `ValueError` on purpose. You have to consciously choose `True`
+or `False` every time.
+
+**Should this punish a range with many rows and a bad rate, and not
+over-trust a range with few rows and a good rate, automatically, like a
+promotion system?**
+This came up directly: the instinct was "a new signal showing promise
+should get gradually promoted, not fully trusted on day one, the way a
+new hire earns trust over time." The honest answer: yes, that's a real
+mechanism (formally, a Wilson-lower-bound-style confidence penalty that
+scales with row count), but it does **not** belong inside this function.
+This function's job is to propose a candidate spot on the data it's given
+right now, a single, static, one-shot check. The gradual-trust mechanism
+belongs in whatever *live* system calls this repeatedly over time: check
+sooner when data is thin, widen tolerance as more data accumulates, and
+let a live feedback loop auto-correct a promoted spot that stops
+performing. That reasons about performance as data keeps arriving, not
+just at one static moment, which is more information than any confidence
+interval computed once could ever give you. So: the coverage floor stays
+a hard gate here, and the graduated-trust logic stays out of this
+package, on purpose, it's where your own orchestration layer earns its
+keep, and it's arguably the more proprietary part worth keeping close
+anyway.
+
+**Does it only find a "good" zone, or does it independently verify the
+"bad" zone too?**
+One-directional, by design. This function only ever asks "is there a
+point above which the rate is *better* than below it?" It does not
+independently score the below-side against its own bar, it only knows
+that "below" is worse than "above," which is a comparative statement, not
+two independently-verified zones. In practice those usually amount to the
+same thing, but it's worth being precise about what's actually being
+claimed.
+
+**Is this reinventing the wheel?**
+Partly, and that's fine to say plainly. The underlying math (walk a
+range, find a threshold, compare two groups) isn't novel. What isn't
+already sitting in a well-known library is the specific combination of an
+explicit coverage floor, a forced fallback decision, a tolerance-based
+tiebreak that consistently prefers coverage over noise, and full per-edge
+transparency via `show_progress`, every rejected edge and *why* it was
+rejected, not just the final answer. That combination is what makes it
+something you can actually audit, which matters more than raw statistical
+optimality in a system where a human has to trust and act on the output.
+
+---
+
+## Design decisions, summarized
+
+- **Equal-width candidate edges** avoid dense regions dominating the
+  search.
+- **Coverage guard** measured directly with row counts, not percentile
+  position, so tiny high-performing groups are never over-trusted.
+- **Mandatory fallback decision**, `compute_fallback` has no default,
+  because whether weaker thresholds are acceptable is a modeling call
+  you must make explicitly every time.
+- **Honest `None`**, when no convincing threshold exists, that's reported
+  as a legitimate outcome, not forced into a weak recommendation.
+- **Coverage-first tiebreaking**, among near-identical candidates, the
+  broader-coverage threshold wins.
+- **One-directional search**, asks only "above what value does the
+  outcome become better," and does not independently validate the
+  below-threshold region as its own zone.
+
+---
+
+## Who this is for
+
+Not primarily ML researchers with `optbinning` already in their toolbox,
+they don't need this to solve the raw math. This is for people closer to
+how it was actually built: solo builders, indie quants, and analysts who
+would rather read and trust 100 lines they can fully audit than hand a
+threshold decision to a library's internals. If a chart in a notebook is
+your normal workflow, this is the same idea, minus the human staring at
+the chart, a `df` in, a structured answer out, ready to be called from
+inside a live system, not just eyeballed once and forgotten.
+
+---
+
+## FAQ
+
+**Does this replace machine learning?**
+No. Machine learning predicts outcomes; `edgepoint` proposes interpretable
+operational thresholds. Different problem.
+
+**Is this statistically optimal?**
+Not necessarily, and not the goal. It intentionally prioritizes
+interpretability and operational usefulness over optimizing a pure
+statistical objective.
+
+**Why can the function return `None`?**
+Because not every variable contains a convincing threshold. Returning
+`None` is more honest than forcing a weak recommendation.
+
+**Should I hard-code the threshold?**
+No. Treat it as a snapshot of your current data and recompute as new
+observations arrive. See "Using the result correctly" above.
+
+---
+
+## Naming note
+
+This package went through a few naming iterations before landing here,
+early candidates included `optimal_start`, `sweet_spot`, `sweetspot`, and
+`maxspot`, each rejected either for not capturing the actual idea (a
+zone/point where rate improves without sacrificing population) or for
+colliding with an existing PyPI package. `edgepoint` was checked and
+confirmed clear, and both the import and the PyPI distribution name now
+match, so there's no split between what you `pip install` and what you
+`import`.
+
+---
+
+## License
+
+MIT