edgepoint 2.0.0__tar.gz → 2.0.2__tar.gz

{edgepoint-2.0.0 → edgepoint-2.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: edgepoint
-Version: 2.0.0
+Version: 2.0.2
 Summary: Find the point in a numeric column above which a binary outcome becomes meaningfully and reliably better.
 Author: Henry
 License: MIT
@@ -147,7 +147,6 @@ df = pd.DataFrame({
 })
 ```
 
-
 ### Running it
 
 ```python
@@ -156,15 +155,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 +176,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   .
 
- done in 0mins 0 secs | elapsed 0mins 1 secs | 22:28:06.
+Hit Rate    (%) - Full = 47.50. Train = 50.00. Test = 43.75.
 
+ 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 +403,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
 }
 ```
 

{edgepoint-2.0.0 → edgepoint-2.0.2}/README.md

@@ -119,7 +119,6 @@ df = pd.DataFrame({
 })
 ```
 
-
 ### Running it
 
 ```python
@@ -128,15 +127,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.
@@ -145,101 +148,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   .
 
- done in 0mins 0 secs | elapsed 0mins 1 secs | 22:28:06.
+Hit Rate    (%) - Full = 47.50. Train = 50.00. Test = 43.75.
 
+ 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.
 
 ---
 
@@ -356,14 +375,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
 }
 ```