edgepoint 3.0.0__tar.gz → 3.0.2__tar.gz

{edgepoint-3.0.0 → edgepoint-3.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: edgepoint
-Version: 3.0.0
+Version: 3.0.2
 Summary: Find the point in a numeric column above which a binary outcome becomes meaningfully and reliably better.
 Author: Henry
 License: MIT

{edgepoint-3.0.0 → edgepoint-3.0.2}/edgepoint/main.py

@@ -17,14 +17,6 @@ def _print_table(display_df):
         print(display_df)
 
 
-# Display metadata for the 3 combo-search modes - same dots/labels/hints
-# the old script's banner used, so the mode indicator here matches.
-_MODE_INFO = {
-    "quick":    {"dot": "\U0001F7E2", "label": "QUICK",    "hint": "<  3 mins"},
-    "standard": {"dot": "\U0001F7E1", "label": "STANDARD", "hint": ">  3 mins"},
-    "deep":     {"dot": "\U0001F534", "label": "DEEP",     "hint": "> 10 mins"},
-}
-
 STAGE_PAUSE_SECONDS = 0.6  # cosmetic pause between stages, same as old script
 TOTAL_STAGES = 6
 
@@ -43,16 +35,11 @@ def _format_duration(seconds):
     return f"{mins}mins {secs} secs"
 
 
-def _banner(mode):
-    # Printed once, before any stage - app title + active mode only.
-    # No timestamp here - that's added after the dataset summary instead,
-    # same as the other stages get their own timestamp.
-    print(_bold("EDGEPOINT."))
+def _banner():
+    # Printed once, before any stage - app title + begin timestamp on
+    # one line, followed by the divider.
+    print(_bold(f"\nEDGEPOINT. \U0001F552 Begin : {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}."))
     print("-" * 32)
-    for key, info in _MODE_INFO.items():
-        marker = "->" if key == mode else "  "
-        print(f" {marker} {info['dot']}  {info['label']:<9} {info['hint']:<8}"
-              f"{'  (active)' if key == mode else ''}")
     time.sleep(STAGE_PAUSE_SECONDS)
 
 
@@ -173,12 +160,16 @@ def _print_legend(legend):
         print(f"  {abbr:<{abbr_width}}  =  {full}")
 
 
-def _print_top_combos(merged_combos_df, top_combo_n=3):
+def _print_top_combos(merged_combos_df, baseline_full, top_combo_n=3):
     """
     Prints the top `top_combo_n` combos (already sorted by final_score)
     side by side as columns - one column per combo, edges and stats as
-    rows. Pure content only - the banner and stage timing live in
-    search(), same as train_and_combo_gen/test_and_combo_val are
+    rows. Also appends a Baseline row (the dataset's overall "do
+    nothing" hit rate) and a vs Baseline row (the worse of that combo's
+    train/test hit_rate minus baseline, signed +/-) so it's obvious at
+    a glance whether a combo actually beats doing nothing even in its
+    weaker split. Pure content only - the banner and stage timing live
+    in search(), same as train_and_combo_gen/test_and_combo_val are
     the actual stages, not this print function.
     """
     top_df = merged_combos_df.head(top_combo_n)
@@ -206,8 +197,10 @@ def _print_top_combos(merged_combos_df, top_combo_n=3):
     ]
     stat_fields = [(k, l) for k, l in stat_fields if k in top_df.columns]
 
+    extra_labels = ["Baseline", "vs Baseline"]
     label_width = max(
-        [len(c) for c in edge_cols] + [len(l) for _, l in stat_fields] + [5]
+        [len(c) for c in edge_cols] + [len(l) for _, l in stat_fields]
+        + [len(l) for l in extra_labels] + [5]
     )
     col_width = max(14, label_width)
 
@@ -234,6 +227,23 @@ def _print_top_combos(merged_combos_df, top_combo_n=3):
         values = [row[key] for row in rows]
         print(fmt_row(label, values))
 
+    if baseline_full is not None:
+        baseline_values = [f"{baseline_full:.2f}" for _ in rows]
+        print(fmt_row("Baseline", baseline_values))
+
+        vs_baseline_values = []
+        for row in rows:
+            raw_candidates = [row.get("hit_rate_tr"), row.get("hit_rate_te")]
+            candidates = [float(v) for v in raw_candidates if v is not None]
+            if candidates:
+                worst = min(candidates)
+                diff = worst - baseline_full
+                sign = "+" if diff >= 0 else "-"
+                vs_baseline_values.append(f"{abs(diff):.2f} {sign}")
+            else:
+                vs_baseline_values.append("n/a")
+        print(fmt_row("vs Baseline", vs_baseline_values, bold_values=True))
+
 
 def _fmt_pct(v):
     return f"{v:.2f}" if v is not None else "n/a"
@@ -325,7 +335,7 @@ def _add_final_score(merged_df):
     return merged_df
 
 
-def _row_to_combo_dict(row, top_combos_df):
+def _row_to_combo_dict(row, top_combos_df, baseline_full):
     """
     Builds one combo's return-value dict from a merged_combos_df row.
     Mirrors main.py's _row_to_combo_dict: edges are looked up from
@@ -333,17 +343,27 @@ def _row_to_combo_dict(row, top_combos_df):
     main.py looks edges up from its own top_combos_df) by combo_num -
     merged_combos_df itself never carries an 'edges' column, it only
     carries the _tr/_te stat columns produced by the Stage 5 merge.
+    baseline_full/vs_baseline mirror the same fields shown in the
+    printed top-combos summary (Stage 6): vs_baseline is the worse of
+    this combo's train/test hit_rate minus baseline_full, so a caller
+    can tell at a glance whether the weaker split still beats "do
+    nothing" without recomputing it themselves.
     """
     combo_num = row["combo_num"]
     edges_row = top_combos_df[top_combos_df["combo_num"] == combo_num]
     edges = edges_row.iloc[0]["edges"] if not edges_row.empty else {}
 
