causal-insights

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Causal Insight Analysis for

doubleml-pipeline

Outputs

doubleml-pipeline

输出的因果洞察分析

The pipeline has already estimated debiased causal effects with Double Machine Learning (DML). Read the completed

output_dir

files directly using the exact metric definitions in references/metric_formulas.md — never refit raw regressions on the input panel.

Adapt to the run's schema (
metadata.json
first): Treatments, channels, interventions, outcome KPIs, entity dimensions (

geo_col

item_col

), and covariates vary across users and domains (including non-monetary treatments with no spend column). Derive every lever name, unit type, segment label, and driver strictly from

metadata.json

and the columns present in

consolidated_1a_full_df.csv

— never assume specific channels, treatments, or domain constructs that are not in the data. When a question cannot be answered from the run's outputs, say so explicitly and name the exact pipeline setting (

treatment_cols

x_cols_list

covariates_for_cate_list

geo_col

item_col

optimize=True

, or

run_sensitivity=True

) needed to answer it.

该流水线已使用 Double Machine Learning (DML) 估计经过去偏的因果效应。直接读取已完成的

output_dir

文件，并严格采用 references/metric_formulas.md 中的精确指标定义——绝不要在输入面板数据上重新拟合原始回归模型。

根据本次运行的 schema 调整（先读取
metadata.json
）：处理项、渠道、干预措施、结果 KPI、实体维度（

geo_col

、

item_col

）和协变量会因用户和领域而异（包括没有支出列的非货币型处理项）。所有杠杆名称、单位类型、分群标签和驱动因素都必须严格根据

metadata.json

以及

consolidated_1a_full_df.csv

中存在的列推导——绝不能假设数据中不存在的特定渠道、处理项或领域构念。如果无法从本次运行的输出中回答某个问题，应明确说明，并指出回答该问题所需的确切 pipeline 设置（

treatment_cols

、

x_cols_list

、

covariates_for_cate_list

、

geo_col

item_col

、

optimize=True

或

run_sensitivity=True

）。

Output Directory Reading Order

输出目录读取顺序


outcome_col
estimated_incremental_KPI_<d>
model == "median"
total_estimated_incremental_KPI
robustness_value
decision
optimization_metrics.csv

Step	File in `<output_dir>`	What to extract
1	`metadata.json`	`outcome_col` , `treatment_cols` , `treatment_types` , `treatment_spend_cols` , `x_cols_list` , `covariates_for_cate_list` , `geo_col` , `item_col` , `date_col` , `opt_threshold_roi` ( `threshold_roi` ), `saturation_family` , `saturation_phase0` , `phase4_optimization` , `cluster_dml` .
2	`step4_consolidated_results/consolidated_1a_full_df.csv`	Row-level panel + `estimated_incremental_KPI_<d>` , `_2.5%` , `_97.5%` , `roi_amount_based_<d>` , and (saturation optimizer only) `optimized_<d>_spend` / `optimized_incremental_KPI_<d>` . Aggregate all overall, segment, calendar, and driver slices from this table.
3	`step4_consolidated_results/graph/004_cate/cate_coef_dict_pooling.csv`	Pooled `model == "median"` row `cate_pvalue_dict` for Bonferroni-adjusted heterogeneity grades ( `strong` , `weak` , `none` ).
4	`step4_consolidated_results/consolidated_3a_detail.csv`	Phase 3 repetition stability ( `total_estimated_incremental_KPI` sign consistency and CV across `n_reps` ).
5	`step4_consolidated_results/graph/006_sensitivity/sensitivity_metrics.csv`	OVB `robustness_value` vs. `benchmark_covariate` ( `benchmark_cf_d` , `benchmark_cf_y` ).
6	`step0_saturation/summary_alpha_selection.json` & `diag6_t_ref_consistency.csv`	Phase 0 `decision` ( `saturation` vs. `linear` ), `decision_reason` ( `1se_pass` , `1se_fail` , `grid_edge_upper` ), `selected_family` , `alpha_hat` , `half_saturation_T` , `T_ref` , `d_bar` , `se` , `diag1_fired` , `diag2_fired` , `r_T` , `messages` . (Per-treatment subdirs when `len(treatment_cols) > 1` .)
7	`step4_consolidated_results/graph/007_optimization/` or `roi_output/<d>/007_optimization/`	`optimization_metrics.csv` and `optimization_yearly_summary.csv` ( `spend` treatments use `graph/007_optimization/` ; non- `spend` treatments with spend mapping use `roi_output/<d>/007_optimization/` ).


