gitlabds 2.2.1__tar.gz → 2.2.2__tar.gz

{gitlabds-2.2.1 → gitlabds-2.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitlabds
-Version: 2.2.1
+Version: 2.2.2
 Summary: GitLab Data Science Tools
 Author-email: Kevin Dietz <kdietz@gitlab.com>
 License-Expression: MIT
@@ -891,7 +891,7 @@ shap_df = gitlabds.per_record_shap(
 #### Description
 "Change X -> +Y" counterfactual search, direction chosen empirically. For each actionable lever SHAP surfaced for a record, evaluates candidate values drawn from peer-group quantiles, re-scores the model at each, and keeps the single move that maximizes the gain in predicted probability. No monotonicity assumption is made.
 
-`gitlabds.per_record_counterfactuals(model, df, shap_df, model_algo="lgb", unique_id="record_id", peer_group=None, candidate_quantiles=[0.1, 0.25, 0.5, 0.75, 0.9], direction=None, actionable_values=["Yes", "Partial"], min_delta_p=0.005, impact_medium=0.01, impact_high=0.03, bands={"poor fit": 0.03, "good fit": 0.10, "best fit": float("inf")}, n_bins=5):`
+`gitlabds.per_record_counterfactuals(model, df, shap_df, model_algo="lgb", unique_id="record_id", peer_group=None, candidate_quantiles=[0.1, 0.25, 0.5, 0.75, 0.9], direction=None, actionable_values=["Yes", "Partial"], min_delta_p=0.005, impact_medium=0.01, impact_high=0.03, levels={"poor fit": 0.03, "good fit": 0.10, "best fit": float("inf")}, n_bins=5):`
 
 #### Parameters:
 - _**model**_ : trained model (as in `per_record_shap`)
@@ -905,11 +905,11 @@ shap_df = gitlabds.per_record_shap(
 - _**actionable_values**_ : values in `shap_df["actionable"]` treated as actionable levers
 - _**min_delta_p**_ : drop levers whose best achievable gain is below this
 - _**impact_medium, impact_high**_ : delta_p thresholds bucketing each lever into Low/Medium/High `impact_bucket`
-- _**bands**_ : dict mapping label -> upper bound on `p_before`/`p_after` for that band, ordered worst to best (e.g., default `{"poor fit": 0.03, "good fit": 0.10, "best fit": float("inf")}` means `p <= 0.03` -> "poor fit", `0.03 < p <= 0.10` -> "good fit", `p > 0.10` -> "best fit"). Key order doesn't matter (sorted by cutoff), but the top band's cutoff must be `float("inf")`. Used to detect whether a move crosses a band boundary (any crossing move is floored at "Medium" impact). Pass your own dict (e.g., `{"low": 0.03, "medium": 0.10, "high": float("inf")}`) to match your own pipeline
+- _**levels**_ : dict mapping label -> upper bound on `p_before`/`p_after` for that level, ordered worst to best (e.g., default `{"poor fit": 0.03, "good fit": 0.10, "best fit": float("inf")}` means `p <= 0.03` -> "poor fit", `0.03 < p <= 0.10` -> "good fit", `p > 0.10` -> "best fit"). Key order doesn't matter (sorted by cutoff), but the top level's cutoff must be `float("inf")`. Used to detect whether a move crosses a level boundary (any crossing move is floored at "Medium" impact). Pass your own dict (e.g., `{"low": 0.03, "medium": 0.10, "high": float("inf")}`) to match your own pipeline
 - _**n_bins**_ : quantile bins for numeric `peer_group` columns
 
 #### Returns
-- Long DataFrame, one row per (record, lever): `current_value`, `intervention_value`, `intervention_quantile`, `p_before`, `p_after`, `delta_p`, `impact_bucket`, `level_before`, `level_after`, `crosses_band`
+- Long DataFrame, one row per (record, lever): `current_value`, `intervention_value`, `intervention_quantile`, `p_before`, `p_after`, `delta_p`, `impact_bucket`, `level_before`, `level_after`, `crosses_level`
 
 #### Requirements
 For XGBoost models without `predict_proba`, requires the `xgboost` package (included in core dependencies).

{gitlabds-2.2.1 → gitlabds-2.2.2}/README.md

@@ -859,7 +859,7 @@ shap_df = gitlabds.per_record_shap(
 #### Description
 "Change X -> +Y" counterfactual search, direction chosen empirically. For each actionable lever SHAP surfaced for a record, evaluates candidate values drawn from peer-group quantiles, re-scores the model at each, and keeps the single move that maximizes the gain in predicted probability. No monotonicity assumption is made.
 
-`gitlabds.per_record_counterfactuals(model, df, shap_df, model_algo="lgb", unique_id="record_id", peer_group=None, candidate_quantiles=[0.1, 0.25, 0.5, 0.75, 0.9], direction=None, actionable_values=["Yes", "Partial"], min_delta_p=0.005, impact_medium=0.01, impact_high=0.03, bands={"poor fit": 0.03, "good fit": 0.10, "best fit": float("inf")}, n_bins=5):`
+`gitlabds.per_record_counterfactuals(model, df, shap_df, model_algo="lgb", unique_id="record_id", peer_group=None, candidate_quantiles=[0.1, 0.25, 0.5, 0.75, 0.9], direction=None, actionable_values=["Yes", "Partial"], min_delta_p=0.005, impact_medium=0.01, impact_high=0.03, levels={"poor fit": 0.03, "good fit": 0.10, "best fit": float("inf")}, n_bins=5):`
 
 #### Parameters:
 - _**model**_ : trained model (as in `per_record_shap`)
@@ -873,11 +873,11 @@ shap_df = gitlabds.per_record_shap(
 - _**actionable_values**_ : values in `shap_df["actionable"]` treated as actionable levers
 - _**min_delta_p**_ : drop levers whose best achievable gain is below this
 - _**impact_medium, impact_high**_ : delta_p thresholds bucketing each lever into Low/Medium/High `impact_bucket`
-- _**bands**_ : dict mapping label -> upper bound on `p_before`/`p_after` for that band, ordered worst to best (e.g., default `{"poor fit": 0.03, "good fit": 0.10, "best fit": float("inf")}` means `p <= 0.03` -> "poor fit", `0.03 < p <= 0.10` -> "good fit", `p > 0.10` -> "best fit"). Key order doesn't matter (sorted by cutoff), but the top band's cutoff must be `float("inf")`. Used to detect whether a move crosses a band boundary (any crossing move is floored at "Medium" impact). Pass your own dict (e.g., `{"low": 0.03, "medium": 0.10, "high": float("inf")}`) to match your own pipeline
+- _**levels**_ : dict mapping label -> upper bound on `p_before`/`p_after` for that level, ordered worst to best (e.g., default `{"poor fit": 0.03, "good fit": 0.10, "best fit": float("inf")}` means `p <= 0.03` -> "poor fit", `0.03 < p <= 0.10` -> "good fit", `p > 0.10` -> "best fit"). Key order doesn't matter (sorted by cutoff), but the top level's cutoff must be `float("inf")`. Used to detect whether a move crosses a level boundary (any crossing move is floored at "Medium" impact). Pass your own dict (e.g., `{"low": 0.03, "medium": 0.10, "high": float("inf")}`) to match your own pipeline
 - _**n_bins**_ : quantile bins for numeric `peer_group` columns
 
 #### Returns
-- Long DataFrame, one row per (record, lever): `current_value`, `intervention_value`, `intervention_quantile`, `p_before`, `p_after`, `delta_p`, `impact_bucket`, `level_before`, `level_after`, `crosses_band`
+- Long DataFrame, one row per (record, lever): `current_value`, `intervention_value`, `intervention_quantile`, `p_before`, `p_after`, `delta_p`, `impact_bucket`, `level_before`, `level_after`, `crosses_level`
 
 #### Requirements
 For XGBoost models without `predict_proba`, requires the `xgboost` package (included in core dependencies).

{gitlabds-2.2.1 → gitlabds-2.2.2}/gitlabds/record_benchmarking.py

@@ -160,7 +160,7 @@ def per_record_counterfactuals(
     min_delta_p=0.005,
     impact_medium=0.01,
     impact_high=0.03,
-    bands={"poor fit": 0.03, "good fit": 0.10, "best fit": float("inf")},
+    levels={"poor fit": 0.03, "good fit": 0.10, "best fit": float("inf")},
     n_bins=5,
 ):
     """
@@ -183,29 +183,29 @@ def per_record_counterfactuals(
     impact_medium, impact_high : delta_p thresholds bucketing each lever into
         Low/Medium/High impact_bucket. delta_p shrinks mechanically near the tails of
         the probability distribution, so a fixed pp threshold alone under-weights
-        moves for low-scoring/mid-band records relative to those near a band edge.
-        bands (below) corrects for that: any move that crosses a band boundary is
-        floored at "Medium" regardless of its raw delta_p, since crossing bands is
+        moves for low-scoring/mid-level records relative to those near a level edge.
+        levels (below) corrects for that: any move that crosses a level boundary is
+        floored at "Medium" regardless of its raw delta_p, since crossing levels is
         typically the thing that actually changes which downstream action gets taken.
         Tune impact_medium/high against the real delta_p distribution for your model;
-        bands should mirror whatever thresholds are live in your own scoring/banding
-        logic (if that logic considers factors beyond the score itself, bands are
+        levels should mirror whatever thresholds are live in your own scoring/leveling
+        logic (if that logic considers factors beyond the score itself, levels are
         only meant to detect crossings for impact_bucket purposes, not to reproduce
         it exactly).
-    bands : dict mapping label -> upper bound (on p_before/p_after) for that band,
+    levels : dict mapping label -> upper bound (on p_before/p_after) for that level,
         ordered worst to best (e.g. {"poor fit": 0.03, "good fit": 0.10, "best fit":
         float("inf")} means p <= 0.03 -> "poor fit", 0.03 < p <= 0.10 -> "good fit",
-        p > 0.10 -> "best fit"). The dict's key order doesn't matter -- bands are
-        sorted by their cutoff value -- but the highest-scoring band's cutoff must be
-        float("inf") since it has no upper bound. Used only to detect band crossings
-        for impact_bucket, not to reproduce your production banding logic. Pass your
+        p > 0.10 -> "best fit"). The dict's key order doesn't matter -- levels are
+        sorted by their cutoff value -- but the highest-scoring level's cutoff must be
+        float("inf") since it has no upper bound. Used only to detect level crossings
+        for impact_bucket, not to reproduce your production leveling logic. Pass your
         own dict (e.g. {"low": 0.03, "medium": 0.10, "high": float("inf")}) to match
         your own pipeline.
     n_bins : quantile bins for numeric peer_group columns.
 
     Returns a long DataFrame: one row per (record, lever) with the best move found
     (current_value, intervention_value, intervention_quantile, p_before/p_after/delta_p,
-    impact_bucket, level_before, level_after, crosses_band).
+    impact_bucket, level_before, level_after, crosses_level).
     """
     if impact_medium >= impact_high:
         raise ValueError(f"impact_medium ({impact_medium}) must be less than impact_high ({impact_high})")
@@ -282,17 +282,17 @@ def per_record_counterfactuals(
     out["impact_bucket"] = pd.cut(out["delta_p"],
                                    bins=[-np.inf, impact_medium, impact_high, np.inf],
                                    labels=["Low", "Medium", "High"]).astype(str)
-    # Band-crossing floor: a move that pushes the record into a better band is at
+    # Level-crossing floor: a move that pushes the record into a better level is at
     # least "Medium" impact even if its raw delta_p is small (see docstring).
-    _sorted_bands = sorted(bands.items(), key=lambda kv: kv[1])
-    _edges = [-np.inf] + [cutoff for _, cutoff in _sorted_bands]
-    _labels = [label for label, _ in _sorted_bands]
-    def _band(p):
+    _sorted_levels = sorted(levels.items(), key=lambda kv: kv[1])
+    _edges = [-np.inf] + [cutoff for _, cutoff in _sorted_levels]
+    _labels = [label for label, _ in _sorted_levels]
+    def _level(p):
         return pd.cut(p, bins=_edges, labels=_labels).astype(str)
-    out["level_before"] = _band(out["p_before"])
-    out["level_after"] = _band(out["p_after"])
+    out["level_before"] = _level(out["p_before"])
+    out["level_after"] = _level(out["p_after"])
     out["crosses_level"] = out["level_before"] != out["level_after"]
-    out.loc[out["crosses_band"] & (out["impact_bucket"] == "Low"), "impact_bucket"] = "Medium"
+    out.loc[out["crosses_level"] & (out["impact_bucket"] == "Low"), "impact_bucket"] = "Medium"
     return out.sort_values([unique_id, "delta_p"], ascending=[True, False]).reset_index(drop=True)
 
 

{gitlabds-2.2.1 → gitlabds-2.2.2}/gitlabds.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitlabds
-Version: 2.2.1
+Version: 2.2.2
 Summary: GitLab Data Science Tools
 Author-email: Kevin Dietz <kdietz@gitlab.com>
 License-Expression: MIT
@@ -891,7 +891,7 @@ shap_df = gitlabds.per_record_shap(
 #### Description
 "Change X -> +Y" counterfactual search, direction chosen empirically. For each actionable lever SHAP surfaced for a record, evaluates candidate values drawn from peer-group quantiles, re-scores the model at each, and keeps the single move that maximizes the gain in predicted probability. No monotonicity assumption is made.
 
-`gitlabds.per_record_counterfactuals(model, df, shap_df, model_algo="lgb", unique_id="record_id", peer_group=None, candidate_quantiles=[0.1, 0.25, 0.5, 0.75, 0.9], direction=None, actionable_values=["Yes", "Partial"], min_delta_p=0.005, impact_medium=0.01, impact_high=0.03, bands={"poor fit": 0.03, "good fit": 0.10, "best fit": float("inf")}, n_bins=5):`
+`gitlabds.per_record_counterfactuals(model, df, shap_df, model_algo="lgb", unique_id="record_id", peer_group=None, candidate_quantiles=[0.1, 0.25, 0.5, 0.75, 0.9], direction=None, actionable_values=["Yes", "Partial"], min_delta_p=0.005, impact_medium=0.01, impact_high=0.03, levels={"poor fit": 0.03, "good fit": 0.10, "best fit": float("inf")}, n_bins=5):`
 
 #### Parameters:
 - _**model**_ : trained model (as in `per_record_shap`)
@@ -905,11 +905,11 @@ shap_df = gitlabds.per_record_shap(
 - _**actionable_values**_ : values in `shap_df["actionable"]` treated as actionable levers
 - _**min_delta_p**_ : drop levers whose best achievable gain is below this
 - _**impact_medium, impact_high**_ : delta_p thresholds bucketing each lever into Low/Medium/High `impact_bucket`
-- _**bands**_ : dict mapping label -> upper bound on `p_before`/`p_after` for that band, ordered worst to best (e.g., default `{"poor fit": 0.03, "good fit": 0.10, "best fit": float("inf")}` means `p <= 0.03` -> "poor fit", `0.03 < p <= 0.10` -> "good fit", `p > 0.10` -> "best fit"). Key order doesn't matter (sorted by cutoff), but the top band's cutoff must be `float("inf")`. Used to detect whether a move crosses a band boundary (any crossing move is floored at "Medium" impact). Pass your own dict (e.g., `{"low": 0.03, "medium": 0.10, "high": float("inf")}`) to match your own pipeline
+- _**levels**_ : dict mapping label -> upper bound on `p_before`/`p_after` for that level, ordered worst to best (e.g., default `{"poor fit": 0.03, "good fit": 0.10, "best fit": float("inf")}` means `p <= 0.03` -> "poor fit", `0.03 < p <= 0.10` -> "good fit", `p > 0.10` -> "best fit"). Key order doesn't matter (sorted by cutoff), but the top level's cutoff must be `float("inf")`. Used to detect whether a move crosses a level boundary (any crossing move is floored at "Medium" impact). Pass your own dict (e.g., `{"low": 0.03, "medium": 0.10, "high": float("inf")}`) to match your own pipeline
 - _**n_bins**_ : quantile bins for numeric `peer_group` columns
 
 #### Returns
-- Long DataFrame, one row per (record, lever): `current_value`, `intervention_value`, `intervention_quantile`, `p_before`, `p_after`, `delta_p`, `impact_bucket`, `level_before`, `level_after`, `crosses_band`
+- Long DataFrame, one row per (record, lever): `current_value`, `intervention_value`, `intervention_quantile`, `p_before`, `p_after`, `delta_p`, `impact_bucket`, `level_before`, `level_after`, `crosses_level`
 
 #### Requirements
 For XGBoost models without `predict_proba`, requires the `xgboost` package (included in core dependencies).