+    hit_rate_tr = row.get("hit_rate_tr")
+    hit_rate_te = row.get("hit_rate_te")
+    candidates = [float(v) for v in (hit_rate_tr, hit_rate_te) if v is not None]
+    vs_baseline = (min(candidates) - baseline_full) if candidates and baseline_full is not None else None
+
     return {
         "combo_num": int(combo_num),
         "combo": row["combo"],
         "edges": dict(edges),
-        "hit_rate_tr": row.get("hit_rate_tr"),
-        "hit_rate_te": row.get("hit_rate_te"),
+        "hit_rate_tr": hit_rate_tr,
+        "hit_rate_te": hit_rate_te,
         "coverage_tr": row.get("coverage_tr"),
         "coverage_te": row.get("coverage_te"),
         "n_tr": row.get("n_tr"),
@@ -351,6 +371,8 @@ def _row_to_combo_dict(row, top_combos_df):
         "score_tr": row.get("score_tr"),
         "score_te": row.get("score_te"),
         "final_score": row.get("final_score"),
+        "baseline_full": round(baseline_full, 2) if baseline_full is not None else None,
+        "vs_baseline": round(vs_baseline, 2) if vs_baseline is not None else None,
     }
 
 
@@ -368,10 +390,12 @@ def _empty_combo_dict():
         "score_tr": None,
         "score_te": None,
         "final_score": None,
+        "baseline_full": None,
+        "vs_baseline": None,
     }
 
 
-def _build_top_combos(merged_combos_df, top_combos_df, top_combo_n):
+def _build_top_combos(merged_combos_df, top_combos_df, top_combo_n, baseline_full):
     """
     Same shape/behavior as main.py's _build_top_combos: top `top_combo_n`
     rows from merged_combos_df (already sorted by final_score). Returns
@@ -383,27 +407,23 @@ def _build_top_combos(merged_combos_df, top_combos_df, top_combo_n):
         return _empty_combo_dict()
 
     rows = [row for _, row in merged_combos_df.head(top_combo_n).iterrows()]
-    combos = [_row_to_combo_dict(row, top_combos_df) for row in rows]
+    combos = [_row_to_combo_dict(row, top_combos_df, baseline_full) for row in rows]
 
     if top_combo_n == 1:
         return combos[0]
     return combos
 
 
-def search(df, outcome_col="hit", mode="quick", min_coverage=10, show_progress=True, top_combo_n=3):
+def search(df, outcome_col="hit", min_coverage=10, show_progress=True, top_combo_n=3):
     # Validate every param up front - before the banner, split, core.find,
-    # or any other side-effecting work runs. mode is reassigned to the
-    # normalized (stripped/lowercased) string validate_search_params
-    # returns, so every downstream use of `mode` (banner, stage 2, etc.)
-    # sees the exact same cleaned-up spelling.
-    mode = validate_search_params(
-        df, outcome_col, mode, min_coverage, show_progress, top_combo_n,
+    # or any other side-effecting work runs.
+    validate_search_params(
+        df, outcome_col, min_coverage, show_progress, top_combo_n,
     )
 
     run_start = time.time()
     if show_progress:
-        _banner(mode)
-        print(f"\n \U0001F552 Begin : {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}.")
+        _banner()
 
     # ---- Stage 1: Data Sanity / Splitting ---------------------------------
     # Chronological split, no shuffling: oldest rows -> train, newest rows
@@ -438,7 +458,7 @@ def search(df, outcome_col="hit", mode="quick", min_coverage=10, show_progress=T
     if show_progress:
         _stage_header(2, TOTAL_STAGES, "Train Section (train_and_combo_gen)")
     train_results_df, folds_df, top_combos_df = train_and_combo_gen(
-        train_df, outcome_col=outcome_col, mode=mode, min_coverage=min_coverage,
+        train_df, outcome_col=outcome_col, min_coverage=min_coverage,
         show_progress=show_progress,
     )
     if show_progress:
@@ -515,13 +535,13 @@ def search(df, outcome_col="hit", mode="quick", min_coverage=10, show_progress=T
     # ---- Build top_combos (mirrors main.py's _build_top_combos) -----------
     # Same shape as main.py: top_combo_n==1 -> single dict, else a list of
     # dicts, each combo's edges looked up from top_combos_df by combo_num.
-    top_combos = _build_top_combos(merged_combos_df, top_combos_df, top_combo_n)
+    top_combos = _build_top_combos(merged_combos_df, top_combos_df, top_combo_n, baseline_full)
 
     # ---- Stage 6: Top Combos Summary ---------------------------------------
     stage_start = time.time()
     if show_progress:
         _stage_header(6, TOTAL_STAGES, f"Top {top_combo_n} \u2764\ufe0f Combo(s) (train vs test)")
-        _print_top_combos(merged_combos_df, top_combo_n)
+        _print_top_combos(merged_combos_df, baseline_full, top_combo_n)
         _stage_footer(stage_start, run_start)
         _complete(run_start)
 
@@ -539,7 +559,7 @@ if __name__ == "__main__":
     # Split ratio is auto-detected from row count inside search()'s
     # Stage 1 (via split_router.split_dataset). Nothing else changes.
     edgepoints_df, top_combos = search(
-        df, outcome_col="hit", mode="quick", min_coverage=10, show_progress=True,
+        df, outcome_col="hit", min_coverage=10, show_progress=True,
         top_combo_n=3,
     )
 """

edgepoint-3.0.2/edgepoint/run_kfold_search.py