outcome_col
estimated_incremental_KPI_<d>
model == "median"
total_estimated_incremental_KPI
robustness_value
decision
optimization_metrics.csv

步骤	`<output_dir>` 中的文件	要提取的内容
1	`metadata.json`	`outcome_col` 、 `treatment_cols` 、 `treatment_types` 、 `treatment_spend_cols` 、 `x_cols_list` 、 `covariates_for_cate_list` 、 `geo_col` 、 `item_col` 、 `date_col` 、 `opt_threshold_roi` （ `threshold_roi` ）、 `saturation_family` 、 `saturation_phase0` 、 `phase4_optimization` 、 `cluster_dml` 。
2	`step4_consolidated_results/consolidated_1a_full_df.csv`	行级面板数据，以及 `estimated_incremental_KPI_<d>` 、 `_2.5%` 、 `_97.5%` 、 `roi_amount_based_<d>` ，和（仅限 saturation optimizer） `optimized_<d>_spend` / `optimized_incremental_KPI_<d>` 。从该表汇总所有整体、分群、日历和驱动因素切片。
3	`step4_consolidated_results/graph/004_cate/cate_coef_dict_pooling.csv`	池化后的 `model == "median"` 行中的 `cate_pvalue_dict` ，用于确定经过 Bonferroni 校正的异质性等级（ `strong` 、 `weak` 、 `none` ）。
4	`step4_consolidated_results/consolidated_3a_detail.csv`	Phase 3 重复稳定性（ `total_estimated_incremental_KPI` 的符号一致性，以及跨 `n_reps` 的 CV）。
5	`step4_consolidated_results/graph/006_sensitivity/sensitivity_metrics.csv`	OVB `robustness_value` 与 `benchmark_covariate` （ `benchmark_cf_d` 、 `benchmark_cf_y` ）的对照关系。
6	`step0_saturation/summary_alpha_selection.json` 与 `diag6_t_ref_consistency.csv`	Phase 0 `decision` （ `saturation` 或 `linear` ）、 `decision_reason` （ `1se_pass` 、 `1se_fail` 、 `grid_edge_upper` ）、 `selected_family` 、 `alpha_hat` 、 `half_saturation_T` 、 `T_ref` 、 `d_bar` 、 `se` 、 `diag1_fired` 、 `diag2_fired` 、 `r_T` 、 `messages` 。当 `len(treatment_cols) > 1` 时，还需读取各处理项的子目录。
7	`step4_consolidated_results/graph/007_optimization/` 或 `roi_output/<d>/007_optimization/`	`optimization_metrics.csv` 和 `optimization_yearly_summary.csv` （ `spend` 处理项使用 `graph/007_optimization/` ；具有支出映射的非 `spend` 处理项使用 `roi_output/<d>/007_optimization/` ）。

Four Non-Negotiable Calculation Rules

四条不可违背的计算规则

Always apply the formulas in references/metric_formulas.md to avoid silent calculation errors:

