vistaar 0.3.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (90) hide show
  1. vistaar/__init__.py +72 -0
  2. vistaar/anomaly/__init__.py +6 -0
  3. vistaar/anomaly/anomaly.py +58 -0
  4. vistaar/anomaly/drift.py +157 -0
  5. vistaar/causal/__init__.py +5 -0
  6. vistaar/causal/effects.py +195 -0
  7. vistaar/conversion/__init__.py +6 -0
  8. vistaar/conversion/opportunities.py +37 -0
  9. vistaar/conversion/ranking.py +149 -0
  10. vistaar/core/__init__.py +6 -0
  11. vistaar/core/config.py +255 -0
  12. vistaar/core/data_validator.py +149 -0
  13. vistaar/core/engine.py +1017 -0
  14. vistaar/core/exceptions.py +27 -0
  15. vistaar/core/logging.py +25 -0
  16. vistaar/core/results.py +584 -0
  17. vistaar/customer/__init__.py +5 -0
  18. vistaar/customer/intelligence.py +115 -0
  19. vistaar/data/conversion_sample.csv +8013 -0
  20. vistaar/datasets.py +339 -0
  21. vistaar/discovery/__init__.py +9 -0
  22. vistaar/discovery/ask.py +208 -0
  23. vistaar/discovery/explore.py +134 -0
  24. vistaar/discovery/guidance.py +113 -0
  25. vistaar/discovery/insights.py +289 -0
  26. vistaar/discovery/interactions.py +152 -0
  27. vistaar/discovery/simpsons.py +174 -0
  28. vistaar/explainability/__init__.py +6 -0
  29. vistaar/explainability/feature_importance.py +246 -0
  30. vistaar/explainability/shap_engine.py +279 -0
  31. vistaar/funnel/__init__.py +5 -0
  32. vistaar/funnel/funnel.py +68 -0
  33. vistaar/monitoring/__init__.py +15 -0
  34. vistaar/monitoring/bundle.py +130 -0
  35. vistaar/monitoring/calibration.py +121 -0
  36. vistaar/monitoring/monitor.py +104 -0
  37. vistaar/predictive/__init__.py +5 -0
  38. vistaar/predictive/classification.py +466 -0
  39. vistaar/predictive/evaluation.py +57 -0
  40. vistaar/predictive/metrics.py +129 -0
  41. vistaar/predictive/prune.py +85 -0
  42. vistaar/predictive/reasons.py +98 -0
  43. vistaar/predictive/selection.py +238 -0
  44. vistaar/predictive/woe.py +84 -0
  45. vistaar/profiling/__init__.py +5 -0
  46. vistaar/profiling/diagnostics.py +129 -0
  47. vistaar/profiling/profiler.py +322 -0
  48. vistaar/py.typed +0 -0
  49. vistaar/registry.py +278 -0
  50. vistaar/reporting/__init__.py +6 -0
  51. vistaar/reporting/assets/hdfc_bank_logo.svg +37 -0
  52. vistaar/reporting/exporters.py +148 -0
  53. vistaar/reporting/html_report.py +481 -0
  54. vistaar/reporting/theme.py +112 -0
  55. vistaar/sampling/__init__.py +5 -0
  56. vistaar/sampling/stratified.py +351 -0
  57. vistaar/segmentation/__init__.py +5 -0
  58. vistaar/segmentation/clustering.py +277 -0
  59. vistaar/segmentation/micro_segments.py +589 -0
  60. vistaar/segmentation/portfolio.py +150 -0
  61. vistaar/segmentation/rule_discovery.py +185 -0
  62. vistaar/segmentation/subgroup.py +183 -0
  63. vistaar/spark/__init__.py +5 -0
  64. vistaar/spark/adapter.py +146 -0
  65. vistaar/statistics/__init__.py +28 -0
  66. vistaar/statistics/confidence_intervals.py +178 -0
  67. vistaar/statistics/lift.py +176 -0
  68. vistaar/statistics/significance.py +158 -0
  69. vistaar/targeting/__init__.py +12 -0
  70. vistaar/targeting/campaign.py +210 -0
  71. vistaar/targeting/decile_segments.py +136 -0
  72. vistaar/targeting/deciles.py +127 -0
  73. vistaar/targeting/profit.py +181 -0
  74. vistaar/timebased/__init__.py +5 -0
  75. vistaar/timebased/trends.py +60 -0
  76. vistaar/uplift/__init__.py +5 -0
  77. vistaar/uplift/models.py +295 -0
  78. vistaar/utils/__init__.py +1 -0
  79. vistaar/utils/helpers.py +172 -0
  80. vistaar/utils/lazy.py +29 -0
  81. vistaar/utils/progress.py +119 -0
  82. vistaar/version.py +3 -0
  83. vistaar/visualization/__init__.py +5 -0
  84. vistaar/visualization/dashboards.py +52 -0
  85. vistaar/visualization/plots.py +343 -0
  86. vistaar-0.3.1.dist-info/METADATA +237 -0
  87. vistaar-0.3.1.dist-info/RECORD +90 -0
  88. vistaar-0.3.1.dist-info/WHEEL +5 -0
  89. vistaar-0.3.1.dist-info/licenses/LICENSE +21 -0
  90. vistaar-0.3.1.dist-info/top_level.txt +1 -0