@@ -0,0 +1,192 @@
+import pandas as pd
+from datetime import datetime
+from .run_kfold_find import run_kfold_find
+from .train_combo import recommend
+from .aggregate_kfold_combos import aggregate_kfold_combos
+from .utils import (
+    GAP_WEIGHT,
+    SHRINKAGE_K,
+)
+from .utils import _score_combos_on_test
+
+def _baseline_hit_rate(df, outcome_col):
+    """mean(outcome_col)*100 with no threshold filter - the "do nothing" baseline."""
+    y = df[outcome_col].dropna()
+    if len(y) == 0:
+        return None
+    return float(y.astype(int).mean()) * 100.0
+
+def _print_table(display_df):
+    # Consistent print formatting for every table in this module - same
+    # option_context recipe used in aggregate_kfold_combos.py.
+    with pd.option_context(
+        "display.width", 1000, "display.max_columns", None,
+        "display.max_colwidth", None, "display.expand_frame_repr", False,
+    ):
+        print(display_df)
+
+
+def train_and_combo_gen(
+    df,
+    outcome_col,
+    columns=None,
+    min_coverage=20,
+    show_progress=True,
+    debug=False,
+):
+    # debug=True always turns on show_progress - debug tables only ever
+    # print inside the show_progress-gated blocks below.
+    if debug:
+        show_progress = True
+
+    train_results_df, folds_df = run_kfold_find(
+        df,
+        outcome_col,
+        columns=columns,
+        min_coverage=min_coverage,
+        gap_weight=GAP_WEIGHT,
+        shrinkage_k=SHRINKAGE_K,
+        show_progress=show_progress,
+    )
+
+    # GLOBAL qualify bar = the overall positive rate on the FULL df,
+    # computed before any folding/splitting happens. Fixed, absolute:
+    # a combo that can't beat "doing nothing" is disqualified, no matter
+    # how it compares to other combos. Reused as-is in every per-fold
+    # gate below and passed into aggregate_kfold_combos - never
+    # recomputed, so the bar never drifts anywhere in this pipeline.
+    baseline_full = _baseline_hit_rate(df, outcome_col)
+
+    if show_progress and baseline_full is not None:
+        print(f"\n[debug] global qualify bar (overall positive rate): {baseline_full:.2f}")
+        
+    full_combos_df = recommend(
+        folds_df[0],
+        train_results_df,
+        outcome_col=outcome_col,
+        min_coverage=min_coverage,
+        gap_weight=GAP_WEIGHT,
+        shrinkage_k=SHRINKAGE_K,
+        show_progress=show_progress,
+        debug= False,
+    )
+
+    if show_progress:
+        display_df = full_combos_df[["combo_num", "combo", "hit_rate", "coverage", "n", "score"]].copy()
+        display_df = display_df if debug else display_df.head(5)
+        print(f"=== FOLD 1 VALIDATION ({len(full_combos_df)} combo(s) survived) ===")
+        _print_table(display_df)
+
+    # surviving_combos_df narrows every round - only currently-surviving
+    # combos get tested against the next fold. By loop end it holds only
+    # the combos that made it through every fold - the set to aggregate.
+    surviving_combos_df = full_combos_df
+    combo_fold_results = []
+    for i, fold in enumerate(folds_df[1:], start=2):
+        if surviving_combos_df.empty:
+            break
+
+        going_in = len(surviving_combos_df)
+        fold_combos_df = _score_combos_on_test(
+            fold, outcome_col, surviving_combos_df, min_coverage, GAP_WEIGHT, SHRINKAGE_K
+        )
+
+        # Anything that went in but isn't in _score_combos_on_test's
+        # output failed min_coverage in this fold.
+        after_coverage = len(fold_combos_df)
+        dropped_coverage = going_in - after_coverage
+
+        # Per-fold qualify gate: _score_combos_on_test only filters by
+        # min_coverage, not the qualify bar. Without this, a combo could
+        # dip below baseline_full, still "survive" on coverage alone, and
+        # get diluted/hidden by good folds instead of disqualified
+        # outright. Uses the GLOBAL baseline_full (fixed on the full df,
+        # not this fold's own numbers) so the bar never drifts.
+        dropped_baseline = 0
+        if not fold_combos_df.empty and baseline_full is not None:
+            fold_hit_rates = fold_combos_df["hit_rate"].astype(float)
+            before_baseline = len(fold_combos_df)
+            fold_combos_df = fold_combos_df[fold_hit_rates >= baseline_full].reset_index(drop=True)
+            dropped_baseline = before_baseline - len(fold_combos_df)
+
+        if show_progress:
+            print(f"\nfold {i}: in={going_in}   coverage_drop={dropped_coverage}   "
+                  f"baseline_drop={dropped_baseline}   remain={len(fold_combos_df)}")
+
+        combo_fold_results.append(fold_combos_df)
+
+        if show_progress:
+            # Built directly instead of via a shared formatting helper -
+            # avoids pulling in train_hit_rate/train_coverage columns
+            # that shouldn't show here.
+            display_df = fold_combos_df[["combo_num", "combo", "hit_rate", "coverage", "n"]].copy()
+            # _score_combos_on_test returns raw floats (unlike
+            # recommend()'s fold-1 output, already 2dp) - match that
+            # convention here too.
+            display_df["hit_rate"] = display_df["hit_rate"].map(lambda v: f"{float(v):.2f}")
+            display_df["coverage"] = display_df["coverage"].map(lambda v: f"{float(v):.2f}")
+            if "score" in fold_combos_df.columns:
+                display_df["score"] = fold_combos_df["score"]
+            display_df = display_df if debug else display_df.head(5)
+            print(f"\n=== FOLD {i} VALIDATION ({len(fold_combos_df)} combo(s) survived) ===")
+            _print_table(display_df)
+
+        if fold_combos_df.empty:
+            surviving_combos_df = fold_combos_df
+            break
+
+        surviving_nums = set(fold_combos_df["combo_num"])
+        surviving_combos_df = full_combos_df[full_combos_df["combo_num"].isin(surviving_nums)].reset_index(drop=True)
+
+    # Restrict aggregation to only the FINAL survivors - combo_fold_results
+    # still contains early-fold entries for combos eliminated partway
+    # through, so filter both the lookup table and every per-fold
+    # snapshot down to final_surviving_nums before aggregating.
+    final_surviving_nums = set(surviving_combos_df["combo_num"]) if not surviving_combos_df.empty else set()
+
+    filtered_full_combos_df = full_combos_df[
+        full_combos_df["combo_num"].isin(final_surviving_nums)
+    ].reset_index(drop=True)
+
+    filtered_combo_fold_results = [
+        fold_df[fold_df["combo_num"].isin(final_surviving_nums)].reset_index(drop=True)
+        for fold_df in combo_fold_results
+    ]
+
+    if show_progress:
+        print(f"\n[debug] {len(final_surviving_nums)} combo(s) survived every fold - "
+              f"aggregating only these (out of {len(full_combos_df)} originally generated).")
+
+    final_fold = folds_df[-1]
+
+    # baseline_full is passed straight into aggregate_kfold_combos, which
+    # runs the same "hit_rate >= baseline_full" check internally on its
+    # own aggregated hit_rate before scoring/sorting/printing - so
+    # aggregated_combos_df arriving here is already baseline-filtered.
+    aggregated_combos_df = aggregate_kfold_combos(
+        df, outcome_col, filtered_full_combos_df, filtered_combo_fold_results,
+        gap_weight=GAP_WEIGHT, shrinkage_k=SHRINKAGE_K, show_progress=False,
+        baseline_full=baseline_full,
+        min_coverage=min_coverage,
+    )
+
+    # Final surviving combos, returned RAW from recommend(). No join, no
+    # recompute - filtered_full_combos_df is recommend()'s own untouched
+    # output, filtered down to combo_nums that survived every fold and
+    # the final baseline gate.
+    final_qualified_nums = set(aggregated_combos_df["combo_num"]) if not aggregated_combos_df.empty else set()
+    top_combos_df = filtered_full_combos_df[
+        filtered_full_combos_df["combo_num"].isin(final_qualified_nums)
+    ].reset_index(drop=True)
+
+    # Overwrite hit_rate with the AGGREGATED, baseline-gated number.
+    # filtered_full_combos_df's own hit_rate is recommend()'s raw
+    # fold[0]-only output, never gated against baseline_full - without
+    # this, top_combos_df (and train_hit_rate downstream) could show a
+    # value below baseline_full even though the combo only qualified via
+    # its aggregated hit_rate clearing the bar.
+    if not top_combos_df.empty and not aggregated_combos_df.empty:
+        agg_hit_rate_map = dict(zip(aggregated_combos_df["combo_num"], aggregated_combos_df["hit_rate"]))
+        top_combos_df["hit_rate"] = top_combos_df["combo_num"].map(agg_hit_rate_map)
+
+    return train_results_df, folds_df, top_combos_df

