edgepoint 2.0.1__tar.gz → 2.0.3__tar.gz

{edgepoint-2.0.1 → edgepoint-2.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: edgepoint
-Version: 2.0.1
+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                 |
 | --------------------- | ------------------------------- |
@@ -147,7 +189,6 @@ df = pd.DataFrame({
 })
 ```
 
-
 ### Running it
 
 ```python
@@ -156,15 +197,19 @@ from edgepoint import search
 train_results_df, test_results_df, top_combos = search(
     df,
     outcome_col="hit",
-    mode="quick",
+    train_split=60,      # 24 train / 16 test → both ≥ min_rows
+    min_rows=15,
     min_coverage=20,
+    mode="quick",
     top_combos_n=2,
-    show_progress=True,
+    show_progress=False,
 )
 ```
 
-Running that prints a five-stage progress log (suppress it with
-`show_progress=False`):
+With `show_progress=False` the call above runs silently and just returns
+the three values. Turning `show_progress=True` on the exact same call
+prints the full five-stage log so you can see how the split, the
+single-column search, and the combo search actually got there:
 
 ```
 EDGEPOINT.
@@ -173,101 +218,117 @@ EDGEPOINT.
     🟡  STANDARD  >  3 mins
     🔴  DEEP      > 10 mins
 
- start : 2026-07-16 22:28:05.
+ start : 2026-07-17 07:10:14.
 
 [1/5] Train / Test Split
 --------------------------------
 
-train n=140. test n=60. total n=200.
+Sample Size (n) - Full = 40   . Train = 24   . Test = 16   .
+
+Hit Rate    (%) - Full = 47.50. Train = 50.00. Test = 43.75.
 
- done in 0mins 0 secs | elapsed 0mins 1 secs | 22:28:06.
+ done in 0mins 0 secs | elapsed 0mins 1 secs | 07:10:15.
 
 
-[2/5] Single-Column Search (train, n=140)
+[2/5] Single-Column Search (train, n=24)
 --------------------------------
 
-  column edge_point hit_rate miss_rate     gap    n coverage
-0  score      65.67    92.11      7.89   84.21   38    27.14
-1    age      18.00    43.57     56.43  -12.86  140   100.00
+  column edge_point hit_rate miss_rate    gap   n coverage
+0  score      49.46    75.00     25.00  50.00  16    66.67
+1    age      39.50    57.14     42.86  14.29  14    58.33
 
- done in 0mins 0 secs | elapsed 0mins 1 secs | 22:28:06.
+ done in 0mins 0 secs | elapsed 0mins 1 secs | 07:10:16.
 
 
-[3/5] Single-Column Evaluation (test, n=60)
+[3/5] Single-Column Evaluation (test, n=16)
 --------------------------------
 
-  column edge_point hit_rate miss_rate     gap   n coverage
-0  score      65.67    80.00     20.00   60.00  20    33.33
-1    age      18.00    41.67     58.33  -16.67  60   100.00
+  column edge_point hit_rate miss_rate     gap  n coverage
+0  score      49.46    77.78     22.22   55.56  9    56.25
+1    age      39.50    42.86     57.14  -14.29  7    43.75
 
- done in 0mins 0 secs | elapsed 0mins 2 secs | 22:28:07.
+ done in 0mins 0 secs | elapsed 0mins 2 secs | 07:10:16.
 
 
 [4/5] Combo Generation & Evaluation (train, mode='quick') ..This may take a while.
 --------------------------------
 
- 2 combo(s) qualified (train).
+ 3 combo(s) qualified (train). sample size (n) = 24. hit rate (%) = 50.00.
 
    combo_num       combo hit_rate miss_rate    gap   n coverage
-0          1       score    92.11      7.89  84.21  38    27.14
-1          3  score, age    92.11      7.89  84.21  38    27.14
+0          3  score, age    80.00     20.00  60.00  10    41.67
+1          1       score    75.00     25.00  50.00  16    66.67
+2          2         age    57.14     42.86  14.29  14    58.33
 
- done in 0mins 0 secs | elapsed 0mins 2 secs | 22:28:08.
+ done in 0mins 0 secs | elapsed 0mins 2 secs | 07:10:17.
 
 
 [5/5] Combo Validation (test, mode='quick')
 --------------------------------
 
- 2 combo(s) qualified (test).
+ 3 combo(s) qualified (test). sample size (n) = 16. hit rate (%) = 43.75.
 
-   combo_num       combo hit_rate coverage   n train_hit_rate train_coverage  score
-0          1       score    80.00    33.33  20          92.11          27.14    1.0
-1          3  score, age    80.00    33.33  20          92.11          27.14    1.0
+   combo_num       combo hit_rate coverage  n train_hit_rate train_coverage  score
+0          3  score, age    60.00    31.25  5          80.00          41.67  21.49
+1          1       score    77.78    56.25  9          75.00          66.67   1.00
+2          2         age    42.86    43.75  7          57.14          58.33 -29.50
 
- done in 0mins 0 secs | elapsed 0mins 3 secs | 22:28:08.
+ done in 0mins 0 secs | elapsed 0mins 3 secs | 07:10:17.
 
 
 TOP 2 COMBOS (test)
 --------------------------------
-                   : combo #1         combo #3
- score             : 65.67            65.67
- age               : -                18.0
+
+Sample Size (n) - Full = 40   . Train = 24   . Test = 16   .
+Hit Rate    (%) - Full = 47.50. Train = 50.00. Test = 43.75.
+
+                             : combo #3         combo #1
+ Score                       : 49.46            49.46
+ Age                         : 39.5             -
  ......................................................
- hit_rate          : 80.0             80.0
- coverage          : 33.33            33.33
- train_hit_rate    : 92.11            92.11
- train_coverage    : 27.14            27.14
- combo_sample_size : 20               20
- test_sample_size  : 60               60
-
-COMPLETE  -  total duration 0mins 4 secs  (end 22:28:09).
+ Hit_rate                    : 60.0             77.78
+ Coverage                    : 31.25            56.25
+ Train_hit_rate              : 80.0             75.0
+ Train_coverage              : 41.67            66.67
+ Combo_sample_size           : 5                9
+ Test_sample_size            : 16               16
+ Baseline_hit_rate (full df) : 47.50            47.50
+ Vs_baseline                 : 12.50 +          30.28 +
+
+COMPLETE  -  total duration 0mins 4 secs  (end 07:10:18).
 ```
 
 And the three values `search()` returns:
 
 ```python
 >>> train_results_df
-  column edge_point hit_rate miss_rate     gap    n coverage
-0  score      65.67    92.11      7.89   84.21   38    27.14
-1    age      18.00    43.57     56.43  -12.86  140   100.00
+  column edge_point hit_rate miss_rate    gap   n coverage
+0  score      49.46    75.00     25.00  50.00  16    66.67
+1    age      39.50    57.14     42.86  14.29  14    58.33
 
 >>> test_results_df
-  column edge_point hit_rate miss_rate     gap   n coverage
-0  score      65.67    80.00     20.00   60.00  20    33.33
-1    age      18.00    41.67     58.33  -16.67  60   100.00
+  column edge_point hit_rate miss_rate     gap  n coverage
+0  score      49.46    77.78     22.22   55.56  9    56.25
+1    age      39.50    42.86     57.14  -14.29  7    43.75
 
 >>> top_combos
-[{'combo_num': 1, 'edges': {'score': 65.67}, 'hit_rate': 80.0, 'coverage': 33.33,
-  'train_hit_rate': 92.11, 'train_coverage': 27.14, 'combo_sample_size': 20, 'test_sample_size': 60},
- {'combo_num': 3, 'edges': {'score': 65.67, 'age': 18.0}, 'hit_rate': 80.0, 'coverage': 33.33,
-  'train_hit_rate': 92.11, 'train_coverage': 27.14, 'combo_sample_size': 20, 'test_sample_size': 60}]
+[{'combo_num': 3, 'edges': {'score': 49.46, 'age': 39.5}, 'hit_rate': 60.0, 'coverage': 31.25,
+  'train_hit_rate': 80.0, 'train_coverage': 41.67, 'combo_sample_size': 5, 'test_sample_size': 16,
+  'baseline_hit_rate': 47.5, 'vs_baseline': 12.5},
+ {'combo_num': 1, 'edges': {'score': 49.46}, 'hit_rate': 77.78, 'coverage': 56.25,
+  'train_hit_rate': 75.0, 'train_coverage': 66.67, 'combo_sample_size': 9, 'test_sample_size': 16,
+  'baseline_hit_rate': 47.5, 'vs_baseline': 30.28}]
 ```
 
-Reading this: `score`'s threshold of 65.67 looked strong on train (92.11%
-hit rate over 27.14% of rows) and, replayed unchanged against test, held up
-at 80.00% over 33.33% of rows, a real but expected drop, not a collapse.
-Adding `age` to the combo changed nothing here (its own threshold barely
-qualified on train), which is itself a useful, honest result.
+Reading this: `score`'s threshold of 49.46 looked solid on train (75.00%
+hit rate over 66.67% of rows) and, replayed unchanged against test, held up
+even better at 77.78% over 56.25% of rows, comfortably ahead of the 47.5%
+baseline hit rate. Adding `age` into the combo (`score >= 49.46 AND age >=
+39.5`) tightens things further on train (80.00% hit rate) but shrinks
+coverage a lot (down to 5 rows on test), and its test hit rate of 60.00%,
+while still above baseline, is the less reliable of the two picks precisely
+because it's resting on so few rows, exactly the kind of honest trade-off
+`search()` is built to surface rather than hide.
 
 ---
 
@@ -384,14 +445,16 @@ list of up to `top_combos_n` dicts otherwise. Each dict:
 
 ```python
 {
-    "combo_num": 1,
-    "edges": {"score": 65.67},          # {column: edge_point} used by this combo
-    "hit_rate": 80.0,                   # test-side
-    "coverage": 33.33,                  # test-side
-    "train_hit_rate": 92.11,            # carried over from train, unchanged
-    "train_coverage": 27.14,            # carried over from train, unchanged
-    "combo_sample_size": 20,            # rows clearing the combo on test
-    "test_sample_size": 60,             # total test rows
+    "combo_num": 3,
+    "edges": {"score": 49.46, "age": 39.5},  # {column: edge_point} used by this combo
+    "hit_rate": 60.0,                        # test-side
+    "coverage": 31.25,                       # test-side
+    "train_hit_rate": 80.0,                  # carried over from train, unchanged
+    "train_coverage": 41.67,                 # carried over from train, unchanged
+    "combo_sample_size": 5,                  # rows clearing the combo on test
+    "test_sample_size": 16,                  # total test rows
+    "baseline_hit_rate": 47.5,               # "do nothing" hit rate on the full df
+    "vs_baseline": 12.5,                     # test hit_rate - baseline_hit_rate, in points
 }
 ```
 
@@ -482,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