Order row-level 95% bounds before summing:
```
estimated_incremental_KPI_<d>_2.5%
```
and
```
_97.5%
```
are
```
(T - zero_point) * bound
```
, so they swap order whenever
```
T < zero_point
```
. Always compute
```
np.minimum(c25, c975).sum()
```
and
```
np.maximum(c25, c975).sum()
```
. Compute
```
effect_per_unit
```
(and its ordered 95% interval) by dividing by
```
T.sum()
```
, leaving it unset if a slice mixes positive and negative treatment values.
Divide by monetary spend for ROI (
treatment_spend_cols
): In
```
consolidated_3b_summary*.csv
```
,
```
total_estimated_roi
```
is
```
incremental_kpi / total_input
```
(effect per raw unit of treatment
```
<d>
```
, NOT monetary ROI when
```
treatment_types[d]
```
is
```
percentage
```
,
```
price
```
,
```
impressions
```
, or another non-spend unit). Always compute monetary ROI from
```
consolidated_1a_full_df.csv
```
by dividing
```
incremental_kpi
```
(and its ordered 95% bounds) by
```
df[treatment_spend_cols[d]].sum()
```
when spend is mapped (otherwise report
```
effect_per_unit
```
and its 95% interval). Compare
```
[roi_low, roi_high]
```
against
```
opt_threshold_roi
```
:
```
roi_high < threshold_roi
```
->
```
not_worth_investing
```
;
```
roi_low > threshold_roi
```
->
```
worth_investing
```
; straddling ->
```
undetermined
```
(omit verdict if
```
opt_threshold_roi
```
is
```
null
```
or no spend column exists). A
```
price
```
treatment is estimated as a gap
```
benchmark price - price
```
(its column is named
```
<price>_gap
```
;
```
metadata["price_benchmarks"][d]
```
gives the benchmark, the benchmark column and the investment column), so
```
effect_per_unit
```
is "incremental KPI per currency unit of price cut", rows with a zero gap were sold at the benchmark price, and a negative gap (price above the benchmark) counts as zero investment.
Grade CATE heterogeneity from the
median
row with Bonferroni scaling: In
```
cate_coef_dict_pooling.csv
```
(
```
model == "median"
```
), match all basis p-values for covariate
```
c
```
(
```
<c>_pvalue
```
,
```
bs(<c>, ...)
```
,
```
C(<c>)...
```
), compute
```
p_adj = min(1.0, min(ps) * len(ps))
```
, and classify
```
< 0.05
```
as
```
strong (p=...)
```
,
```
< 0.10
```
as
```
weak (p=...)
```
, and
```
>= 0.10
```
as
```
none (p=...)
```
(quoting
```
p<0.001
```
below
```
0.001
```
). Pooled BLP p-values ignore first-stage estimation error, so treat them as an approximate grade rather than a formal hypothesis test.
Exclude synthetic ground truth and derived cluster columns: Never read, profile, or report
```
TrueContrib_*
```
,
```
total_ground_truth_KPI
```
,
```
true_incremental_KPI_*
```
,
```
ground_truth_*
```
,
```
true_total_roi
```
,
```
SMAPE
```
,
```
R_squared
```
,
```
MAE
```
,
```
RMSE
```
, or
```
metadata["ground_truth_metrics"]
```
unless the user explicitly asks to audit synthetic recovery. Exclude
```
cluster_dml.derived_columns
```
(
```
cluster_date_block
```
) from driver analyses.

Allowed manual arithmetic & multi-run rule: Break-even gross margin

1 / roi_on_spend

when

outcome_col

represents gross revenue, and rescaling

effect_per_unit

to natural units (e.g., dividing by

when

treatment_types[d] == "percentage"

stored on

[0, 1]

to report per 1 percentage point). Never invent margins or benchmarks (ask the user instead), and never extrapolate outside observed support. Across multiple

output_dir

runs estimated separately, compare side by side only when

outcome_col

matches, and never sum

incremental_kpi

across runs. Speak in plain domain terms matching the user's column semantics and language without leaking internal schema keys.

始终应用 references/metric_formulas.md 中的公式，避免无声的计算错误：

