edgepoint 1.0.0__py3-none-any.whl

edgepoint/__init__.py

@@ -0,0 +1,16 @@
+"""
+edgepoint, find the point in a numeric column above which a binary
+outcome rate becomes noticeably, reliably better.
+
+    from edgepoint import find
+
+    profile = find(df, outcome_col="hit", compute_fallback=True)
+    # {"score": 66.75, "age": None, ...}
+
+See edgepoint.core.find for the full parameter reference.
+"""
+
+from .core import find, VERSION
+
+__version__ = VERSION
+__all__ = ["find"]

edgepoint/core.py

@@ -0,0 +1,573 @@
+"""
+edgepoint/core.py (VERSION 1.0.0)
+
+Answers one question, for any numeric column and any binary outcome:
+
+    "Walk this column from its min to its max in even steps, and check
+    every possible split point along the way: where's the first
+    place the split is actually big enough to matter?"
+
+That point is the column's SWEET SPOT: the value above which the
+outcome rate becomes noticeably, reliably better than below it.
+
+METHOD (two-tier: primary quality bar, then OPTIONAL coverage
+        fallback, both with a tolerance-based tiebreak that prefers
+        coverage; a single coverage floor gates every edge)
+---------------------------------------------------------------------
+1. Take the column's own [min, max] range and cut it into `range_bins`
+   equal-WIDTH steps (np.linspace) to get edge points to walk. No
+   per-step binning, at each edge the WHOLE column is split directly
+   into >= edge and < edge and each side's rate is computed on the
+   spot.
+
+   WHY equal-width, not quantile: quantile (qcut) edges are
+   population-based, they guarantee similar ROW COUNT per step, not
+   similar VALUE RANGE. On a column with a lot of duplicate/repeated
+   values (e.g. a rate or score with hundreds of rows sitting at or
+   near 0), quantile edges collapse toward the crowded region, and a
+   real effect sitting AT 0 gets buried inside one wide edge alongside
+   completely different values. Equal-width edges are spaced evenly
+   across the RANGE itself, so a cluster at 0 still gets a nearby edge
+   to split on.
+
+2. Walk every internal edge, low to high (there are range_bins - 1 of
+   them). At each edge:
+     - gap = rate(>= edge) - rate(< edge)
+     - coverage = above_n / total_n
+   An edge is skipped outright if coverage < min_coverage_pct, this
+   is the ONE guard against thin, unreliable "above" groups, checked
+   directly against actual row count rather than range-position.
+
+   WHY coverage instead of range-position: on a skewed column,
+   range-position and row coverage decouple. An edge at 67% of the way
+   across the range can still cover 4% of rows, while an edge at 20%
+   of the way across can cover 91%, range-position is only ever a
+   proxy for "is this a thin sliver," and a proxy that can be badly
+   wrong. Checking coverage directly is the more honest guard for the
+   thing actually being protected against.
+
+   Only POSITIVE gaps (above side better) are ever candidates. All of
+   this is printed per edge when show_progress=True.
+
+3. PRIMARY condition: an edge (already coverage-qualified per step 2)
+   is a primary candidate if BOTH:
+     - gap >= gap_threshold (default 10 = 10 percentage points)
+     - above_rate >= target_pct (default 60 = 60%)
+   Among all primary candidates, the winner is chosen by
+   `primary_tiebreak`:
+     - "gap"  (default) -> largest gap wins
+     - "rate"           -> highest above_rate wins
+   TOLERANCE: rather than picking the single literal max, every
+   candidate within `fallback_tolerance_pct` (default 3, i.e. 3
+   percentage points) of the best value on the tiebreak metric is
+   treated as "tied." Among the tied group, the edge with the highest
+   coverage (broadest above_n share, i.e. the lowest/earliest edge)
+   wins. This avoids picking a split that's technically 0.4pp better
+   but throws away 5+ points of coverage for a difference that's
+   really just noise.
+
+4. FALLBACK: controlled by the MANDATORY `compute_fallback` parameter.
+   This tier only ever runs if NO edge satisfies the primary condition
+   AND `compute_fallback=True`.
+     - compute_fallback=True:  an edge is a fallback candidate if
+       gap > 0 (above side still better, just not by enough / not
+       high enough rate to clear the primary bar), coverage is
+       already guaranteed by step 2's floor, so nothing further to
+       check there. Among fallback candidates, the highest above_rate
+       sets the bar, then the SAME tolerance rule as PRIMARY applies:
+       any candidate within `fallback_tolerance_pct` of that best rate
+       is "tied," and the highest-coverage edge among the tied group
+       wins, since "50.5% beats 50.1%" isn't a real reason to prefer
+       a thinner split over a broader one differing by noise.
+     - compute_fallback=False: the fallback tier is skipped entirely.
+       If no edge clears PRIMARY, the column is reported as None,
+       full stop, fallback candidates are never even evaluated.
+   `compute_fallback` has no default value and MUST be passed
+   explicitly (True or False) on every call, omitting it raises a
+   ValueError. This is deliberate: whether a column falls back to a
+   "best available, if weaker" split is a modeling decision that
+   should never be silently defaulted.
+
+5. If neither the primary condition nor an enabled fallback finds
+   anything, the column is reported as having no usable split (None).
+   This includes the case where every edge has a negative or zero gap,
+   i.e. "above" is never better than "below" anywhere in the column.
+   That is a legitimate, honest result, not a gap to be patched: the
+   function's job is to report where a real sweet spot exists, not to
+   always produce a number by picking the least-bad option when no
+   such split exists.
+
+No credible intervals, no significance tests, no baseline comparison,
+on purpose. This is a plain, easy-to-reason-about check: "is there a
+point in this column's range where splitting it actually separates two
+meaningfully different groups." gap_threshold / target_pct /
+min_coverage_pct / fallback_tolerance_pct are your quality controls, so
+set them deliberately.
+
+Note on directionality: this function only ever searches for a rising
+sweet spot: a point above which the outcome rate is better. It does
+not independently verify that the "below" side is bad on its own bar;
+it only knows that "below" is worse than "above." Usually that amounts
+to the same practical thing, but it's a comparative statement, not two
+independently-scored zones.
+
+UNITS: every percentage-style parameter is a plain 0-100 number, not a
+0-1 fraction, gap_threshold=10 means 10 percentage points,
+target_pct=60 means 60%, min_coverage_pct=30 means 30%,
+fallback_tolerance_pct=3 means 3 percentage points. Internally these
+are converted to 0-1 fractions for comparison against computed
+rates/gaps.
+
+USAGE
+-----
+    from edgepoint import find
+
+    profile = find(
+        df,
+        outcome_col="converted",       # any binary (0/1) outcome column
+        compute_fallback=True,         # MANDATORY, must be True or False
+        columns=None,                  # None = auto-scan every numeric col
+        gap_threshold=10,              # required gap (pp) for the primary condition
+        target_pct=60,                 # required above_rate (%) for the primary condition
+        min_coverage_pct=30,           # required above_n share (%) for ANY edge to qualify
+        fallback_tolerance_pct=3,      # "close enough" band (pp) for tiebreaks; prefers coverage
+        primary_tiebreak="gap",        # "gap" or "rate"
+        range_bins=15,                 # number of equal-width steps across [min, max]
+        show_progress=True,            # print every edge's split as it's checked
+    )
+
+    # profile is a flat dict, one entry per column:
+    # {
+    #   "colA": 44.44,     # sweet-spot value, or None if no usable split
+    #   "colB": None,
+    #   ...
+    # }
+
+EXAMPLES OF WHERE THIS APPLIES
+-------------------------------
+Any continuous metric + binary outcome pair, for example:
+  - marketing: at what engagement score does churn risk drop off
+  - credit: at what score does default rate become acceptable
+  - healthcare: at what biomarker level does an outcome rate jump
+  - product: at what usage count does upgrade-to-paid rate spike
+  - manufacturing: at what sensor reading does defect rate climb
+  - trading/betting: at what signal-strength value does a pick's
+    hit rate become reliable
+"""
+
+import numpy as np
+import pandas as pd
+
+VERSION = "1.0.0"
+
+# ── config defaults ──────────────────────────────────────────────────────
+# Number of equal-width steps to cut the column's [min, max] range into.
+DEFAULT_RANGE_BINS = 15
+
+# Minimum gap (in percentage points, e.g. 10 = 10 percentage points)
+# required for the PRIMARY condition.
+DEFAULT_GAP_THRESHOLD = 10
+
+# Minimum above_rate (in %, e.g. 60 = 60%) required for the PRIMARY
+# condition.
+DEFAULT_TARGET_PCT = 60
+
+# Minimum share of total rows (in %, e.g. 30 = 30%) the "above" side
+# must cover for an edge to qualify as a candidate AT ALL, checked up
+# front for every edge, primary and fallback alike. This is the one
+# guard against thin, unreliable "above" groups.
+DEFAULT_MIN_COVERAGE_PCT = 30
+
+# "Close enough" tolerance band, in percentage points, used to decide
+# ties on the tiebreak metric (gap or above_rate) for BOTH the primary
+# and fallback tiers. Any candidate within this many points of the
+# best value is treated as tied; among tied candidates, the one with
+# the highest coverage wins.
+DEFAULT_FALLBACK_TOLERANCE_PCT = 3
+
+# How to pick among edges that satisfy the PRIMARY condition.
+# "gap" = largest gap wins (within tolerance). "rate" = highest
+# above_rate wins (within tolerance).
+DEFAULT_PRIMARY_TIEBREAK = "gap"
+
+# Minimum rows required before even attempting to scan a column at all.
+DEFAULT_MIN_ROWS = 15
+
+
+def _build_range_edges(col_values, n_bins):
+    """
+    Equal-WIDTH edge points across the column's own [min, max] range,
+    np.linspace(min, max, n_bins + 1), NOT quantile/qcut. Returns only
+    the INTERNAL edges (n_bins - 1 of them), the outer min/max aren't
+    useful split points since one side would always be empty.
+    """
+    lo, hi = float(np.min(col_values)), float(np.max(col_values))
+    if lo == hi:
+        return None  # no range to split
+    all_edges = np.linspace(lo, hi, n_bins + 1)
+    return all_edges[1:-1]  # drop the min and max themselves
+
+
+def _pick_with_tolerance(candidates, key, tolerance_frac):
+    """
+    Picks the "winner" among `candidates` on metric `key`, but instead
+    of taking the literal single max, first finds the best value on
+    `key`, then treats every candidate within `tolerance_frac` of that
+    best value as tied. Among the tied group, the highest-coverage
+    candidate wins (ties broken by lowest breakout_value, i.e. the
+    earliest/broadest edge). This avoids picking a split that's only
+    a fraction of a point better on `key` while covering meaningfully
+    less of the data.
+
+    Returns (winning candidate dict, tied list).
+    """
+    best_val = max(c[key] for c in candidates)
+    tied = [c for c in candidates if (best_val - c[key]) <= tolerance_frac]
+    # highest coverage wins; break remaining ties by lowest breakout_value
+    winner = max(tied, key=lambda c: (c["coverage"], -c["breakout_value"]))
+    return winner, tied
+
+
+def _scan_edges(
+    col_values, y, edges, show_progress,
+    compute_fallback,
+    gap_threshold=DEFAULT_GAP_THRESHOLD,
+    target_pct=DEFAULT_TARGET_PCT,
+    min_coverage_pct=DEFAULT_MIN_COVERAGE_PCT,
+    fallback_tolerance_pct=DEFAULT_FALLBACK_TOLERANCE_PCT,
+    primary_tiebreak=DEFAULT_PRIMARY_TIEBREAK,
+):
+    """
+    Walks every internal edge (low to high), splitting the WHOLE
+    column directly into >= edge and < edge at each one and computing
+    each side's rate on the spot. Prints each edge's split when
+    show_progress=True.
+
+    Every edge is checked against the min_coverage_pct floor first,
+    if the "above" side covers less than min_coverage_pct of total
+    rows, the edge is skipped outright and never becomes a candidate,
+    for primary OR fallback. This is the sole guard against thin,
+    unreliable "above" groups.
+
+    All threshold params (gap_threshold, target_pct, min_coverage_pct,
+    fallback_tolerance_pct) are plain 0-100 numbers; they're converted
+    to 0-1 fractions here for comparison against computed rates/gaps.
+
+    Every coverage-qualified edge with a positive gap (above side
+    better) is kept as a row of candidate stats. After the walk:
+      - PRIMARY: among candidates with gap >= gap_threshold AND
+        above_rate >= target_pct, pick by primary_tiebreak
+        ("gap" -> largest gap, "rate" -> highest above_rate), using
+        the tolerance rule (prefer coverage among near-ties).
+      - FALLBACK (only if no primary candidate, AND ONLY IF
+        compute_fallback=True): among all remaining candidates
+        (already coverage-qualified), pick the highest above_rate
+        using the same tolerance rule.
+      - Otherwise: None. This includes the case where no primary
+        candidate exists and compute_fallback=False, fallback
+        candidates are never evaluated in that case.
+
+    Returns the breakout_value (edge), or None.
+    """
+    gap_threshold_frac = gap_threshold / 100.0
+    target_pct_frac = target_pct / 100.0
+    min_coverage_pct_frac = min_coverage_pct / 100.0
+    tolerance_frac = fallback_tolerance_pct / 100.0
+
+    total_n = len(col_values)
+    candidates = []  # each: {"breakout_value", "gap", "above_rate", "above_n", "coverage"}
+
+    for edge in edges:
+        above_mask = col_values >= edge
+        below_mask = ~above_mask
+
+        above_n = int(above_mask.sum())
+        below_n = int(below_mask.sum())
+
+        if above_n == 0 or below_n == 0:
+            if show_progress:
+                print(f"        edge={edge:.4g}   "
+                      f"skipped, nothing on one side (above_n={above_n}, below_n={below_n})")
+            continue
+
+        coverage = above_n / total_n
+
+        if coverage < min_coverage_pct_frac:
+            if show_progress:
+                print(f"        edge={edge:.4g}   "
+                      f"(coverage {coverage:.0%} < min_coverage_pct={min_coverage_pct:.0f}%) "
+                      f"→ skipped")
+            continue
+
+        above_rate = float(y[above_mask].mean())
+        below_rate = float(y[below_mask].mean())
+        gap = above_rate - below_rate  # positive = "above" side is better
+
+        if show_progress:
+            print(f"        edge={edge:.4g}   "
+                  f">= {edge:.4g}: n={above_n:<5} rate={above_rate:.1%}   "
+                  f"< {edge:.4g}: n={below_n:<5} rate={below_rate:.1%}   "
+                  f"gap={gap:+.1%}  coverage={coverage:.0%}")
+
+        if gap <= 0:
+            continue  # not the "above is better" shape we're looking for
+
+        candidates.append({
+            "breakout_value": float(edge),
+            "gap": gap,
+            "above_rate": above_rate,
+            "above_n": above_n,
+            "coverage": coverage,
+        })
+
+    if not candidates:
+        if show_progress:
+            print(f"      → no edge had a usable positive gap "
+                  f"at or above min_coverage_pct={min_coverage_pct:.0f}%")
+        return None
+
+    # ── PRIMARY: gap AND target_pct both required ──────────────────
+    primary = [c for c in candidates
+               if c["gap"] >= gap_threshold_frac and c["above_rate"] >= target_pct_frac]
+
+    if primary:
+        key = "gap" if primary_tiebreak == "gap" else "above_rate"
+        best, tied = _pick_with_tolerance(primary, key, tolerance_frac)
+        if show_progress:
+            tie_note = (f" (tied with {len(tied)-1} other edge(s) within "
+                        f"{fallback_tolerance_pct:.0f}pp on {key}; "
+                        f"highest coverage wins)") if len(tied) > 1 else ""
+            print(f"      → PRIMARY: split at {best['breakout_value']:.4g}, "
+                  f"gap={best['gap']:.1%}, above_rate={best['above_rate']:.1%}, "
+                  f"coverage={best['coverage']:.0%} "
+                  f"(>= gap_threshold={gap_threshold:.0f}% AND "
+                  f"target_pct={target_pct:.0f}%; tiebreak={primary_tiebreak}){tie_note}")
+        return round(best["breakout_value"], 2)
+
+    if show_progress:
+        print(f"      → no edge cleared PRIMARY (gap_threshold={gap_threshold:.0f}% "
+              f"AND target_pct={target_pct:.0f}%)")
+
+    # ── FALLBACK: only runs if compute_fallback=True ────────────────
+    if not compute_fallback:
+        if show_progress:
+            print(f"      → compute_fallback=False, fallback skipped, column reported as None")
+        return None
+
+    if show_progress:
+        print(f"      → trying fallback")
+
+    # candidates is non-empty here (checked above), and every entry
+    # already cleared the coverage floor up front, so fallback just
+    # picks the highest rate (w/ tolerance) among them
+    best, tied = _pick_with_tolerance(candidates, "above_rate", tolerance_frac)
+    if show_progress:
+        tie_note = (f" (tied with {len(tied)-1} other edge(s) within "
+                    f"{fallback_tolerance_pct:.0f}pp on above_rate; "
+                    f"highest coverage wins)") if len(tied) > 1 else ""
+        print(f"      → FALLBACK: split at {best['breakout_value']:.4g}, "
+              f"above_rate={best['above_rate']:.1%}, "
+              f"coverage={best['coverage']:.0%} "
+              f"(>= min_coverage_pct={min_coverage_pct:.0f}%){tie_note}")
+    return round(best["breakout_value"], 2)
+
+
+def find(
+    df,
+    outcome_col,
+    compute_fallback=None,
+    columns=None,
+    range_bins=DEFAULT_RANGE_BINS,
+    gap_threshold=DEFAULT_GAP_THRESHOLD,
+    target_pct=DEFAULT_TARGET_PCT,
+    min_coverage_pct=DEFAULT_MIN_COVERAGE_PCT,
+    fallback_tolerance_pct=DEFAULT_FALLBACK_TOLERANCE_PCT,
+    primary_tiebreak=DEFAULT_PRIMARY_TIEBREAK,
+    min_rows=DEFAULT_MIN_ROWS,
+    show_progress=False,
+):
+    """
+    For each candidate column: cuts its [min, max] range into
+    `range_bins` equal-WIDTH steps to get edge points, then walks every
+    edge from low to high, splitting the whole column directly at each
+    edge. Any edge whose "above" side covers less than min_coverage_pct
+    of total rows is skipped outright before it can become a candidate,
+    this is the sole guard against thin, unreliable splits, checked
+    for every edge regardless of tier.
+
+    Two-tier pick, both tiers using a tolerance-based tiebreak that
+    prefers coverage among near-ties:
+      PRIMARY , edge must clear BOTH gap_threshold AND target_pct.
+                 Ties (within fallback_tolerance_pct on the
+                 primary_tiebreak metric) broken by highest coverage.
+      FALLBACK, only evaluated if no edge clears PRIMARY, AND ONLY IF
+                 compute_fallback=True: among all remaining (already
+                 coverage-qualified) edges, pick the highest
+                 above_rate; ties (within fallback_tolerance_pct)
+                 broken by highest coverage.
+      Otherwise -> None.
+
+    Parameters
+    ----------
+    df : pandas.DataFrame
+        Must contain `outcome_col` plus every column in `columns` (or,
+        if columns=None, every other numeric column is tried).
+    outcome_col : str
+        Name of the binary outcome column (0/1 or True/False).
+    compute_fallback : bool
+        MANDATORY, defaults to None only so its absence can be
+        detected; None is not a valid value. Must be passed explicitly
+        as True or False on every call. Omitting it (leaving it as
+        None) raises a ValueError, and passing anything other than
+        True/False/None also raises a ValueError.
+        Controls whether the FALLBACK tier is ever evaluated for a
+        column that fails to produce a PRIMARY candidate:
+          - True  -> if no edge clears PRIMARY, fall back to the
+                     highest-above_rate coverage-qualified edge
+                     (tolerance tiebreak applies), same as before.
+          - False -> if no edge clears PRIMARY, the column is
+                     reported as None. Fallback candidates are never
+                     evaluated at all.
+        This is deliberately not defaulted: whether a column should
+        ever settle for a "best available, but weaker" split is a
+        modeling decision the caller must make consciously each time.
+    columns : list[str] or None
+        Which columns to scan. Defaults to every numeric column other
+        than outcome_col.
+    range_bins : int
+        Number of equal-width steps to cut the column's [min, max]
+        range into (produces range_bins - 1 internal edges to walk).
+        Default 15.
+    gap_threshold : float
+        PRIMARY condition: minimum gap (above_rate - below_rate)
+        required, in percentage points, e.g. 10 = 10 percentage points.
+        Default 10.
+    target_pct : float
+        PRIMARY condition: minimum above_rate required, in %,
+        e.g. 60 = 60%. Default 60.
+    min_coverage_pct : float
+        Minimum share of total rows the "above" side must cover, in %,
+        e.g. 30 = 30%, for an edge to qualify as a candidate at all,
+        checked for every edge, primary and fallback alike, before
+        gap/rate are even evaluated. Default 30.
+    fallback_tolerance_pct : float
+        Tolerance band, in percentage points, used for tiebreaking in
+        BOTH tiers. Any candidate within this many points of the best
+        value on the relevant tiebreak metric (gap or above_rate) is
+        treated as tied; among tied candidates, the one with the
+        highest coverage wins. Prevents picking a split that's only
+        marginally "better" on the metric while sacrificing meaningful
+        coverage. Default 3 (3 percentage points).
+    primary_tiebreak : str
+        Which metric to use for the PRIMARY tier's tiebreak.
+        "gap" (default) -> largest gap (within tolerance) wins, then
+        highest coverage. "rate" -> highest above_rate (within
+        tolerance) wins, then highest coverage.
+    min_rows : int
+        Minimum non-null rows required for a column to be scanned at
+        all. Default 15.
+    show_progress : bool
+        When True, prints every edge's split (value, each side's
+        n/rate/gap/coverage) as it's checked, plus which tier
+        (primary/fallback/none) produced the final pick, including a
+        note when the tolerance tiebreak was invoked, and whether
+        fallback was skipped because compute_fallback=False. This is
+        the only place that detail is visible; the returned dict is
+        deliberately flat.
+
+    Returns
+    -------
+    dict[str, float or None]
+        {column_name: breakout_point}. breakout_point is the value
+        above which the outcome rate is meaningfully higher (per the
+        primary condition, or the fallback if primary found nothing
+        and compute_fallback=True), or None if neither tier found a
+        usable split (including columns that couldn't be scanned at
+        all, too few rows, or a constant/no-range column, and
+        columns where PRIMARY failed and compute_fallback=False).
+
+    Raises
+    ------
+    ValueError
+        If compute_fallback is not passed, or is passed as something
+        other than True/False.
+    """
+    if compute_fallback is None:
+        raise ValueError(
+            "compute_fallback is mandatory and was not passed (got None), "
+            "you must explicitly pass compute_fallback=True or "
+            "compute_fallback=False."
+        )
+    if not isinstance(compute_fallback, bool):
+        raise ValueError(
+            f"compute_fallback must be True or False, got {compute_fallback!r}"
+        )
+
+    if outcome_col not in df.columns:
+        raise ValueError(f"outcome_col={outcome_col!r} not found in df")
+
+    if primary_tiebreak not in ("gap", "rate"):
+        raise ValueError(
+            f"primary_tiebreak must be 'gap' or 'rate', got {primary_tiebreak!r}"
+        )
+
+    vals = set(pd.unique(df[outcome_col].dropna()))
+    if not vals.issubset({0, 1, True, False, 0.0, 1.0}):
+        raise ValueError(
+            f"outcome_col={outcome_col!r} must be binary (0/1 or True/False); "
+            f"found values {sorted(vals, key=str)}"
+        )
+
+    if columns is None:
+        columns = [
+            c for c in df.select_dtypes(include=[np.number]).columns
+            if c != outcome_col
+        ]
+
+    if show_progress:
+        print(f"\n{'='*60}")
+        print(f"  edgepoint.find | outcome_col={outcome_col!r}  columns={columns}")
+        print(f"  range_bins={range_bins}  gap_threshold={gap_threshold:.0f}%  "
+              f"target_pct={target_pct:.0f}%  min_coverage_pct={min_coverage_pct:.0f}%  "
+              f"fallback_tolerance_pct={fallback_tolerance_pct:.0f}%  "
+              f"primary_tiebreak={primary_tiebreak!r}  "
+              f"compute_fallback={compute_fallback}")
+        print(f"{'='*60}")
+
+    result = {}
+
+    for col in columns:
+        sub = df[[col, outcome_col]].dropna()
+        n = len(sub)
+        col_values = sub[col].to_numpy(dtype=float)
+        y = sub[outcome_col].astype(int).to_numpy()
+
+        if n < min_rows:
+            if show_progress:
+                print(f"\n    [{col}] only {n} rows, need >= {min_rows} → skipping")
+            result[col] = None
+            continue
+
+        edges = _build_range_edges(col_values, range_bins)
+        if edges is None or len(edges) == 0:
+            if show_progress:
+                print(f"\n    [{col}] no range to split (constant column) → skipping")
+            result[col] = None
+            continue
+
+        if show_progress:
+            print(f"\n    [{col}] n={n}  range=[{col_values.min():.4g} .. "
+                  f"{col_values.max():.4g}]  edges={len(edges)}")
+            print(f"      checking every edge (min_coverage_pct={min_coverage_pct:.0f}% floor):")
+
+        result[col] = _scan_edges(
+            col_values, y, edges, show_progress,
+            compute_fallback,
+            gap_threshold=gap_threshold,
+            target_pct=target_pct,
+            min_coverage_pct=min_coverage_pct,
+            fallback_tolerance_pct=fallback_tolerance_pct,
+            primary_tiebreak=primary_tiebreak,
+        )
+
+    return result

edgepoint-1.0.0.dist-info/METADATA

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

edgepoint-1.0.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+edgepoint/__init__.py,sha256=cv0XIsh3sFKz0leI0KYM72O_pB_lcshBV6bwFr6ydPg,397
+edgepoint/core.py,sha256=ZGRvt39btoEqxR1tk23bfwVo-uSEVe8eAsRUhbS2f_g,25925
+edgepoint-1.0.0.dist-info/licenses/LICENSE,sha256=NXS3_dg3gkUImu9hvTxxZ_27yzdjKvukLtGTL6kN0HM,1076
+edgepoint-1.0.0.dist-info/METADATA,sha256=M_kAPCLlUb7KmQ81ANhYG05DJfcgHC64D0cw3DJH2No,19792
+edgepoint-1.0.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+edgepoint-1.0.0.dist-info/top_level.txt,sha256=Vlii-3A5Kg43pq--dmwzHoFaDPcnQOt2cZ2BB9R9zlM,10
+edgepoint-1.0.0.dist-info/RECORD,,

edgepoint-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

edgepoint-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 osas2henry@gmail.com
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

edgepoint-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+edgepoint