vistaar/__init__.py ADDED
@@ -0,0 +1,72 @@
1
+ """Automated conversion analytics: profiling, micro-segments, lift, and explanations.
2
+
3
+ The numbers are observational. Relative lift is a rate ratio against the
4
+ overall baseline. Significance tests compare a segment with its complement.
5
+ Neither is a causal effect. Scenario sizing is arithmetic, not a forecast.
6
+ """
7
+
8
+ from vistaar.core.config import Config
9
+ from vistaar.core.engine import Analytics
10
+ from vistaar.core.exceptions import (
11
+ ConfigurationError,
12
+ DataValidationError,
13
+ InsufficientDataError,
14
+ VistaarError,
15
+ VistaarWarning,
16
+ OptionalDependencyError,
17
+ )
18
+ from vistaar.core.logging import configure_logging
19
+ from vistaar.datasets import generate_campaign, generate_conversion, hillstrom_treatment, load_bank_marketing, load_conversion, load_hillstrom, load_telco
20
+ from vistaar.monitoring.bundle import load_model
21
+ from vistaar.registry import Registry
22
+ from vistaar.version import __version__
23
+
24
+ def set_theme(name: str = "vistaar") -> str:
25
+ """Apply a built-in palette to new Plotly figures and to library charts.
26
+
27
+ ``vistaar`` is navy, teal, and grey, with no logo. ``neutral`` is the same
28
+ palette. ``hdfc`` is an optional corporate theme.
29
+ """
30
+ from vistaar.reporting.theme import get_theme, register_plotly_templates
31
+ from vistaar.visualization.plots import _apply_theme
32
+
33
+ theme = get_theme(name)
34
+ register_plotly_templates(theme["name"])
35
+ _apply_theme(theme["name"])
36
+ return theme["name"]
37
+
38
+
39
+ def _register_default_theme() -> None:
40
+ """Register the vistaar Plotly template and make it the default."""
41
+ try:
42
+ from vistaar.reporting.theme import register_plotly_templates
43
+
44
+ register_plotly_templates("vistaar")
45
+ except Exception:
46
+ return
47
+
48
+
49
+ _register_default_theme()
50
+
51
+ __all__ = [
52
+ "Analytics",
53
+ "Config",
54
+ "ConfigurationError",
55
+ "DataValidationError",
56
+ "InsufficientDataError",
57
+ "VistaarError",
58
+ "VistaarWarning",
59
+ "OptionalDependencyError",
60
+ "configure_logging",
61
+ "generate_campaign",
62
+ "generate_conversion",
63
+ "load_bank_marketing",
64
+ "Registry",
65
+ "hillstrom_treatment",
66
+ "load_conversion",
67
+ "load_hillstrom",
68
+ "load_model",
69
+ "load_telco",
70
+ "set_theme",
71
+ "__version__",
72
+ ]
@@ -0,0 +1,6 @@
1
+ """Anomaly and drift screens."""
2
+
3
+ from vistaar.anomaly.anomaly import detect_anomalies
4
+ from vistaar.anomaly.drift import compare_populations, psi_categorical, psi_numeric
5
+
6
+ __all__ = ["compare_populations", "detect_anomalies", "psi_categorical", "psi_numeric"]
@@ -0,0 +1,58 @@
1
+ """Isolation Forest screen, followed by a conversion-rate test.
2
+
3
+ Outlier rows are an unsupervised screen. Whether their conversion rate differs
4
+ from the rest of the table is a separate, reported proportion test. A
5
+ non-significant test means the outliers are not a conversion-rate finding.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ from typing import Any
11
+
12
+ import numpy as np
13
+ import pandas as pd
14
+ from sklearn.ensemble import IsolationForest
15
+
16
+ from vistaar.statistics.lift import segment_contrast
17
+ from vistaar.core.config import Config
18
+
19
+
20
+ def detect_anomalies(
21
+ df: pd.DataFrame,
22
+ y: np.ndarray,
23
+ numeric: list[str],
24
+ config: Config,
25
+ ) -> dict[str, Any]:
26
+ if len(df) < 200 or len(numeric) < 2:
27
+ return {
28
+ "anomalies": pd.DataFrame(),
29
+ "notes": ["Anomaly screen skipped: need at least 200 rows and 2 numeric columns."],
30
+ }
31
+ use = numeric[:12]
32
+ matrix = df[use].apply(pd.to_numeric, errors="coerce")
33
+ matrix = matrix.fillna(matrix.median(numeric_only=True))
34
+ model = IsolationForest(
35
+ n_estimators=100,
36
+ contamination=0.03,
37
+ random_state=config.random_state,
38
+ n_jobs=config.n_jobs,
39
+ )
40
+ labels = model.fit_predict(matrix.to_numpy(dtype=float))
41
+ mask = labels == -1
42
+ contrast = segment_contrast(np.asarray(y), mask, config=config, compute_bayes=False)
43
+ row = {
44
+ "screen": "isolation_forest",
45
+ "contamination": 0.03,
46
+ "n_flagged": int(mask.sum()),
47
+ **contrast,
48
+ "interpretation": (
49
+ "Flagged rows are multivariate outliers on numeric columns. "
50
+ "The p-value tests whether their conversion rate differs from the complement. "
51
+ "It is not a claim that the rows are errors, and it is not causal."
52
+ ),
53
+ }
54
+ notes = [
55
+ "IsolationForest contamination is fixed at 3%, so about 3% of rows are flagged by construction.",
56
+ "Read the proportion test before treating the flags as a conversion problem. If it is not significant, the outliers do not convert differently.",
57
+ ]
58
+ return {"anomalies": pd.DataFrame([row]), "notes": notes, "mask": mask}
@@ -0,0 +1,157 @@
1
+ """Population stability (PSI) and Kolmogorov–Smirnov comparisons.
2
+
3
+ PSI uses quantile bins of the reference (expected) sample for numeric columns
4
+ and the shared level set for categorical columns. Empty bins are floored at
5
+ 1e-4 and renormalised, which is the usual PSI convention. Rules of thumb —
6
+ PSI < 0.1 stable, 0.1–0.25 moderate, > 0.25 large — are labels, not tests.
7
+ The KS p-value is the two-sample test and is a better numeric significance
8
+ statement than the PSI band.
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ from typing import Any
14
+
15
+ import numpy as np
16
+ import pandas as pd
17
+ from scipy import stats
18
+
19
+ from vistaar.statistics.significance import choose_proportion_test
20
+
21
+
22
+ def psi_numeric(expected: np.ndarray, actual: np.ndarray, bins: int = 10, eps: float = 1e-4) -> float:
23
+ expected = np.asarray(expected, dtype=float)
24
+ actual = np.asarray(actual, dtype=float)
25
+ expected = expected[np.isfinite(expected)]
26
+ actual = actual[np.isfinite(actual)]
27
+ if expected.size < bins or actual.size < 5:
28
+ return float("nan")
29
+ edges = np.unique(np.quantile(expected, np.linspace(0, 1, bins + 1))).astype(float)
30
+ if edges.size < 3:
31
+ return float("nan")
32
+ # Open the end bins so a shift past the reference range is counted, not dropped.
33
+ edges[0] = -np.inf
34
+ edges[-1] = np.inf
35
+ expected_pct = np.histogram(expected, bins=edges)[0].astype(float)
36
+ actual_pct = np.histogram(actual, bins=edges)[0].astype(float)
37
+ return _psi_from_counts(expected_pct, actual_pct, eps)
38
+
39
+
40
+ def psi_categorical(expected: pd.Series, actual: pd.Series, eps: float = 1e-4) -> float:
41
+ expected_counts = expected.astype("object").where(expected.notna(), "(missing)").astype(str).value_counts()
42
+ actual_counts = actual.astype("object").where(actual.notna(), "(missing)").astype(str).value_counts()
43
+ levels = sorted(set(expected_counts.index) | set(actual_counts.index))
44
+ if len(levels) < 2:
45
+ return float("nan")
46
+ e = np.array([float(expected_counts.get(level, 0.0)) for level in levels])
47
+ a = np.array([float(actual_counts.get(level, 0.0)) for level in levels])
48
+ return _psi_from_counts(e, a, eps)
49
+
50
+
51
+ def _psi_from_counts(expected_counts: np.ndarray, actual_counts: np.ndarray, eps: float) -> float:
52
+ if expected_counts.sum() <= 0 or actual_counts.sum() <= 0:
53
+ return float("nan")
54
+ expected_pct = expected_counts / expected_counts.sum()
55
+ actual_pct = actual_counts / actual_counts.sum()
56
+ expected_pct = np.clip(expected_pct, eps, None)
57
+ actual_pct = np.clip(actual_pct, eps, None)
58
+ expected_pct = expected_pct / expected_pct.sum()
59
+ actual_pct = actual_pct / actual_pct.sum()
60
+ return float(np.sum((actual_pct - expected_pct) * np.log(actual_pct / expected_pct)))
61
+
62
+
63
+ def psi_band(value: float) -> str:
64
+ if not np.isfinite(value):
65
+ return "undefined"
66
+ if value < 0.10:
67
+ return "stable"
68
+ if value < 0.25:
69
+ return "moderate_shift"
70
+ return "large_shift"
71
+
72
+
73
+ def compare_populations(
74
+ reference: pd.DataFrame,
75
+ actual: pd.DataFrame,
76
+ *,
77
+ target: str | None = None,
78
+ max_columns: int = 30,
79
+ ) -> dict[str, Any]:
80
+ """Compare two tables column by column. The first table is the PSI reference."""
81
+ shared = [c for c in reference.columns if c in actual.columns and c != target][:max_columns]
82
+ rows = []
83
+ for column in shared:
84
+ left = reference[column]
85
+ right = actual[column]
86
+ if pd.api.types.is_numeric_dtype(left) and pd.api.types.is_numeric_dtype(right):
87
+ psi = psi_numeric(left.to_numpy(dtype=float), right.to_numpy(dtype=float))
88
+ left_v = pd.to_numeric(left, errors="coerce").dropna().to_numpy()
89
+ right_v = pd.to_numeric(right, errors="coerce").dropna().to_numpy()
90
+ if left_v.size >= 5 and right_v.size >= 5:
91
+ ks = stats.ks_2samp(left_v, right_v, method="auto")
92
+ ks_stat, ks_p = float(ks.statistic), float(ks.pvalue)
93
+ else:
94
+ ks_stat, ks_p = float("nan"), float("nan")
95
+ rows.append(
96
+ {
97
+ "column": column,
98
+ "type": "numeric",
99
+ "psi": psi,
100
+ "psi_band": psi_band(psi),
101
+ "ks_statistic": ks_stat,
102
+ "ks_p_value": ks_p,
103
+ }
104
+ )
105
+ else:
106
+ psi = psi_categorical(left, right)
107
+ rows.append(
108
+ {
109
+ "column": column,
110
+ "type": "categorical",
111
+ "psi": psi,
112
+ "psi_band": psi_band(psi),
113
+ "ks_statistic": float("nan"),
114
+ "ks_p_value": float("nan"),
115
+ }
116
+ )
117
+ target_row: dict[str, Any] | None = None
118
+ if target and target in reference.columns and target in actual.columns:
119
+ y0 = _binary(reference[target])
120
+ y1 = _binary(actual[target])
121
+ if y0 is not None and y1 is not None:
122
+ test = choose_proportion_test(int(y0.sum()), int(len(y0)), int(y1.sum()), int(len(y1)))
123
+ target_row = {
124
+ "reference_rate": float(y0.mean()) if len(y0) else float("nan"),
125
+ "comparison_rate": float(y1.mean()) if len(y1) else float("nan"),
126
+ "reference_n": int(len(y0)),
127
+ "comparison_n": int(len(y1)),
128
+ **test,
129
+ "note": "Rate test compares the two tables. It is not a test that the populations differ only because of drift in features.",
130
+ }
131
+ table = pd.DataFrame(rows)
132
+ if not table.empty:
133
+ table = table.sort_values("psi", ascending=False).reset_index(drop=True)
134
+ return {
135
+ "drift": table,
136
+ "target_comparison": target_row,
137
+ "notes": [
138
+ "PSI bins for numeric columns are the reference sample's quantiles.",
139
+ "Bands: <0.1 stable, 0.1–0.25 moderate, >0.25 large. These are conventions, not hypothesis tests.",
140
+ "KS p-values are two-sample tests on numeric columns and are not multiplicity-adjusted.",
141
+ ],
142
+ }
143
+
144
+
145
+ def _binary(series: pd.Series) -> np.ndarray | None:
146
+ if series.dropna().nunique() != 2:
147
+ return None
148
+ if pd.api.types.is_bool_dtype(series):
149
+ return series.dropna().astype(int).to_numpy()
150
+ if pd.api.types.is_numeric_dtype(series):
151
+ values = series.dropna()
152
+ positive = values.max()
153
+ return (values == positive).astype(int).to_numpy()
154
+ text = series.dropna().astype(str).str.strip().str.lower()
155
+ if set(text.unique()) <= {"0", "1", "true", "false", "yes", "no"}:
156
+ return text.isin({"1", "true", "yes"}).astype(int).to_numpy()
157
+ return None
@@ -0,0 +1,5 @@
1
+ """Observational treatment-effect estimates with explicit assumptions."""
2
+
3
+ from vistaar.causal.effects import ASSUMPTIONS, estimate_effects
4
+
5
+ __all__ = ["ASSUMPTIONS", "estimate_effects"]
@@ -0,0 +1,195 @@
1
+ """Propensity scores, 1:1 matching, and a cross-fit T-learner.
2
+
3
+ These estimators are reported only with their assumptions. Unconfoundedness
4
+ is not testable from the table. The matching standard error is the paired
5
+ difference SE and does not include uncertainty from fitting the propensity
6
+ model. The T-learner uplift is predictive heterogeneity under the same
7
+ assumptions; decile gaps are observed outcome differences, and they remain
8
+ confounded if the assumptions fail.
9
+
10
+ Nothing in this module turns an observational contrast into an experiment.
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ from typing import Any
16
+
17
+ import numpy as np
18
+ import pandas as pd
19
+ from sklearn.compose import ColumnTransformer
20
+ from sklearn.impute import SimpleImputer
21
+ from sklearn.linear_model import LogisticRegression
22
+ from sklearn.model_selection import KFold
23
+ from sklearn.pipeline import Pipeline
24
+ from sklearn.preprocessing import OneHotEncoder, StandardScaler
25
+
26
+ ASSUMPTIONS = [
27
+ "Unconfoundedness: treatment is independent of the potential outcomes given the covariates in the model. This cannot be verified from the table.",
28
+ "Overlap: every row needs a positive probability of both treatment and control. The overlap share below is a check, not a proof.",
29
+ "SUTVA: one row's treatment does not change another row's outcome, and there is one version of treatment.",
30
+ "The propensity model is a main-effects logistic regression. Misspecification biases the score.",
31
+ "The matching standard error is the standard error of the paired outcome difference. It ignores uncertainty from estimating the propensity scores.",
32
+ "The T-learner is cross-fit so each row's uplift is predicted from other folds, but it still relies on unconfoundedness.",
33
+ "These quantities are not a substitute for a randomized experiment.",
34
+ ]
35
+
36
+
37
+ def _design(numeric: list[str], categorical: list[str]) -> ColumnTransformer:
38
+ transformers = []
39
+ if numeric:
40
+ transformers.append(("num", Pipeline([("impute", SimpleImputer(strategy="median")), ("scale", StandardScaler())]), numeric))
41
+ if categorical:
42
+ transformers.append(
43
+ (
44
+ "cat",
45
+ Pipeline(
46
+ [
47
+ ("impute", SimpleImputer(strategy="most_frequent")),
48
+ ("oh", OneHotEncoder(handle_unknown="ignore", sparse_output=False)),
49
+ ]
50
+ ),
51
+ categorical,
52
+ )
53
+ )
54
+ return ColumnTransformer(transformers)
55
+
56
+
57
+ def estimate_effects(
58
+ df: pd.DataFrame,
59
+ y: np.ndarray,
60
+ treatment: np.ndarray,
61
+ numeric: list[str],
62
+ categorical: list[str],
63
+ *,
64
+ random_state: int,
65
+ ) -> dict[str, Any]:
66
+ y = np.asarray(y, dtype=float)
67
+ t = np.asarray(treatment, dtype=int)
68
+ if np.unique(t).size != 2 or not set(np.unique(t)).issubset({0, 1}):
69
+ raise ValueError("Treatment must be coded 0/1.")
70
+ columns = numeric + categorical
71
+ frame = df[columns].copy()
72
+ for column in categorical:
73
+ frame[column] = frame[column].astype("object").where(frame[column].notna(), "(missing)").astype(str)
74
+ pipe = Pipeline(
75
+ [
76
+ ("pre", _design(numeric, categorical)),
77
+ ("model", LogisticRegression(max_iter=500, solver="lbfgs", random_state=random_state)),
78
+ ]
79
+ )
80
+ pipe.fit(frame, t)
81
+ propensity = pipe.predict_proba(frame)[:, 1]
82
+ propensity = np.clip(propensity, 1e-6, 1 - 1e-6)
83
+ overlap = (propensity >= 0.05) & (propensity <= 0.95)
84
+ logit = np.log(propensity / (1 - propensity))
85
+ caliper = 0.2 * float(np.std(logit))
86
+ treated = np.flatnonzero(t == 1)
87
+ control = np.flatnonzero(t == 0)
88
+ rng = np.random.default_rng(random_state)
89
+ order = rng.permutation(treated)
90
+ available = set(control.tolist())
91
+ pairs: list[tuple[int, int]] = []
92
+ control_logit = {int(i): float(logit[i]) for i in control}
93
+ for idx in order:
94
+ if not available:
95
+ break
96
+ # Nearest remaining control on the logit propensity, inside the caliper.
97
+ target = float(logit[idx])
98
+ best_j = None
99
+ best_dist = None
100
+ for j in available:
101
+ dist = abs(control_logit[j] - target)
102
+ if dist <= caliper and (best_dist is None or dist < best_dist):
103
+ best_dist = dist
104
+ best_j = j
105
+ if best_j is not None:
106
+ pairs.append((int(idx), int(best_j)))
107
+ available.remove(best_j)
108
+ if pairs:
109
+ diffs = np.array([y[i] - y[j] for i, j in pairs], dtype=float)
110
+ att = float(diffs.mean())
111
+ se = float(diffs.std(ddof=1) / np.sqrt(len(diffs))) if len(diffs) > 1 else float("nan")
112
+ z = 1.959963984540054
113
+ ci = (att - z * se, att + z * se) if np.isfinite(se) else (float("nan"), float("nan"))
114
+ else:
115
+ att, se, ci = float("nan"), float("nan"), (float("nan"), float("nan"))
116
+ naive = float(y[t == 1].mean() - y[t == 0].mean())
117
+ uplift = _t_learner(frame, y, t, numeric, categorical, random_state)
118
+ return {
119
+ "assumptions": ASSUMPTIONS,
120
+ "estimate_type": "conditional_association_under_stated_assumptions",
121
+ "causal_claim": False,
122
+ "n_treated": int((t == 1).sum()),
123
+ "n_control": int((t == 0).sum()),
124
+ "overlap_share": float(overlap.mean()),
125
+ "overlap_adequate": bool(overlap.mean() >= 0.5),
126
+ "propensity_min": float(propensity.min()),
127
+ "propensity_max": float(propensity.max()),
128
+ "caliper_logit": caliper,
129
+ "n_matched_pairs": len(pairs),
130
+ "matching_att": att,
131
+ "matching_se_paired": se,
132
+ "matching_ci95_low": ci[0],
133
+ "matching_ci95_high": ci[1],
134
+ "naive_difference": naive,
135
+ "naive_difference_label": "unadjusted mean difference, confounded if treatment was not randomized",
136
+ "uplift_deciles": uplift,
137
+ "notes": [
138
+ "matching_att is the mean outcome difference inside 1:1 caliper matches on the logit propensity score, without replacement.",
139
+ "Compare it with naive_difference to see how much of the raw gap the matched covariates absorb. Neither number is an experimental effect unless the assumptions hold.",
140
+ ],
141
+ }
142
+
143
+
144
+ def _t_learner(
145
+ frame: pd.DataFrame,
146
+ y: np.ndarray,
147
+ t: np.ndarray,
148
+ numeric: list[str],
149
+ categorical: list[str],
150
+ random_state: int,
151
+ ) -> pd.DataFrame:
152
+ """Two-fold cross-fit T-learner. Uplift = mu1 - mu0 predicted out of fold."""
153
+ mu1 = np.full(len(y), np.nan)
154
+ mu0 = np.full(len(y), np.nan)
155
+ splitter = KFold(n_splits=2, shuffle=True, random_state=random_state)
156
+ for train_idx, test_idx in splitter.split(frame):
157
+ for label, store in ((1, mu1), (0, mu0)):
158
+ in_arm = train_idx[t[train_idx] == label]
159
+ if len(in_arm) < 20 or np.unique(y[in_arm]).size < 2:
160
+ continue
161
+ pipe = Pipeline(
162
+ [
163
+ ("pre", _design(numeric, categorical)),
164
+ ("model", LogisticRegression(max_iter=400, solver="lbfgs", random_state=random_state)),
165
+ ]
166
+ )
167
+ pipe.fit(frame.iloc[in_arm], y[in_arm])
168
+ store[test_idx] = pipe.predict_proba(frame.iloc[test_idx])[:, 1]
169
+ uplift = mu1 - mu0
170
+ valid = np.isfinite(uplift)
171
+ if valid.sum() < 50:
172
+ return pd.DataFrame()
173
+ frame_u = pd.DataFrame({"uplift": uplift[valid], "y": y[valid], "t": t[valid]})
174
+ try:
175
+ frame_u["bin"] = pd.qcut(frame_u["uplift"], q=5, duplicates="drop")
176
+ except ValueError:
177
+ return pd.DataFrame()
178
+ rows = []
179
+ for interval, group in frame_u.groupby("bin", observed=True):
180
+ treated = group.loc[group["t"] == 1, "y"]
181
+ control = group.loc[group["t"] == 0, "y"]
182
+ rows.append(
183
+ {
184
+ "predicted_uplift_bin": str(interval),
185
+ "n": int(len(group)),
186
+ "n_treated": int(len(treated)),
187
+ "n_control": int(len(control)),
188
+ "mean_predicted_uplift": float(group["uplift"].mean()),
189
+ "observed_rate_treated": float(treated.mean()) if len(treated) else float("nan"),
190
+ "observed_rate_control": float(control.mean()) if len(control) else float("nan"),
191
+ "observed_difference": float(treated.mean() - control.mean()) if len(treated) and len(control) else float("nan"),
192
+ "label": "observed outcome difference inside a predicted-uplift bin; still depends on the causal assumptions",
193
+ }
194
+ )
195
+ return pd.DataFrame(rows)
@@ -0,0 +1,6 @@
1
+ """Conversion opportunity ranking."""
2
+
3
+ from vistaar.conversion.opportunities import build_opportunities
4
+ from vistaar.conversion.ranking import scenario_shift
5
+
6
+ __all__ = ["build_opportunities", "scenario_shift"]
@@ -0,0 +1,37 @@
1
+ """Rank segments by the documented opportunity score."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import pandas as pd
6
+
7
+ from vistaar.conversion.ranking import opportunity_methodology, score_opportunities
8
+ from vistaar.core.config import Config
9
+
10
+
11
+ def build_opportunities(segments: pd.DataFrame, config: Config, value_column: str | None) -> dict:
12
+ with_revenue = bool(value_column) and not segments.empty and "mean_value" in segments.columns and segments["mean_value"].notna().any()
13
+ weights = config.weights(with_revenue=with_revenue)
14
+ frame = score_opportunities(
15
+ segments,
16
+ weights,
17
+ with_revenue=with_revenue,
18
+ higher_is_better=bool(config.higher_is_better) if config.higher_is_better is not None else True,
19
+ )
20
+ return {
21
+ "opportunities": frame,
22
+ "methodology": opportunity_methodology(weights, with_revenue),
23
+ "weights": weights,
24
+ "value_column": value_column if with_revenue else None,
25
+ "notes": [
26
+ "Observed excess events compare the segment rate with the overall baseline. They are not incremental causal effects.",
27
+ "Scenario counts describe a hypothetical move to the baseline rate. They are not a forecast.",
28
+ *(
29
+ [
30
+ "This target is an adverse event. reduce_risk marks segments above the baseline. "
31
+ "scenario_events_avoided_to_baseline is the event count if that rate fell to the baseline."
32
+ ]
33
+ if config.higher_is_better is False
34
+ else []
35
+ ),
36
+ ],
37
+ }