对行级 95% 上下界排序后再求和：
```
estimated_incremental_KPI_<d>_2.5%
```
和
```
_97.5%
```
为
```
(T - zero_point) * bound
```
，因此当
```
T < zero_point
```
时上下界会互换。始终使用
```
np.minimum(c25, c975).sum()
```
和
```
np.maximum(c25, c975).sum()
```
计算。通过除以
```
T.sum()
```
得到
```
effect_per_unit
```
及其排序后的 95% 区间；如果某个切片同时包含正值和负值处理量，则不设置该值。
计算 ROI 时除以货币支出（
treatment_spend_cols
）：在
```
consolidated_3b_summary*.csv
```
中，
```
total_estimated_roi
```
为
```
incremental_kpi / total_input
```
，表示处理
```
<d>
```
每个原始单位的效应；当
```
treatment_types[d]
```
为
```
percentage
```
、
```
price
```
、
```
impressions
```
或其他非
```
spend
```
单位时，它并非货币 ROI。只要存在支出映射，始终应从
```
consolidated_1a_full_df.csv
```
中将
```
incremental_kpi
```
（及其排序后的 95% 上下界）除以
```
df[treatment_spend_cols[d]].sum()
```
来计算货币 ROI；否则应报告
```
effect_per_unit
```
及其 95% 区间。将
```
[roi_low, roi_high]
```
与
```
opt_threshold_roi
```
比较：
```
roi_high < threshold_roi
```
->
```
not_worth_investing
```
；
```
roi_low > threshold_roi
```
->
```
worth_investing
```
；区间跨越阈值 ->
```
undetermined
```
。如果
```
opt_threshold_roi
```
为
```
null
```
或不存在支出列，则省略判定。
```
price
```
处理项以差距
```
benchmark price - price
```
进行估计（其列名为
```
<price>_gap
```
；
```
metadata["price_benchmarks"][d]
```
提供基准值、基准列和投资列），因此
```
effect_per_unit
```
表示“每削减一货币单位价格带来的增量 KPI”；差距为零的行表示按基准价格售出，负差距（价格高于基准）计为零投资。
使用经过 Bonferroni 缩放的
median
行对 CATE 异质性进行分级：在
```
cate_coef_dict_pooling.csv
```
（
```
model == "median"
```
）中，匹配协变量
```
c
```
的所有基函数 p 值（
```
<c>_pvalue
```
、
```
bs(<c>, ...)
```
、
```
C(<c>)...
```
），计算
```
p_adj = min(1.0, min(ps) * len(ps))
```
，并将其分类为
```
< 0.05
```
->
```
strong (p=...)
```
、
```
< 0.10
```
->
```
weak (p=...)
```
、
```
>= 0.10
```
->
```
none (p=...)
```
（低于
```
0.001
```
的值引述为
```
p<0.001
```
）。池化 BLP p 值会忽略第一阶段估计误差，因此应将其视为近似等级，而不是正式的假设检验。
排除合成的 ground truth 和派生的 cluster 列： 除非用户明确要求审计合成数据恢复情况，否则绝不读取、分析或报告
```
TrueContrib_*
```
、
```
total_ground_truth_KPI
```
、
```
true_incremental_KPI_*
```
、
```
ground_truth_*
```
、
```
true_total_roi
```
、
```
SMAPE
```
、
```
R_squared
```
、
```
MAE
```
、
```
RMSE
```
或
```
metadata["ground_truth_metrics"]
```
。从驱动因素分析中排除
```
cluster_dml.derived_columns
```
（
```
cluster_date_block
```
）。

允许的手工计算与多运行规则： 当

outcome_col

表示毛收入时，盈亏平衡毛利率为

1 / roi_on_spend

；将

effect_per_unit

换算为自然单位（例如，当

treatment_types[d] == "percentage"

且以

[0, 1]

存储时除以

，以报告每 1 个百分点的影响）。绝不能臆造利润率或基准值（应改为询问用户），也绝不能外推到观测支持范围之外。对于分别估计的多个

output_dir

运行，仅在

outcome_col

一致时进行并列比较，且绝不跨运行汇总

incremental_kpi

。使用符合用户列语义和语言习惯的领域术语进行表达，不要泄露内部 schema 键名。

7-Step Analysis Playbook

七步分析执行手册

Work through the steps needed to answer the user's question. For a comprehensive review, execute all applicable steps and follow references/report_template.md.

Frame the run: Read

metadata.json