{edgepoint-3.0.0 → edgepoint-3.0.2}/edgepoint/sanity_check.py

@@ -3,7 +3,7 @@ import pandas as pd
 # Minimum number of rows df must have for sanity_check_columns to run at
 # all - below this, there's not enough data for a threshold search to
 # mean anything, regardless of how many columns pass the numeric check.
-MIN_ROWS = 60
+MIN_ROWS = 15
 
 # The only values outcome_col is allowed to contain - anything else
 # (NaN, strings, other numbers) gets dropped as an invalid outcome row.

{edgepoint-3.0.0 → edgepoint-3.0.2}/edgepoint/train_combo.py

@@ -1,9 +1,10 @@
 import math
 import time
- 
+from datetime import datetime
+
 import pandas as pd
 from itertools import combinations
- 
+
 from .core import _normalize, _shrink_gap, DEFAULT_SHRINKAGE_K
 
 # CPU relief is always applied (not optional) - these just control how
@@ -11,14 +12,24 @@ from .core import _normalize, _shrink_gap, DEFAULT_SHRINKAGE_K
 RELIEF_EVERY = 200
 RELIEF_SECONDS = 0.001
 
-# Hard ceiling on generated combinations, used both to auto-fit
-# mode="deep" and to refuse mode="quick"/"standard" up front if they'd
-# blow past it.
+# Hard ceiling on generated combinations - a pure memory/compute safety
+# net, always applied. Never lets combo_generation blow past this many
+# combos regardless of what row/baseline logic below decides.
 MAX_COMBOS = 2_000_000
 
-
-def _estimate_combo_count(n_columns, min_size, max_size):
-    return sum(math.comb(n_columns, k) for k in range(min_size, max_size + 1))
+# Row-count -> max combo size table. Direct and simple on purpose: more
+# rows means more trust to combine columns, no per-combo ratio math
+# involved. This only decides combo SIZE - see the baseline column drop
+# further down, which decides which columns are even allowed to be
+# combined at that size. Tune the thresholds here if these defaults
+# don't fit your data.
+ROW_CAP_TABLE = [
+    (50, 1),      # under 50 rows -> singles only
+    (200, 2),     # 50-200 rows -> pairs allowed
+    (500, 3),     # 200-500 rows -> triples allowed
+    (2000, 4),    # 500-2000 rows -> up to 4
+]
+ROW_CAP_TABLE_MAX = 5  # 2000+ rows -> up to 5 (then memory budget takes over)
 
 
 def _auto_cap_from_budget(n_columns, max_combos, floor=1):
@@ -40,6 +51,33 @@ def _auto_cap_from_budget(n_columns, max_combos, floor=1):
     return max(floor, cap)
 
 
+def _cap_from_rows(n_rows, floor=1):
+    # Statistical sibling of _auto_cap_from_budget: memory answers "what
+    # can I afford", this answers "what should I trust". A direct
+    # row-count -> cap lookup - the more rows you have, the bigger a
+    # combo you're allowed to build, full stop. No column count involved
+    # here on purpose; column count is handled separately (see the
+    # baseline-drop filter in recommend()) so the two concerns - combo
+    # SIZE vs. which columns are eligible to be combined - stay decoupled.
+    if n_rows <= 0:
+        return floor
+    for threshold, cap in ROW_CAP_TABLE:
+        if n_rows < threshold:
+            return max(floor, cap)
+    return max(floor, ROW_CAP_TABLE_MAX)
+
+
+def _baseline_hit_rate(df, outcome_col):
+    # mean(outcome_col)*100 with no threshold filter - the "do nothing"
+    # baseline. Same definition/logic used in train_and_combo_gen.py's
+    # global qualify bar - reused here, not reinvented, so a column that
+    # can't beat "doing nothing" is treated the same way in both places.
+    y = df[outcome_col].dropna()
+    if len(y) == 0:
+        return None
+    return float(y.astype(int).mean()) * 100.0
+
+
 def combo_generation(columns, include_empty=False, max_size=None):
     min_size = 0 if include_empty else 1
     ceiling = len(columns) if max_size is None else min(max_size, len(columns))
@@ -59,11 +97,23 @@ def recommend(
     min_coverage=40,
     gap_weight=0.60,
     shrinkage_k=DEFAULT_SHRINKAGE_K,
-    mode="standard",
     show_progress=False,
+    debug=False,
 ):
     # find() is no longer called here - the caller runs find() once
     # and passes in its two outputs (train_df, train_results_df) directly.
