edgepoint 2.0.2__tar.gz → 2.0.3__tar.gz

{edgepoint-2.0.2/edgepoint.egg-info → edgepoint-2.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: edgepoint
-Version: 2.0.2
+Version: 2.0.3
 Summary: Find the point in a numeric column above which a binary outcome becomes meaningfully and reliably better.
 Author: Henry
 License: MIT
@@ -38,11 +38,13 @@ outcome, it answers a practical question, twice:
 > becoming good enough while keeping the best coverage possible, and
 > does that still hold on unseen data?"**
 
-Rather than fitting a predictive model, `edgepoint` splits your data into
-train and test, searches train for the best threshold(s), then replays those
-exact thresholds against test with no re-optimization. What you get back is
-not just "the best split we could find" but "the best split we could find,
-and here's how it actually performed on data it never touched."
+`edgepoint` makes a simple, less-savvy-visible property of your data easy
+to see: the exact point along a metric where an outcome starts spiking.
+`edgepoint` splits your data into train and test, searches train for the
+best threshold(s), then replays those exact thresholds against test with
+no re-optimization. What you get back is not just "the best split we could
+find" but "the best split we could find, and here's how it actually
+performed on data it never touched."
 
 ```python
 from edgepoint import search
@@ -60,6 +62,52 @@ below.
 
 ---
 
+## `outcome_col`: telling edgepoint what "good" means
+
+Before `search()` scans a single edge, it needs one thing from you that
+matters more than any parameter: `outcome_col`. This is you, the analyst,
+labeling every row in your data as a win or a loss, a pass or a fail, a
+positive or a negative. `edgepoint` doesn't decide what "success" looks
+like in your business, it has no idea what a good sale, a good patient
+outcome, or a good bet even is. You decide that, once, by pointing at a
+column, and every other number the library produces is downstream of that
+one judgment.
+
+Concretely: `outcome_col` must be a column of `1`/`0`, `True`/`False`, or
+a mix of both, one value per row, `1` (or `True`) meaning "this row counts
+as a success" and `0` (or `False`) meaning "this row doesn't." That's it,
+no other values are allowed, `edgepoint` raises a `ValueError` before doing
+any work if it finds anything else in that column, rather than silently
+guessing which values you meant as the "good" ones.
+
+Once that column exists, everything else in `search()` is really just
+counting, over and over, at every candidate edge in every numeric column:
+*"of the rows at or above this point, what fraction were a `1`?"* That
+fraction is `hit_rate`. The rest, `miss_rate`, `gap`, `coverage`, `score`,
+are all built directly on top of that one count. Get `outcome_col` wrong,
+too loose, too strict, mislabeled, or measuring the wrong thing entirely,
+and every threshold `search()` proposes will be confidently optimized for
+the wrong target. Get it right, and the rest of the pipeline (percentile
+edges, train/test replay, combo search) is just honest, mechanical counting
+against a target you already trust.
+
+A few practical notes on choosing it:
+
+- **It has to already exist as a column.** If "success" in your data is a
+  derived condition, e.g. "sale closed within 7 days" or "score improved by
+  at least 10 points", compute that as its own `0`/`1` column *before*
+  calling `search()`. `edgepoint` labels nothing on its own.
+- **One outcome per run.** If you care about two different definitions of
+  success (say, "converted" and "converted *and* retained"), that's two
+  separate calls to `search()` with two different `outcome_col`s, not one
+  call trying to do both.
+- **Rare outcomes still need rows on both sides.** If almost every row is a
+  `1` (or almost every row is a `0`), there's very little contrast for
+  `edgepoint` to find an edge across, and columns are likely to get skipped
+  for failing `min_coverage` on whichever side is thin.
+
+---
+
 ## Where this applies
 
 Any continuous metric (or several) + binary outcome pair, for example:
@@ -77,15 +125,9 @@ Any continuous metric (or several) + binary outcome pair, for example:
 
 ## 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. Any other value (strings, `2`, `-1`, etc.) raises a
-`ValueError` up front, before anything runs.
+You only need two things: one or more **numeric columns** to evaluate, and
+the **`outcome_col`** described above, your `0`/`1` (or `True`/`False`)
+judgment of what counts as a win on each row. A few example pairings:
 
 | Numeric column       | Outcome column                 |
 | --------------------- | ------------------------------- |
@@ -503,22 +545,64 @@ independently verified zones.
 
 ---
 
+## A good alternative choice, at any data size
+
+This isn't tied to a data size at all, it scales from a few dozen rows up
+to millions the same way: scan every candidate point, count what's above
+and below it, replay the winner on held-out data. The core idea holds no
+matter how much data feeds it.
+
+**The core idea: make the spike visible.** Most datasets have some point
+along a metric where the outcome rate stops being flat and starts climbing,
+but that point is easy to miss just eyeballing a column. `edgepoint` scans
+every candidate point along every numeric column and surfaces exactly
+where that climb happens, `edge_point`, `hit_rate`, `gap`, `coverage`, in a
+plain table. No hidden weights, no coefficients to decode, just "here's
+the row count on each side of this line, and here's how much better things
+get above it."
+
+**Built to keep re-checking rather than lock in.** Data keeps arriving,
+and a good threshold today can shift as more of it comes in. Rather than
+fitting one answer and treating it as settled, `search()` is meant to be
+re-run as new rows accumulate, each run rechecks the spike against a
+fresh train/test split and tells you plainly if it moved, held, or
+disappeared. See "Using the result correctly" above, that habit of
+recomputing is what keeps the picture honest over time, regardless of
+how many rows are behind it.
+
+**Worth knowing on any dataset.** A good-looking gap can sometimes be a
+handful of rows doing all the work rather than a real, reliable spike,
+this shows up more easily on a smaller slice of data, but the same logic
+applies at any scale. `edgepoint` leans against this two ways:
+`min_coverage` refuses to let a threshold win on too few rows in the
+first place, and the built-in shrinkage discount (see Design notes)
+discounts small-sample gaps before they're allowed to win. Still worth a
+glance at the `n` column yourself, if a combo's win is resting on very
+few rows relative to the rest of your data, that's exactly the kind of
+thing the recompute habit above is there to confirm or correct as more
+data comes in.
+
+---
+
 ## Who this is for
 
-Not primarily ML researchers with an established modeling toolbox already
-in hand, 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 code they can fully audit than
-hand a threshold decision to a library's internals, and who want a basic
-train/test sanity check built in rather than bolted on separately.
+Solo builders, indie quants, and analysts who want to see exactly where a
+metric's outcome rate spikes, in a table they can read and trust at a
+glance, without needing a modeling toolbox to get there. This is for people
+closer to how it was actually built: readers who'd rather audit code they
+fully understand than hand a threshold decision to a library's internals,
+and who want a basic train/test sanity check built in rather than bolted
+on separately.
 
 ---
 
 ## FAQ
 
-**Does this replace machine learning?**
-No. Machine learning predicts outcomes; `edgepoint` proposes interpretable
-operational thresholds and checks them against held-out data.
+**What does edgepoint actually give me?**
+A plain, readable table of exactly where an outcome starts spiking along
+a metric, plus proof that the spike held up on data it hadn't seen. No
+coefficients or hidden weights to decode, just an edge point, a hit rate,
+and a coverage number.
 
 **Is this statistically optimal?**
 Not necessarily, and not the goal. It prioritizes interpretability and