and inspect date frequency (

daily

weekly

monthly

), row count, active entity axes (

geo_col

item_col

), treatments (

treatment_cols

treatment_types

treatment_spend_cols

), confounders (

x_cols_list

covariates_for_cate_list

opt_threshold_roi

cluster_dml

, and Phase 0 / Phase 4 flags.

Headline causal impact: Summarize total
```
spend
```
(or treatment volume) and treated row count (Fact:), then
```
incremental_kpi
```
with 95% interval,
```
roi_on_spend
```
(or rescaled
```
effect_per_unit
```
),
```
share_of_outcome
```
, break-even margin (if revenue KPI), and payback verdict (Inference:).
Where it works (
geo_col
&
item_col
): Group
```
consolidated_1a_full_df.csv
```
by each configured entity axis (
```
geo_col
```
,
```
item_col
```
). Sort by
```
roi_on_spend
```
for efficiency questions or
```
incremental_kpi
```
for volume questions. Check whether
```
geo_col
```
/
```
item_col
```
is in
```
covariates_for_cate_list
```
.
When it works (calendar cadence): When
```
date_col
```
is present, group by month-of-year (and day-of-week when median date step <= 2 days, plus year-month or quarter for trajectory).
What amplifies it (drivers & 2-D interactions): Bin continuous drivers with within-entity quantiles (
```
within_quantile_bins
```
in references/metric_formulas.md, grouping by
```
geo_col
```
or
```
item_col
```
when present) so each unit is judged against its own baseline, and cross-tabulate 2-D interactions (e.g., a CATE covariate x treatment intensity, or two covariates from the run).
Can we trust it? (Diagnostics & raw segment profiles): Check repetition stability, OVB sensitivity (
```
robustness_value
```
vs.
```
max(benchmark_cf_d, benchmark_cf_y)
```
overall and least-robust segments), Phase 0 saturation diagnostics,
```
low_sample
```
(
```
< 30
```
treated rows), and
```
plausibility_flags
```
. Whenever two segments have non-overlapping 95% intervals (
```
ci_separation
```
on
```
roi_on_spend
```
or
```
effect_per_unit
```
) or
```
plausibility_flags
```
fire, profile that segment's raw data (
```
gap_in_row_sd
```
,
```
ratio_to_overall
```
,
```
treated_share
```
, and treated
```
p25/p50/p75
```
) before interpreting.
How should allocation move? (Optimization): When
```
007_optimization/
```
exists, report historical vs. optimized spend, incremental KPI, and ROI (total, by
```
geo_col
```
/
```
item_col
```
, and yearly from
```
optimization_yearly_summary.csv
```
), row counts shifted (
```
increased
```
,
```
reduced
```
,
```
cut_to_zero
```
), reconciliation with
```
optimization_metrics.csv
```
, and optimizer assumptions/warnings. Never design custom allocations, scale to unmodeled budgets, or shift budget across treatments or runs. If absent, note that optimization requires a single-treatment run with
```
optimize=True
```
,
```
date_col
```
, and spend mapping.

逐步执行回答用户问题所需的步骤。若要进行全面审查，应执行所有适用步骤，并遵循 references/report_template.md。

界定本次运行： 读取
```
metadata.json
```
，检查日期频率（
```
daily
```
、
```
weekly
```
、
```
monthly
```
）、行数、启用的实体轴（
```
geo_col
```
、
```
item_col
```
）、处理项（
```
treatment_cols
```
、
```
treatment_types
```
、
```
treatment_spend_cols
```
）、混杂因素（
```
x_cols_list
```
）、
```
covariates_for_cate_list
```
、
```
opt_threshold_roi
```
、
```
cluster_dml
```
，以及 Phase 0 / Phase 4 标志。
核心因果影响： 汇总总
```
spend
```
（或处理量）和接受处理的行数（Fact:），然后给出
```
incremental_kpi
```
及 95% 区间、
```
roi_on_spend
```
（或重新缩放的
```
effect_per_unit
```
）、
```
share_of_outcome
```
、盈亏平衡毛利率（如果结果 KPI 为收入）和回本结论（Inference:）。
在哪里有效（
geo_col
与
item_col
）：按每个已配置的实体轴（
```
geo_col
```
、
```
item_col
```
）对
```
consolidated_1a_full_df.csv
```
分组。对于效率问题，按
```
roi_on_spend
```
排序；对于规模问题，按
```
incremental_kpi
```
排序。检查
```
geo_col
```
/
```
item_col
```
是否包含在
```
covariates_for_cate_list
```
中。
何时有效（日历节奏）： 如果存在
```
date_col
```
，按月份分组；当中位日期步长 <= 2 天时，再按星期几分组；并按年-月或季度分组以观察趋势。
什么会放大效果（驱动因素与二维交互）： 使用实体内分位数对连续驱动因素分箱（
```
within_quantile_bins
```
，见 references/metric_formulas.md；存在
```
geo_col
```
或
```
item_col
```
时按其分组），从而将每个单元与其自身基线比较；并交叉制表分析二维交互（例如，一个 CATE 协变量 × 处理强度，或运行中的两个协变量）。
能否信任结果？（诊断与原始分群画像）： 检查重复稳定性、OVB 敏感性（整体及最不稳健分群中
```
robustness_value
```
与
```
max(benchmark_cf_d, benchmark_cf_y)
```
的关系）、Phase 0 saturation 诊断、
```
low_sample
```
（接受处理的行数
```
< 30
```
）和
```
plausibility_flags
```
。每当两个分群的 95% 区间不重叠（
```
roi_on_spend
```
或
```
effect_per_unit
```
上的
```
ci_separation
```
）或触发
```
plausibility_flags
```
时，在解释前先对该分群的原始数据进行画像（
```
gap_in_row_sd
```
、
```
ratio_to_overall
```
、
```
treated_share
```
以及接受处理样本的
```
p25/p50/p75
```
）。
应如何调整资源分配？（优化）： 如果存在
```
007_optimization/
```
，报告历史支出与优化后支出、增量 KPI 和 ROI（总体、按
```
geo_col
```
/
```
item_col
```
分组，以及来自
```
optimization_yearly_summary.csv
```
的逐年结果）、行数变化（
```
increased
```
、
```
reduced
```
、
```
cut_to_zero
```
）、与
```
optimization_metrics.csv
```
的核对结果，以及优化器的假设和警告。绝不能设计自定义分配、扩展到未建模的预算，或在不同处理项或运行之间转移预算。如果不存在该目录，应说明优化需要具备
```
optimize=True
```
、
```
date_col
```
和支出映射的单处理项运行。

