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.
- vistaar/__init__.py +72 -0
- vistaar/anomaly/__init__.py +6 -0
- vistaar/anomaly/anomaly.py +58 -0
- vistaar/anomaly/drift.py +157 -0
- vistaar/causal/__init__.py +5 -0
- vistaar/causal/effects.py +195 -0
- vistaar/conversion/__init__.py +6 -0
- vistaar/conversion/opportunities.py +37 -0
- vistaar/conversion/ranking.py +149 -0
- vistaar/core/__init__.py +6 -0
- vistaar/core/config.py +255 -0
- vistaar/core/data_validator.py +149 -0
- vistaar/core/engine.py +1017 -0
- vistaar/core/exceptions.py +27 -0
- vistaar/core/logging.py +25 -0
- vistaar/core/results.py +584 -0
- vistaar/customer/__init__.py +5 -0
- vistaar/customer/intelligence.py +115 -0
- vistaar/data/conversion_sample.csv +8013 -0
- vistaar/datasets.py +339 -0
- vistaar/discovery/__init__.py +9 -0
- vistaar/discovery/ask.py +208 -0
- vistaar/discovery/explore.py +134 -0
- vistaar/discovery/guidance.py +113 -0
- vistaar/discovery/insights.py +289 -0
- vistaar/discovery/interactions.py +152 -0
- vistaar/discovery/simpsons.py +174 -0
- vistaar/explainability/__init__.py +6 -0
- vistaar/explainability/feature_importance.py +246 -0
- vistaar/explainability/shap_engine.py +279 -0
- vistaar/funnel/__init__.py +5 -0
- vistaar/funnel/funnel.py +68 -0
- vistaar/monitoring/__init__.py +15 -0
- vistaar/monitoring/bundle.py +130 -0
- vistaar/monitoring/calibration.py +121 -0
- vistaar/monitoring/monitor.py +104 -0
- vistaar/predictive/__init__.py +5 -0
- vistaar/predictive/classification.py +466 -0
- vistaar/predictive/evaluation.py +57 -0
- vistaar/predictive/metrics.py +129 -0
- vistaar/predictive/prune.py +85 -0
- vistaar/predictive/reasons.py +98 -0
- vistaar/predictive/selection.py +238 -0
- vistaar/predictive/woe.py +84 -0
- vistaar/profiling/__init__.py +5 -0
- vistaar/profiling/diagnostics.py +129 -0
- vistaar/profiling/profiler.py +322 -0
- vistaar/py.typed +0 -0
- vistaar/registry.py +278 -0
- vistaar/reporting/__init__.py +6 -0
- vistaar/reporting/assets/hdfc_bank_logo.svg +37 -0
- vistaar/reporting/exporters.py +148 -0
- vistaar/reporting/html_report.py +481 -0
- vistaar/reporting/theme.py +112 -0
- vistaar/sampling/__init__.py +5 -0
- vistaar/sampling/stratified.py +351 -0
- vistaar/segmentation/__init__.py +5 -0
- vistaar/segmentation/clustering.py +277 -0
- vistaar/segmentation/micro_segments.py +589 -0
- vistaar/segmentation/portfolio.py +150 -0
- vistaar/segmentation/rule_discovery.py +185 -0
- vistaar/segmentation/subgroup.py +183 -0
- vistaar/spark/__init__.py +5 -0
- vistaar/spark/adapter.py +146 -0
- vistaar/statistics/__init__.py +28 -0
- vistaar/statistics/confidence_intervals.py +178 -0
- vistaar/statistics/lift.py +176 -0
- vistaar/statistics/significance.py +158 -0
- vistaar/targeting/__init__.py +12 -0
- vistaar/targeting/campaign.py +210 -0
- vistaar/targeting/decile_segments.py +136 -0
- vistaar/targeting/deciles.py +127 -0
- vistaar/targeting/profit.py +181 -0
- vistaar/timebased/__init__.py +5 -0
- vistaar/timebased/trends.py +60 -0
- vistaar/uplift/__init__.py +5 -0
- vistaar/uplift/models.py +295 -0
- vistaar/utils/__init__.py +1 -0
- vistaar/utils/helpers.py +172 -0
- vistaar/utils/lazy.py +29 -0
- vistaar/utils/progress.py +119 -0
- vistaar/version.py +3 -0
- vistaar/visualization/__init__.py +5 -0
- vistaar/visualization/dashboards.py +52 -0
- vistaar/visualization/plots.py +343 -0
- vistaar-0.3.1.dist-info/METADATA +237 -0
- vistaar-0.3.1.dist-info/RECORD +90 -0
- vistaar-0.3.1.dist-info/WHEEL +5 -0
- vistaar-0.3.1.dist-info/licenses/LICENSE +21 -0
- 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,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}
|
vistaar/anomaly/drift.py
ADDED
|
@@ -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,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,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
|
+
}
|