+    #
+    # show_progress vs debug: show_progress prints the high-level view -
+    # the single-column table, cap resolution, eligible/dropped columns,
+    # and the final combo summary. debug additionally prints the verbose
+    # per-combo loop (every combo's columns/edges and computed stats) -
+    # useful when troubleshooting a specific combo, but far too noisy to
+    # tie to show_progress alone once the combo count gets large.
+
+    # debug implies show_progress - the verbose per-combo view is only
+    # useful alongside the high-level progress view, not instead of it.
+    if debug:
+        show_progress = True
 
     considered_columns = [c for c in train_df.columns if c != outcome_col]
 
@@ -94,44 +144,85 @@ def recommend(
     def fmt_row(vals):
         return "  ".join(str(v).ljust(w) for v, w in zip(vals, widths))
 
-    if show_progress:
+    if debug:
         print("=== RECOMMEND ===")
         print(fmt_row(headers))
         print("  ".join("-" * w for w in widths))
         for row in print_rows:
             print(fmt_row(row))
 
+    # top_columns/edge_map stay as the FULL scored set - this is what's
+    # shown in the printed table above. combo_pool_columns (below) is a
+    # narrower set used only for combo-building, so a bad column can
+    # still be seen in the single-column table but can't sneak a win
+    # into a combo just because cap > 1 let it ride along.
     top_columns = [col for col, r in printed if r is not None]
     edge_map = {col: float(r["edge_point"]) for col, r in printed if r is not None}
 
-    mode_caps = {"quick": 2, "standard": 3}
-    if mode == "deep":
-        cap = _auto_cap_from_budget(len(top_columns), MAX_COMBOS)
-        if show_progress:
-            print(f"mode='deep' -> budget rule: max combo size that keeps total "
-                  f"combos <= {MAX_COMBOS:,} from {len(top_columns)} columns "
-                  f"-> resolved to {cap}")
-    elif mode in mode_caps:
-        cap = mode_caps[mode]
-        estimated = _estimate_combo_count(len(top_columns), 1, cap)
-        if estimated > MAX_COMBOS:
-            raise ValueError(
-                f"mode={mode!r} (combo size {cap}) would generate ~{estimated:,} "
-                f"combinations from {len(top_columns)} columns - that risks a "
-                f"MemoryError, so it's refused up front instead. Try mode='deep' "
-                f"to auto-fit a safe combo size, or raise the MAX_COMBOS "
-                f"constant at the top of this module if you really mean it."
-            )
+    n_rows = len(train_df)
+
+    # Two independent guards against small-df overfitting, kept
+    # deliberately separate and always applied - no mode switch, this is
+    # just how combo generation works now:
+    #   1. combo SIZE - decided purely by row count (_cap_from_rows),
+    #      floored further by the memory budget so it still can never
+    #      blow up regardless of row count.
+    #   2. combo ELIGIBILITY - any column whose own hit_rate can't beat
+    #      baseline_full (the dataset's "do nothing" rate) is dropped
+    #      from the combo-building pool entirely, so it can't pair up
+    #      with a good column and win on luck alone. It still appears in
+    #      the printed single-column table above - only combo
+    #      participation is affected.
+    memory_cap = _auto_cap_from_budget(len(top_columns), MAX_COMBOS)
+    rows_cap = _cap_from_rows(n_rows)
+    cap = min(memory_cap, rows_cap)
+
+    baseline_full = _baseline_hit_rate(train_df, outcome_col)
+    if baseline_full is not None:
+        hit_rate_map = {col: float(r["hit_rate"]) for col, r in printed if r is not None}
+        dropped = [col for col in top_columns if hit_rate_map[col] < baseline_full]
+        combo_pool_columns = [col for col in top_columns if col not in dropped]
     else:
-        raise ValueError(f"mode must be 'quick', 'standard', or 'deep', got {mode!r}")
+        dropped = []
+        combo_pool_columns = top_columns
 
-    all_combos = combo_generation(top_columns, max_size=cap)
-
-    # combo scoring runs unconditionally - show_progress only toggles the
-    # printing below, the winner still needs to be returned either way.
     if show_progress:
-        print(f"\n=== COMBOS (mode={mode!r}, {len(top_columns)} columns, "
-              f"max combo size {cap}) ===")
+        print(f"\n\033[1m=== {len(combo_pool_columns)} COLUMN(S) ELIGIBLE FOR COMBO GENERATION ===\033[0m\n")
+        print(f"Memory cap = {memory_cap}, Row cap ({n_rows} rows) = {rows_cap} -> resolved to {cap}.")
+        if baseline_full is not None:
+            print(f"Baseline = {baseline_full:.2f}; dropped {len(dropped)}/{len(top_columns)} column(s) below baseline.\n")
+
+        # Same headers/to_row/fmt_row used for the full RECOMMEND table
+        # above, just re-run on the narrower eligible-columns subset so
+        # this table shows each column's actual stats, not bare names.
+        row_lookup = dict(printed)
+        eligible_rows = [to_row(col, row_lookup[col]) for col in combo_pool_columns]
+        eligible_widths = [
+            max(len(str(h)), *(len(str(row[i])) for row in eligible_rows)) if eligible_rows else len(str(h))
+            for i, h in enumerate(headers)
+        ]
+        def fmt_eligible_row(vals):
+            return "  ".join(str(v).ljust(w) for v, w in zip(vals, eligible_widths))
+        print(fmt_eligible_row(headers))
+        print("  ".join("-" * w for w in eligible_widths))
+        for row in eligible_rows:
+            print(fmt_eligible_row(row))
+
+        print(f"\n\033[1m\u26a0\ufe0f THIS IS WHERE THE MAGIC HAPPENS, MIGHT TAKE A WHILE, BE PATIENT. "
+              f"\U0001F552 {datetime.now().strftime('%H:%M:%S')}.\033[0m\n")
+
+    if debug:
+        for col in combo_pool_columns:
+            print(col)
+
+    all_combos = combo_generation(combo_pool_columns, max_size=cap)
+
+    # combo scoring runs unconditionally - debug only toggles the verbose
+    # per-combo printing below, the winner still needs to be returned
+    # either way.
+    if debug:
+        print(f"\n=== COMBOS ({len(combo_pool_columns)} columns "
+              f"eligible, max combo size {cap}) ===")
 
     combo_results = []
     for i, combo in enumerate(all_combos, start=1):
@@ -142,7 +233,7 @@ def recommend(
             # / RELIEF_SECONDS above if it's still too hot.
             time.sleep(RELIEF_SECONDS)
 
-        if show_progress:
+        if debug:
             print(f"Combo {i}")
             name_width = max(len(col) for col in combo)
             for col in combo:
@@ -157,7 +248,7 @@ def recommend(
         above_n = int(above_mask.sum())
 
         if above_n == 0:
-            if show_progress:
+            if debug:
                 print("  -> nothing clears the AND filter, can't compute hit_rate/gap/coverage")
             combo_results.append({"combo_num": i, "combo": combo, "hit_rate": None,
                                    "miss_rate": None, "gap": None, "shrunk_gap": None,
@@ -169,20 +260,20 @@ def recommend(
             gap = hit_rate - miss_rate
             coverage = (above_n / total_n) * 100.0
             shrunk_gap = _shrink_gap(gap, above_n, shrinkage_k)
-            if show_progress:
+            if debug:
                 print(f"  hit_rate={hit_rate:.2f}%  miss_rate={miss_rate:.2f}%  "
                       f"gap={gap:+.2f}pp  shrunk_gap={shrunk_gap:+.2f}pp  "
                       f"n={above_n}  coverage={coverage:.2f}%")
             combo_results.append({"combo_num": i, "combo": combo, "hit_rate": hit_rate,
                                    "miss_rate": miss_rate, "gap": gap, "shrunk_gap": shrunk_gap,
                                    "n": above_n, "coverage": coverage, "population": total_n})
-        if show_progress:
+        if debug:
             print()
 
-    if show_progress:
-        effective_max_size = min(cap, len(top_columns))
+    if debug:
+        effective_max_size = min(cap, len(combo_pool_columns))
         print(f"{len(all_combos)} total combinations printed "
-              f"(sizes 1 to {effective_max_size} of {len(top_columns)} columns)")
+              f"(sizes 1 to {effective_max_size} of {len(combo_pool_columns)} eligible columns)")
 
     scored_combos = [c for c in combo_results if c["hit_rate"] is not None]
     scored_combos = [c for c in scored_combos if c["coverage"] >= min_coverage]
@@ -230,7 +321,7 @@ def recommend(
         ]
         combo_summary_df = combo_summary_df[[c for c in ordered_cols if c in combo_summary_df.columns]]
 
-    if show_progress:
+    if debug:
         print(f"\n=== COMBO SUMMARY ({len(combo_summary_df)} qualifying combos) ===")
         display_df = combo_summary_df.drop(columns=["edges", "population"], errors="ignore")
         with pd.option_context(

{edgepoint-3.0.0 → edgepoint-3.0.2}/edgepoint/validations.py

@@ -2,7 +2,7 @@ import pandas as pd
 
 
 def validate_search_params(
-    df, outcome_col, mode, min_coverage, show_progress, top_combo_n,
+    df, outcome_col, min_coverage, show_progress, top_combo_n,
 ):
     """
     Validates every edgepoint.search() param for the right datatype and,
@@ -24,39 +24,20 @@ def validate_search_params(
     row-count floor), so re-checking them here would be redundant at
     best and stricter-than-necessary at worst, since it'd reject data
     sanity_check_columns is designed to clean up rather than reject.
-
-    mode is normalized (surrounding whitespace stripped, case folded to
-    lowercase) before being checked against its allowed values - so
-    " Quick ", "QUICK", and "quick" all validate the same way. The
-    normalized string is returned as `mode` so the caller (search())
-    uses the exact same cleaned-up spelling everywhere downstream,
-    instead of whatever casing/whitespace the caller happened to type.
     """
     if not isinstance(df, pd.DataFrame):
         raise TypeError(f"df must be a pandas DataFrame, got {type(df).__name__}")
-
     if not isinstance(outcome_col, str):
         raise TypeError(f"outcome_col must be a str, got {type(outcome_col).__name__}")
     if outcome_col not in df.columns:
         raise ValueError(f"outcome_col={outcome_col!r} not found in df")
-
-    if not isinstance(mode, str):
-        raise TypeError(f"mode must be a str, got {type(mode).__name__}")
-    mode_clean = mode.strip().lower()
-    if mode_clean not in ("quick", "standard", "deep"):
-        raise ValueError(f"mode must be 'quick', 'standard', or 'deep', got {mode!r}")
-
     if isinstance(min_coverage, bool) or not isinstance(min_coverage, (int, float)):
         raise TypeError(f"min_coverage must be a number, got {type(min_coverage).__name__}")
     if not (0 <= min_coverage <= 100):
         raise ValueError(f"min_coverage must be between 0 and 100, got {min_coverage}")
-
     if not isinstance(show_progress, bool):
         raise TypeError(f"show_progress must be a bool, got {type(show_progress).__name__}")
-
     if isinstance(top_combo_n, bool) or not isinstance(top_combo_n, int):
         raise TypeError(f"top_combo_n must be an int, got {type(top_combo_n).__name__}")
     if top_combo_n < 1:
-        raise ValueError(f"top_combo_n must be >= 1, got {top_combo_n}")
-
-    return mode_clean
+        raise ValueError(f"top_combo_n must be >= 1, got {top_combo_n}")

{edgepoint-3.0.0 → edgepoint-3.0.2}/edgepoint.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: edgepoint
-Version: 3.0.0
+Version: 3.0.2
 Summary: Find the point in a numeric column above which a binary outcome becomes meaningfully and reliably better.
 Author: Henry
 License: MIT

{edgepoint-3.0.0 → edgepoint-3.0.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "edgepoint"
-version = "3.0.0"
+version = "3.0.2"
 description = "Find the point in a numeric column above which a binary outcome becomes meaningfully and reliably better."
 readme = "README.md"
 requires-python = ">=3.9"

{edgepoint-3.0.0 → edgepoint-3.0.2}/setup.py

@@ -5,7 +5,7 @@ long_description = (Path(__file__).parent / "README.md").read_text(encoding="utf
 
 setup(
     name="edgepoint",
-    version="3.0.0",
+    version="3.0.2",
     author="Henry",
     description="Find where a metric, or combination of metrics, starts getting better while keeping the best coverage possible, then check if that holds on unseen data.",
     long_description=long_description,

edgepoint-3.0.0/edgepoint/run_kfold_search.py

@@ -1,251 +0,0 @@
-import pandas as pd
-from datetime import datetime
-from .run_kfold_find import run_kfold_find
-from .train_combo import recommend
-from .aggregate_kfold_combos import aggregate_kfold_combos
-from .utils import (
-    GAP_WEIGHT,
-    SHRINKAGE_K,
-)
-from .utils import _score_combos_on_test
-
-def _baseline_hit_rate(df, outcome_col):
-    """mean(outcome_col)*100 with no threshold filter - the "do nothing" baseline."""
-    y = df[outcome_col].dropna()
-    if len(y) == 0:
-        return None
-    return float(y.astype(int).mean()) * 100.0
-
-def _print_table(display_df):
-    # Own print style - no longer routed through main.py's _print_df/
-    # _print_df_full. Whether the caller passed the full df or an
-    # already-head(5)-limited one is decided before this is called;
-    # this just prints whatever it's given, consistently formatted,
-    # same option_context recipe used in aggregate_kfold_combos.py.
-    with pd.option_context(
-        "display.width", 1000, "display.max_columns", None,
-        "display.max_colwidth", None, "display.expand_frame_repr", False,
-    ):
-        print(display_df)
-
-
-def train_and_combo_gen(
-    df,
-    outcome_col,
-    columns=None,
-    min_coverage=20,
-    mode="quick",
-    show_progress=True,
-    debug=False,
-):
-    # debug=True always turns on show_progress - debug tables only ever
-    # print inside the show_progress-gated blocks below, so debug=True
-    # with show_progress=False would otherwise print nothing at all.
-    if debug:
-        show_progress = True
-
-    train_results_df, folds_df = run_kfold_find(
-        df,
-        outcome_col,
-        columns=columns,
-        min_coverage=min_coverage,
-        gap_weight=GAP_WEIGHT,
-        shrinkage_k=SHRINKAGE_K,
-        show_progress=show_progress,
-    )
-
-    # ---- GLOBAL qualify bar = the overall positive rate on the FULL df,
-    # computed before any folding/splitting happens. This replaces the
-    # old MIN_QUALIFY_POINTS ("top_hit_rate - 33.33") approach entirely -
-    # the bar is no longer relative to whatever the best combo happens to
-    # score. It's fixed, absolute, and simple: a combo that can't beat
-    # "doing nothing" (the dataset's own overall hit rate) is disqualified,
-    # no matter how it compares to other combos. This single value is
-    # reused as-is in every per-fold gate below AND passed straight into
-    # aggregate_kfold_combos for its own final gate - never recomputed
-    # from a shrinking fold or from the aggregated table's own top, so
-    # the bar never drifts anywhere in this pipeline.
-    baseline_full = _baseline_hit_rate(df, outcome_col)
-
-    if show_progress and baseline_full is not None:
-        print(f"\n[debug] global qualify bar (overall positive rate): {baseline_full:.2f}")
-
-    # original, un-narrowed combos from fold[0] - kept around unmodified
-    # so aggregate_kfold_combos can always look up a *surviving* combo's
-    # fixed edges/name by combo_num.
-
-    if show_progress:
-        print(f"\n\u26a0\ufe0f THIS IS WHERE THE MAGIC HAPPENS, MIGHT TAKE A WHILE, BE PATIENT. \U0001F552 {datetime.now().strftime('%H:%M:%S')}.\n")
-
-    full_combos_df = recommend(
-        folds_df[0],
-        train_results_df,
-        outcome_col=outcome_col,
-        min_coverage=min_coverage,
-        gap_weight=GAP_WEIGHT,
-        shrinkage_k=SHRINKAGE_K,
-        mode=mode,
-        show_progress=False,
-    )
-
-    if show_progress:
-        display_df = full_combos_df[["combo_num", "combo", "hit_rate", "coverage", "n", "score"]].copy()
-        display_df = display_df if debug else display_df.head(5)
-        print(f"=== FOLD 1 VALIDATION ({len(full_combos_df)} combo(s) survived) ===")
-        _print_table(display_df)
-
-    # this one narrows every round - only the currently-surviving combos
-    # get tested against the next fold. By the time the loop ends,
-    # surviving_combos_df holds ONLY the combos that made it through
-    # every single fold - this is the set that should get aggregated.
-    surviving_combos_df = full_combos_df
-    combo_fold_results = []
-    for i, fold in enumerate(folds_df[1:], start=2):
-        if surviving_combos_df.empty:
-            break
-
-        going_in = len(surviving_combos_df)
-        fold_combos_df = _score_combos_on_test(
-            fold, outcome_col, surviving_combos_df, min_coverage, GAP_WEIGHT, SHRINKAGE_K
-        )
-
-        # _score_combos_on_test's own internal filter - anything that
-        # went in but isn't in its output failed min_coverage in this
-        # fold. Counted here (rather than inside that function) since
-        # this is the only place that knows both "going in" and "came
-        # out" counts. Same accounting test_and_combo_val.py does.
-        after_coverage = len(fold_combos_df)
-        dropped_coverage = going_in - after_coverage
-
-        # ---- per-fold qualify gate ---------------------------------
-        # _score_combos_on_test only filters by min_coverage - it does NOT
-        # check the qualify bar. Without this, a combo could dip below
-        # the overall baseline positive rate, still "survive" on coverage
-        # alone, and get carried into the aggregate - letting one bad
-        # fold get diluted/hidden by good folds instead of disqualifying
-        # the combo outright. Uses the GLOBAL baseline_full (fixed once,
-        # computed on the full df before any folding) - not this fold's
-        # own top hit_rate - so the bar never drifts. Any combo below
-        # baseline_full in THIS fold is dropped now, before it can
-        # survive into the next fold.
-        dropped_baseline = 0
-        if not fold_combos_df.empty and baseline_full is not None:
-            fold_hit_rates = fold_combos_df["hit_rate"].astype(float)
-            before_baseline = len(fold_combos_df)
-            fold_combos_df = fold_combos_df[fold_hit_rates >= baseline_full].reset_index(drop=True)
-            dropped_baseline = before_baseline - len(fold_combos_df)
-
-        if show_progress:
-            print(f"\nfold {i}: in={going_in}   coverage_drop={dropped_coverage}   "
-                  f"baseline_drop={dropped_baseline}   remain={len(fold_combos_df)}")
-
-        combo_fold_results.append(fold_combos_df)
-
-        if show_progress:
-            # Built directly here instead of going through
-            # _format_combos_df_for_display() (in main.py) - that helper
-            # pulls in train_hit_rate/train_coverage columns from
-            # _score_combos_on_test's own output, which we don't want
-            # showing up in this table. Selecting/formatting the columns
-            # directly removes that dependency entirely.
-            display_df = fold_combos_df[["combo_num", "combo", "hit_rate", "coverage", "n"]].copy()
-            # _score_combos_on_test returns raw full-precision floats for
-            # hit_rate/coverage (unlike recommend()'s fold-1 output, which
-            # already comes pre-stringified to 2dp) - force the same 2dp
-            # convention here so this table matches every other printout.
-            display_df["hit_rate"] = display_df["hit_rate"].map(lambda v: f"{float(v):.2f}")
-            display_df["coverage"] = display_df["coverage"].map(lambda v: f"{float(v):.2f}")
-            if "score" in fold_combos_df.columns:
-                display_df["score"] = fold_combos_df["score"]
-            display_df = display_df if debug else display_df.head(5)
-            print(f"\n=== FOLD {i} VALIDATION ({len(fold_combos_df)} combo(s) survived) ===")
-            _print_table(display_df)
-
-        if fold_combos_df.empty:
-            surviving_combos_df = fold_combos_df
-            break
-
-        surviving_nums = set(fold_combos_df["combo_num"])
-        surviving_combos_df = full_combos_df[full_combos_df["combo_num"].isin(surviving_nums)].reset_index(drop=True)
-
-    # ---- restrict aggregation to only the FINAL survivors -------------
-    # combo_fold_results still contains early-fold entries for combos
-    # that got eliminated partway through the walkthrough (e.g. dropped
-    # at fold 3 of 5). Without filtering, aggregate_kfold_combos would
-    # happily aggregate votes for combos that never made it to the end.
-    # So: only combo_nums present in the final surviving_combos_df are
-    # kept, both in the lookup table (full_combos_df) and in every
-    # per-fold snapshot (combo_fold_results), before aggregating.
-    final_surviving_nums = set(surviving_combos_df["combo_num"]) if not surviving_combos_df.empty else set()
-
-    filtered_full_combos_df = full_combos_df[
-        full_combos_df["combo_num"].isin(final_surviving_nums)
-    ].reset_index(drop=True)
-
-    filtered_combo_fold_results = [
-        fold_df[fold_df["combo_num"].isin(final_surviving_nums)].reset_index(drop=True)
-        for fold_df in combo_fold_results
-    ]
-
-    if show_progress:
-        print(f"\n[debug] {len(final_surviving_nums)} combo(s) survived every fold - "
-              f"aggregating only these (out of {len(full_combos_df)} originally generated).")
-
-    final_fold = folds_df[-1]
-
-    # ---- baseline_full is now passed straight into aggregate_kfold_combos
-    # instead of being re-applied here afterward. aggregate_kfold_combos
-    # runs the exact same "hit_rate >= baseline_full" check internally, on
-    # its own aggregated/honest full-df hit_rate, BEFORE it scores/sorts/
-    # prints its summary - so the printed table and the returned df are
-    # already baseline-filtered by the time they come back here. This is
-    # the SAME single fixed bar used by every per-fold gate above; it is
-    # not recomputed anywhere.
-    aggregated_combos_df = aggregate_kfold_combos(
-        df, outcome_col, filtered_full_combos_df, filtered_combo_fold_results,
-        gap_weight=GAP_WEIGHT, shrinkage_k=SHRINKAGE_K, show_progress=False,
-        baseline_full=baseline_full,
-        min_coverage=min_coverage,
-    )
-
-    # NOTE: the old post-hoc "final qualify gate" block that re-filtered
-    # aggregated_combos_df by baseline_full has been removed - that
-    # filtering now happens INSIDE aggregate_kfold_combos itself (see
-    # above), so aggregated_combos_df arriving here is already gated.
-
-    # ---- final surviving combos, returned RAW from recommend() --------
-    # No join, no recompute. filtered_full_combos_df is recommend()'s own
-    # untouched output (from the fold[0] call above), already filtered
-    # down to just the combo_nums that survived every fold and (via
-    # aggregate_kfold_combos) the final baseline qualify gate. Its
-    # columns are exactly what recommend() itself returns for its own
-    # qualified combos - combo_num, combo, hit_rate, miss_rate, gap, n,
-    # coverage, population, score, edges - so nothing here is invented or
-    # pulled from the aggregate step.
-    final_qualified_nums = set(aggregated_combos_df["combo_num"]) if not aggregated_combos_df.empty else set()
-    top_combos_df = filtered_full_combos_df[
-        filtered_full_combos_df["combo_num"].isin(final_qualified_nums)
-    ].reset_index(drop=True)
-
-    # ---- overwrite hit_rate with the AGGREGATED, baseline-gated number
-    # -------------------------------------------------------------------
-    # filtered_full_combos_df's own hit_rate column is recommend()'s raw
-    # fold[0]-only output - it was never touched by aggregate_kfold_combos
-    # and never gated against baseline_full. final_qualified_nums only
-    # filters WHICH rows survive, it does not fix up what hit_rate value
-    # those surviving rows carry - so without this step, top_combos_df
-    # would still report each combo's single-fold hit_rate, not the
-    # aggregated full-df number that actually cleared the baseline gate.
-    # Downstream (test_and_combo_val.py, via include_train_hit_rate=True)
-    # reads this same hit_rate column to populate train_hit_rate - so if
-    # it's left as the raw fold[0] number, train_hit_rate can show below
-    # baseline_full even though the combo only qualified because its
-    # AGGREGATED hit_rate cleared the bar. Mapping in aggregated_combos_df's
-    # hit_rate here (already gated, already stringified 2dp) makes
-    # top_combos_df's hit_rate - and therefore train_hit_rate downstream -
-    # consistent with the gate that actually let the combo through.
-    if not top_combos_df.empty and not aggregated_combos_df.empty:
-        agg_hit_rate_map = dict(zip(aggregated_combos_df["combo_num"], aggregated_combos_df["hit_rate"]))
-        top_combos_df["hit_rate"] = top_combos_df["combo_num"].map(agg_hit_rate_map)
-
-    return train_results_df, folds_df, top_combos_df