Causal & Domain Interpretation Rules

因果与领域解释规则

Reading 95% intervals: Always lead with the point estimate and
```
effect_direction
```
(
```
positive
```
,
```
negative
```
,
```
zero
```
). Aggregate 95% bands sum row-level bounds conservatively and routinely span zero. Never call an estimate "statistically significant", "not significant", "inconclusive", or "indistinguishable from zero", and never use the words significant or p-value in prose (except quoting CATE grades verbatim like
```
strong (p=0.0022)
```
as an approximate heterogeneity grade).
Average vs. Marginal ROI:
```
roi_on_spend
```
is the average return on past spend.
```
worth_investing
```
justifies keeping historical spend;
```
not_worth_investing
```
justifies cutting/stopping;
```
undetermined
```
calls for a controlled test. Scaling budget up requires marginal returns from an active saturation curve or KKT
```
optimization
```
. Under saturation, per-unit effect naturally falls at higher spend along diminishing returns.
Column Role (
cate_covariate
|
confounder
|
unused
) & Constant-Effect Runs: Per-unit treatment effects vary only through
```
covariates_for_cate_list
```
. If
```
covariates_for_cate_list
```
is empty, per-unit effect is constant by construction and
```
incremental_kpi
```
differs across slices only with treatment volume. If a slice column is
```
confounder
```
(in
```
x_cols_list
```
only, including entity dummies) or
```
unused
```
, splitting by it is descriptive — showing where effects landed via covariate mix and intensity, not modeled slice-specific response. Say so explicitly and recommend adding the column to
```
covariates_for_cate_list
```
to test it. Warn against conditioning on post-treatment variables (columns moved by the treatment itself) as targeting pre-conditions.
Confounding, Carryover & Spillover: Inspect
```
x_cols_list
```
against the other columns in
```
consolidated_1a_full_df.csv
```
to flag unadjusted concurrent treatments or levers, intertemporal pull-forward or lagged carryover effects (
```
_l<k>
```
lagged columns), and cross-unit spillover or substitution across
```
geo_col
```
/
```
item_col
```
.

解读 95% 区间： 始终先给出点估计和
```
effect_direction
```
（
```
positive
```
、
```
negative
```
、
```
zero
```
）。汇总 95% 区间时，对行级上下界采用保守求和；这些区间通常会跨越零。绝不将估计称为“statistically significant”“not significant”“inconclusive”或“indistinguishable from zero”，也绝不在正文中使用 significant 或 p-value 这两个词；但按原文引用 CATE 等级（如
```
strong (p=0.0022)
```
）作为近似异质性等级时除外。
平均 ROI 与边际 ROI：
```
roi_on_spend
```
是过去支出的平均回报。
```
worth_investing
```
支持保留历史支出；
```
not_worth_investing
```
支持削减或停止；
```
undetermined
```
则需要开展受控测试。要扩大预算，必须有来自活跃 saturation 曲线或 KKT
```
optimization
```
的边际收益。在 saturation 下，随着支出增加，单位效应会因边际收益递减而自然下降。
列角色（
cate_covariate
|
confounder
|
unused
）与恒定效应运行：单位处理效应只会通过
```
covariates_for_cate_list
```
产生变化。如果
```
covariates_for_cate_list
```
为空，则单位效应按构造保持恒定，
```
incremental_kpi
```
在不同切片间的差异仅来自处理量。如果某个切片列是
```
confounder
```
（仅出现在
```
x_cols_list
```
中，包括实体虚拟变量）或
```
unused
```
，按它拆分仅属于描述性分析——展示效果通过协变量组合与处理强度落在何处，而不是模型估计出的切片特异性响应。应明确说明这一点，并建议将该列加入
```
covariates_for_cate_list
```
以进行检验。同时警告，不要把处理本身改变的 post-treatment 变量作为定向投放的前置条件。
混杂、Carryover 与 Spillover： 将
```
x_cols_list
```
与
```
consolidated_1a_full_df.csv
```
中的其他列进行对照，标记未调整的同时期处理项或杠杆、时间上的提前拉动（pull-forward）或滞后 carryover 效应（
```
_l<k>
```
滞后列），以及跨
```
geo_col
```
/
```
item_col
```
的 spillover 或替代效应。

Trust Checklist

信任检查清单

Check	Required Action
Payback & multiplicity	Keep `worth_investing` , cut `not_worth_investing` , test `undetermined` . Across many `geo_col` or `item_col` slices, ~2.5% per tail can cross `threshold_roi` by chance unless consistent across periods and repetitions.
Driver evidence	Claim a covariate shifts per-unit response only when CATE grade is `strong` (quote verbatim, e.g., `strong (p=0.0022)` ). Treat `weak` as a lead to validate and `none` as no modeled heterogeneity.
Plausibility & support	Flag `< 30` treated rows ( `low_sample` ) as directional only. If `incremental_kpi_exceeds_outcome` , `kpi_without_spend` , or `negative_spend` fires, treat that slice's estimate as unreliable and inspect raw segment profiles.
Model & Phase 0	Caveat high repetition CV ( `> 0.3` ), mixed repetition signs, `robustness_value <= max(benchmark_cf_d, benchmark_cf_y)` (passing rules out confounders only up to the strongest observed `x_col` ), few clusters ( `< 30` in `cluster_dml.messages` ), or Phase 0 warnings ( `1se_fail` , `diag1_fired` , `diag2_fired` , low `r_T` , `fallback_half_saturation_T_used` ).
Optimizer discipline	Frame `optimization` strictly as a retrospective model-implied proposal (no carryover/adstock, point-estimate CATE, no 95% interval). State whether Phase 4 ran `saturation` , `simple` , or `linear_fallback` , warn if `kpi_after > 2.0 * kpi_before` (upper bound from cutting low-scored rows), if `kpi_before <= 0 < kpi_after` , or if `> 30%` of active units are cut to zero, and ask about operational floors/contracts.

检查项	必须采取的操作
回本与多重性	保留 `worth_investing` ，削减 `not_worth_investing` ，对 `undetermined` 开展测试。在大量 `geo_col` 或 `item_col` 切片中，每一尾部约有 2.5% 的分片可能仅因偶然性就跨过 `threshold_roi` ，除非其在多个周期和重复运行中保持一致。
驱动因素证据	只有当 CATE 等级为 `strong` 时，才可断言协变量会改变单位响应（按原文引用，如 `strong (p=0.0022)` ）。将 `weak` 视为有待验证的线索，将 `none` 视为没有建模的异质性。
合理性与支持度	将 `< 30` 个接受处理的行（ `low_sample` ）标为仅具有方向性。如果 `incremental_kpi_exceeds_outcome` 、 `kpi_without_spend` 或 `negative_spend` 触发，则将该切片的估计视为不可靠，并检查原始分群画像。
模型与 Phase 0	对高重复 CV（ `> 0.3` ）、重复结果符号不一致、 `robustness_value <= max(benchmark_cf_d, benchmark_cf_y)` （通过该检验只能排除影响程度不超过已观测最强 `x_col` 的混杂因素）、cluster 数量过少（ `cluster_dml.messages` 中 `< 30` ），或 Phase 0 警告（ `1se_fail` 、 `diag1_fired` 、 `diag2_fired` 、较低的 `r_T` 、 `fallback_half_saturation_T_used` ）给出必要说明。
优化器纪律	严格将 `optimization` 定位为回溯性的模型隐含建议（无 carryover/adstock、采用点估计 CATE、无 95% 区间）。说明 Phase 4 运行的是 `saturation` 、 `simple` 还是 `linear_fallback` ；如果 `kpi_after > 2.0 * kpi_before` （剔除低分行后的上限）、 `kpi_before <= 0 < kpi_after` ，或超过 30% 的活跃单元被削减至零，则发出警告，并询问是否存在运营下限或合同约束。

Mandatory Statement Tagging (

Fact:

Inference:

Hypothesis:

)

强制陈述标签（

Fact:

Inference:

Hypothesis:

）

Start every bullet point (and every standalone result sentence) with exactly one bold tag — never rely on section headers, and split mixed bullets:

Fact: Raw input panel quantities (
```
spend
```
, observed KPI, row/treated counts, treatment intensity quantiles, bin cut points, covariate means).
Inference: DML model outputs (
```
incremental_kpi
```
, 95% intervals,
```
roi_on_spend
```
, payback verdicts, CATE evidence grades, sensitivity
```
RV
```
, model-implied optimization numbers).
Hypothesis: Proposed mechanism explaining why an inference occurred, always paired with a concrete verification step (config change or holdout experiment).

每个要点（以及每个独立的结果句）都必须以恰好一个粗体标签开头——绝不能依赖章节标题；包含多种内容的要点必须拆分。

Fact: 原始输入面板中的数量（
```
spend
```
、观测到的 KPI、行数/接受处理数、处理强度分位数、分箱切点、协变量均值）。
Inference: DML 模型输出（
```
incremental_kpi
```
、95% 区间、
```
roi_on_spend
```
、回本结论、CATE 证据等级、敏感性
```
RV
```
、模型隐含的优化数值）。
Hypothesis: 为解释某个推断为何发生而提出的机制，并且始终配套一个具体的验证步骤（配置变更或留出实验）。

Bundled References

内置参考文件

Exact aggregation, ROI, CATE grading, diagnostics, and optimization formulas: references/metric_formulas.md
Full causal review structure and statement-tagging examples: references/report_template.md

精确的汇总、ROI、CATE 分级、诊断和优化公式：references/metric_formulas.md
完整的因果审查结构和陈述标签示例：references/report_template.md

causal-insights

Original

Translation

Causal Insight Analysis for
`doubleml-pipeline`
Outputs

`doubleml-pipeline`
输出的因果洞察分析

Output Directory Reading Order

输出目录读取顺序

Four Non-Negotiable Calculation Rules

四条不可违背的计算规则

7-Step Analysis Playbook

七步分析执行手册

Causal & Domain Interpretation Rules

因果与领域解释规则

Trust Checklist

信任检查清单

Mandatory Statement Tagging (
`Fact:`
/
`Inference:`
/
`Hypothesis:`
)

强制陈述标签（
`Fact:`
/
`Inference:`
/
`Hypothesis:`
）

Bundled References

内置参考文件

causal-insights

Original

Translation

Causal Insight Analysis for doubleml-pipeline Outputs

doubleml-pipeline 输出的因果洞察分析

Output Directory Reading Order

输出目录读取顺序

Four Non-Negotiable Calculation Rules

四条不可违背的计算规则

7-Step Analysis Playbook

七步分析执行手册

Causal & Domain Interpretation Rules

因果与领域解释规则

Trust Checklist

信任检查清单

Mandatory Statement Tagging (Fact: / Inference: / Hypothesis:)

强制陈述标签（Fact: / Inference: / Hypothesis:）

Bundled References

内置参考文件

Causal Insight Analysis for
`doubleml-pipeline`
Outputs

`doubleml-pipeline`
输出的因果洞察分析

Mandatory Statement Tagging (
`Fact:`
/
`Inference:`
/
`Hypothesis:`
)

强制陈述标签（
`Fact:`
/
`Inference:`
/
`Hypothesis:`
）