@elaraai/east-py-datascience 1.0.12 → 1.0.14

package/dist/src/causal/causal.js

@@ -5,18 +5,21 @@
 /**
  * Causal inference for East.
  *
- * Provides causal effect estimation (DoWhy backdoor adjustment),
- * refutation tests, heterogeneous treatment effects (EconML LinearDML),
- * and accumulated local effects dose-response curves (PyALE).
+ * One declarative entry point — {@link Causal.experiment} — answers *"did X
+ * change Y, and can I trust it?"* for a binary treatment: the naive vs
+ * backdoor-adjusted effect, confounder balance, propensity overlap, a
+ * robustness check, and an honesty **verdict** that refuses (`adjusted = none`)
+ * when the data can't support an answer. The raw DoWhy / EconML / PyALE
+ * estimators are internal implementation it composes — not a public surface.
  *
  * @packageDocumentation
  */
-import { East, StructType, VariantType, OptionType, ArrayType, IntegerType, FloatType, BooleanType, StringType, BlobType, NullType, } from "@elaraai/east";
-import { VectorType, MatrixType } from "../types.js";
+import { East, StructType, VariantType, OptionType, ArrayType, IntegerType, FloatType, BooleanType, StringType, NullType, } from "@elaraai/east";
+import { VectorType } from "../types.js";
 // Re-export shared types for convenience
-export { VectorType, MatrixType } from "../types.js";
+export { VectorType } from "../types.js";
 // ============================================================================
-// Config Types
+// Shared vocabulary
 // ============================================================================
 /**
  * Inverse propensity weighting scheme for the propensity score
@@ -34,7 +37,7 @@ export const CausalWeightingSchemeType = VariantType({
  * Backdoor-adjusted effect estimator.
  */
 export const CausalEstimatorType = VariantType({
-    /** Linear regression of outcome on treatment + common causes */
+    /** Linear regression of outcome on treatment + common causes (default) */
     linear_regression: NullType,
     /** Inverse propensity score weighting (binary treatment only) */
     propensity_score_weighting: StructType({
@@ -53,545 +56,325 @@ export const CausalTargetUnitsType = VariantType({
     /** Average treatment effect on the controls */
     atc: NullType,
 });
-/**
- * Propensity-based sample trimming applied before estimation
- * (propensity score weighting only).
- */
-export const PropensityTrimType = VariantType({
-    /** Keep units inside the common-support overlap of treated and control propensities */
-    overlap: NullType,
-    /** Keep units with propensity inside explicit bounds */
-    bounds: StructType({
-        /** Minimum propensity score to keep */
-        lower: FloatType,
-        /** Maximum propensity score to keep */
-        upper: FloatType,
-    }),
-});
 /**
  * Bootstrap confidence interval configuration.
  *
- * When `cluster_column` is set, whole clusters are resampled with
- * replacement (the cluster is the exchangeable unit) — use this when rows
- * are autocorrelated within a group (e.g. days within a batch).
+ * When `cluster_column` is set, whole clusters are resampled with replacement
+ * (the cluster is the exchangeable unit) — use this when rows are autocorrelated
+ * within a group.
  */
 export const CausalBootstrapConfigType = StructType({
-    /** Number of bootstrap replicates */
+    /** Number of bootstrap replicates (default 200) */
     reps: IntegerType,
     /** Column whose values identify clusters to resample (default: resample rows) */
     cluster_column: OptionType(StringType),
     /** Confidence level for the percentile interval (default 0.95) */
     confidence_level: OptionType(FloatType),
 });
+/** A confidence interval — the one CI type used across the result. */
+export const CiType = StructType({ lower: FloatType, upper: FloatType });
+// ============================================================================
+// Experiment — the single declarative entry point (snake_case; mirrors the
+// e3-ui `<Experiment>` contract exactly so the two replicas unify structurally).
+// ============================================================================
 /**
- * Configuration for backdoor-adjusted causal effect estimation.
- *
- * The data matrix is interpreted via `columns`: every column referenced by
- * `treatment`, `outcome`, `common_causes`, `categorical` and
- * `bootstrap.cluster_column` must appear in `columns`. Categorical columns
- * hold integer-valued category codes and are one-hot encoded internally.
+ * Which robustness checks to run inside {@link causal_experiment}.
  */
-export const CausalEffectConfigType = StructType({
-    /** Treatment column (must be 0/1 for propensity score weighting) */
+export const RefuteSpecType = StructType({
+    /** Permuted-treatment negative control — a real effect should vanish. */
+    placebo: BooleanType,
+    /** Inject an independent random common cause — the effect should hold. */
+    random_common_cause: BooleanType,
+    /** Re-estimate on random subsamples — the effect should be stable. */
+    data_subset: BooleanType,
+    /** Unobserved-confounder strengths to simulate → the sensitivity / tipping curve. */
+    sensitivity: OptionType(ArrayType(FloatType)),
+});
+/**
+ * Configuration for {@link causal_experiment} — the staged "question + method"
+ * the surface edits. Binary treatment only (v1). Reuses the estimator / target
+ * / bootstrap vocabularies.
+ */
+export const CausalExperimentConfigType = StructType({
+    /** Binary (0/1) treatment column. */
     treatment: StringType,
-    /** Outcome column */
+    /** Outcome column. */
     outcome: StringType,
-    /** Confounder columns to adjust for (the backdoor set) */
+    /** Confounders to adjust for (the backdoor set). */
     common_causes: ArrayType(StringType),
-    /** Columns holding integer category codes, one-hot encoded internally */
+    /** Confounder columns holding categories (string or int codes), one-hot encoded. */
     categorical: OptionType(ArrayType(StringType)),
-    /** Effect estimator (default: linear_regression) */
+    /** Estimator (default: linear_regression). */
     method: OptionType(CausalEstimatorType),
-    /** Target population (default: ate) */
-    target_units: OptionType(CausalTargetUnitsType),
-    /** Propensity trimming applied before estimation (psw only) */
-    trim: OptionType(PropensityTrimType),
-    /** Bootstrap confidence interval (omit to skip CI computation) */
+    /** Target population (default: ate). */
+    estimand: OptionType(CausalTargetUnitsType),
+    /** Which robustness checks to run. */
+    refute: OptionType(RefuteSpecType),
+    /** Continuous column for the ALE dose-response curve (the "How much?" view). */
+    dose_feature: OptionType(StringType),
+    /** Positivity guard — common-support fraction below this → non_identifiable_positivity (default 0.10). */
+    min_overlap: OptionType(FloatType),
+    /** Not-estimable guard — minority-arm fraction below this → not_estimable (default 0.02). */
+    min_treatment_variation: OptionType(FloatType),
+    /** Bootstrap CI config (default: 200 reps, 0.95). */
     bootstrap: OptionType(CausalBootstrapConfigType),
-    /** Random seed for propensity fitting and bootstrap resampling */
+    /** Random seed. */
     random_state: OptionType(IntegerType),
 });
-/**
- * Refutation test for an estimated causal effect.
- */
-export const CausalRefuterType = VariantType({
-    /** Replace treatment with a permuted placebo - effect should vanish */
-    placebo_treatment: StructType({
-        /** Number of simulations (default 100) */
-        num_simulations: OptionType(IntegerType),
-    }),
-    /** Add an independent random common cause - effect should be unchanged */
-    random_common_cause: StructType({
-        /** Number of simulations (default 100) */
-        num_simulations: OptionType(IntegerType),
-    }),
-    /** Re-estimate on random data subsets - effect should be stable */
-    data_subset: StructType({
-        /** Fraction of rows kept per simulation (default 0.8) */
-        subset_fraction: OptionType(FloatType),
-        /** Number of simulations (default 100) */
-        num_simulations: OptionType(IntegerType),
-    }),
-    /**
-     * Simulate an unobserved confounder at each given strength - a
-     * sensitivity/tipping curve. Strength acts on both treatment
-     * (flip probability for binary treatment, linear coefficient otherwise)
-     * and outcome (linear coefficient).
-     */
-    unobserved_common_cause: StructType({
-        /** Confounder effect strengths to simulate, one new effect per entry */
-        effect_strengths: ArrayType(FloatType),
-    }),
+/** One confounder's before-adjustment imbalance (categoricals → one row per level). */
+export const BalanceRowType = StructType({
+    column: StringType,
+    /** The original confounder this row belongs to — equals `column` for a numeric
+     *  confounder; the base confounder for a one-hot categorical level. */
+    base_column: StringType,
+    treated_mean: FloatType,
+    control_mean: FloatType,
+    /** Standardized mean difference, (mt-mc)/sqrt((vt+vc)/2). */
+    std_diff: FloatType,
 });
-/**
- * Nuisance model for DML residualization stages.
- */
-export const CausalNuisanceModelType = VariantType({
-    /** Random forest (regressor, or classifier for a discrete treatment) */
-    random_forest: StructType({
-        /** Number of trees (default 100) */
-        n_estimators: OptionType(IntegerType),
-        /** Minimum samples per leaf (default 5) */
-        min_samples_leaf: OptionType(IntegerType),
-        /** Maximum tree depth (default unlimited) */
-        max_depth: OptionType(IntegerType),
-    }),
-    /** Gradient boosting (regressor, or classifier for a discrete treatment) */
-    gradient_boosting: StructType({
-        /** Number of boosting stages (default 100) */
-        n_estimators: OptionType(IntegerType),
-        /** Learning rate (default 0.1) */
-        learning_rate: OptionType(FloatType),
-        /** Maximum tree depth (default 3) */
-        max_depth: OptionType(IntegerType),
-    }),
-    /** Linear/logistic regression */
-    linear: NullType,
+/** Positivity / common-support diagnostic (binary treatment). */
+export const OverlapDiagnosticType = StructType({
+    /** Propensity histogram (20 bins over [0,1]) for the treated arm. */
+    treated_propensity: VectorType(FloatType),
+    /** Propensity histogram for the control arm. */
+    control_propensity: VectorType(FloatType),
+    /** Fraction of rows inside the treated/control common support. */
+    common_support_frac: FloatType,
+    /** Whether common support clears `min_overlap`. */
+    positivity_ok: BooleanType,
 });
-/**
- * Configuration for double machine learning (EconML LinearDML).
- */
-export const CausalDMLConfigType = StructType({
-    /** Nuisance model for the outcome stage (default: random_forest) */
-    model_y: OptionType(CausalNuisanceModelType),
-    /** Nuisance model for the treatment stage (default: random_forest) */
-    model_t: OptionType(CausalNuisanceModelType),
-    /** Treat the treatment as discrete/categorical (default false) */
-    discrete_treatment: OptionType(BooleanType),
-    /** Cross-fitting folds (default 2) */
-    cv_folds: OptionType(IntegerType),
-    /** Confidence level for effect/ATE intervals (default 0.95) */
-    confidence_level: OptionType(FloatType),
-    /** Random seed */
-    random_state: OptionType(IntegerType),
+/** The robustness summary the verdict + Trust tab consume. */
+export const RefutationType = StructType({
+    /** Effect under a permuted (placebo) treatment — should be ≈ 0. */
+    placebo_effect: OptionType(FloatType),
+    /** Whether the placebo effect vanished. */
+    placebo_passes: OptionType(BooleanType),
+    /** Whether a decoy random common cause left the estimate inside its CI. */
+    random_cc_within_ci: OptionType(BooleanType),
+    /** Mean effect across data subsamples (stability). */
+    data_subset_effect: OptionType(FloatType),
+    /** Std of the effect across data subsamples. */
+    data_subset_std: OptionType(FloatType),
+    /** Closed-form E-value — confounder strength needed to explain the effect away. */
+    robustness_value: OptionType(FloatType),
+    /** Unobserved-confounder sensitivity (tipping) curve: effect at each simulated strength. */
+    sensitivity: OptionType(StructType({
+        strengths: VectorType(FloatType),
+        effects: VectorType(FloatType),
+    })),
 });
-/**
- * Configuration for an accumulated local effects (ALE) dose-response curve.
- *
- * Fits a gradient-boosting emulator of the outcome on all non-outcome
- * columns, then computes the correlation-robust ALE curve of `feature`.
- */
-export const CausalALEConfigType = StructType({
-    /** Outcome column the emulator predicts */
-    outcome: StringType,
-    /** Continuous feature column to compute the ALE curve for */
+/** A dose-response (ALE) curve of a continuous feature on the outcome. */
+export const DoseResponseType = StructType({
     feature: StringType,
-    /** Columns holding integer category codes, one-hot encoded internally */
-    categorical: OptionType(ArrayType(StringType)),
-    /** Number of grid intervals (default 10) */
-    grid_size: OptionType(IntegerType),
-    /** Include confidence intervals (default true) */
-    include_ci: OptionType(BooleanType),
-    /** Confidence level for the CI (default 0.95) */
-    confidence_level: OptionType(FloatType),
-    /** Emulator (HistGradientBoosting) hyperparameters */
-    emulator: OptionType(StructType({
-        /** Number of boosting iterations (default 300) */
-        n_estimators: OptionType(IntegerType),
-        /** Learning rate (default 0.05) */
-        learning_rate: OptionType(FloatType),
-        /** Maximum tree depth (default unlimited) */
-        max_depth: OptionType(IntegerType),
-        /** Minimum samples per leaf (default 20; lower for small datasets) */
-        min_samples_leaf: OptionType(IntegerType),
-    })),
-    /** Random seed for the emulator */
-    random_state: OptionType(IntegerType),
+    grid: VectorType(FloatType),
+    effect: VectorType(FloatType),
+    lower: OptionType(VectorType(FloatType)),
+    upper: OptionType(VectorType(FloatType)),
+    /** Rows per dose bin — drives the surface's "you are here" (busiest bin) marker. */
+    size: VectorType(IntegerType),
 });
-// ============================================================================
-// Model Blob Types
-// ============================================================================
 /**
- * Model blob for a fitted LinearDML estimator.
+ * The honesty verdict — a thin tag; the numbers live top-level on the result.
+ * Only `not_estimable` carries a (human-readable) reason.
  */
-export const CausalDMLModelBlobType = VariantType({
-    /** Fitted EconML LinearDML estimator */
-    causal_dml: StructType({
-        /** Serialized estimator (cloudpickle) */
-        data: BlobType,
-        /** Number of effect-modifier (X) features */
-        n_features_x: IntegerType,
-        /** Confidence level used for effect/ATE intervals */
-        confidence_level: FloatType,
-    }),
+export const ExperimentVerdictType = VariantType({
+    /** A real, robust, material effect. */
+    causal: NullType,
+    /** A small but real effect, or no clear effect after adjustment. */
+    modest: NullType,
+    /** Adjusted, but the estimate isn't trustworthy (placebo fails). */
+    adjustment_insufficient: NullType,
+    /** No like-for-like comparison exists (positivity violated). */
+    non_identifiable_positivity: NullType,
+    /** The estimand can't be formed (treatment barely varies). */
+    not_estimable: StringType,
 });
-// ============================================================================
-// Result Types
-// ============================================================================
 /**
- * Estimated causal effect.
+ * The complete, honest result of {@link causal_experiment}. `adjusted` is
+ * `none` when the engine refuses (positivity / no-variation); the `verdict` tag
+ * carries the headline; every word/colour on the surface derives from these numbers.
  */
-export const CausalEffectResultType = StructType({
-    /** Point estimate of the effect (outcome units per treatment unit) */
-    effect: FloatType,
-    /** Bootstrap percentile confidence interval (present when bootstrap configured) */
-    ci: OptionType(StructType({
-        /** Lower bound */
-        lower: FloatType,
-        /** Upper bound */
-        upper: FloatType,
-    })),
-    /** Rows used for estimation (after trimming) */
-    n_samples: IntegerType,
-    /** Treated rows used */
+export const CausalExperimentResultType = StructType({
+    /** The raw (unadjusted) mean difference — always computable. */
+    naive: FloatType,
+    naive_ci: OptionType(CiType),
+    /** The adjusted (like-for-like) effect + CI; `none` ⇒ the engine refused. */
+    adjusted: OptionType(StructType({ effect: FloatType, ci: OptionType(CiType) })),
+    n_total: IntegerType,
     n_treated: IntegerType,
-    /** Control rows used */
     n_control: IntegerType,
+    n_dropped: IntegerType,
+    /** Per-confounder before-adjustment imbalance, most-imbalanced first. */
+    balance: ArrayType(BalanceRowType),
+    overlap: OverlapDiagnosticType,
+    refutation: OptionType(RefutationType),
+    /** ALE dose-response of `dose_feature` (present when `config.dose_feature` is set). */
+    dose_response: OptionType(DoseResponseType),
+    verdict: ExperimentVerdictType,
 });
-/**
- * Refutation test result.
- */
-export const CausalRefuteResultType = StructType({
-    /** The original estimated effect being refuted */
-    estimated_effect: FloatType,
-    /**
-     * Effect under the refutation. One entry for placebo/random-common-cause/
-     * data-subset; one entry per strength for unobserved_common_cause.
-     */
-    new_effects: VectorType(FloatType),
-    /** Refutation p-value where the refuter provides one */
-    p_value: OptionType(FloatType),
-});
-/**
- * Average treatment effect with confidence interval.
- */
-export const CausalATEResultType = StructType({
-    /** Average treatment effect over the given X */
-    ate: FloatType,
-    /** Lower bound at the model's confidence level */
-    lower: FloatType,
-    /** Upper bound at the model's confidence level */
-    upper: FloatType,
-});
-/**
- * Accumulated local effects curve.
- */
-export const ALEResultType = StructType({
-    /** Feature grid values (interval edges) */
-    grid: VectorType(FloatType),
-    /** Centered ALE effect at each grid value (outcome units) */
-    effect: VectorType(FloatType),
-    /** Lower CI at each grid value (present when include_ci) */
-    lower: OptionType(VectorType(FloatType)),
-    /** Upper CI at each grid value (present when include_ci) */
-    upper: OptionType(VectorType(FloatType)),
-    /** Number of samples in each grid interval */
-    size: VectorType(IntegerType),
-});
-// ============================================================================
-// Platform Functions
-// ============================================================================
-/**
 /**
  * Type-parameter placeholder for the generic row struct `T`. At a call site the
  * caller passes the concrete row `StructType`; `applyTypeArgs` substitutes this
- * bare `"T"` reference wherever it appears in the input types (here, inside
- * `ArrayType(ROW_T)`). The cast is the documented way to nest a type parameter
- * in a `genericPlatform` input.
+ * bare `"T"` reference wherever it appears in the input types (inside
+ * `ArrayType(ROW_T)`).
  */
 const ROW_T = "T";
 /**
- * Estimate a backdoor-adjusted causal effect of treatment on outcome.
- *
- * Identifies the effect with DoWhy given the common causes, then estimates
- * it by linear regression or inverse propensity score weighting. Optionally
- * trims to propensity common support and computes a (cluster) bootstrap
- * confidence interval.
+ * One declarative causal experiment — naive vs adjusted effect, balance,
+ * overlap, robustness, and an honesty verdict, in a single call. Generic over
+ * the row struct (fields = columns), binary treatment.
  *
  * @param data - Array of row structs (one per unit; fields are the columns)
- * @param config - Estimation configuration
- * @returns Effect estimate with optional CI and sample counts
+ * @param config - The experiment configuration
+ * @returns The honest result + verdict; `adjusted` is `none` when refused
  */
-export const causal_effect = East.genericPlatform("causal_effect", ["T"], [ArrayType(ROW_T), CausalEffectConfigType], CausalEffectResultType);
-/**
- * Refute an estimated causal effect.
- *
- * Re-estimates the effect from `config`, then applies the given refuter
- * (placebo treatment, random common cause, data subset, or simulated
- * unobserved confounder sensitivity curve).
- *
- * @param data - Data matrix (rows = units, columns named by config.columns)
- * @param config - Estimation configuration (same as causal_effect)
- * @param refuter - Refutation test to apply
- * @returns Original effect, refuted effect(s), and p-value where available
- */
-export const causal_refute = East.genericPlatform("causal_refute", ["T"], [ArrayType(ROW_T), CausalEffectConfigType, CausalRefuterType], CausalRefuteResultType);
-/**
- * Fit an EconML LinearDML estimator for heterogeneous treatment effects.
- *
- * Cross-fits nuisance models for outcome and treatment, then fits a linear
- * CATE model on the residuals.
- *
- * @param Y - Outcome vector
- * @param T - Treatment vector
- * @param X - Effect modifier matrix (CATE varies with these)
- * @param W - Additional confounders adjusted for but not modifying the effect
- * @param config - DML configuration
- * @returns Model blob for use with dmlEffect / dmlAte
- */
-export const causal_dml_train = East.platform("causal_dml_train", [VectorType(FloatType), VectorType(FloatType), MatrixType(FloatType), OptionType(MatrixType(FloatType)), CausalDMLConfigType], CausalDMLModelBlobType);
-/**
- * Per-row conditional average treatment effects (CATE) from a fitted DML model.
- *
- * @param model - Fitted DML model blob
- * @param X - Effect modifier matrix
- * @returns CATE per row (outcome units per treatment unit)
- */
-export const causal_dml_effect = East.platform("causal_dml_effect", [CausalDMLModelBlobType, MatrixType(FloatType)], VectorType(FloatType));
+export const causal_experiment = East.genericPlatform("causal_experiment", ["T"], [ArrayType(ROW_T), CausalExperimentConfigType], CausalExperimentResultType);
+// ============================================================================
+// Validation-design contract — `causal_design_validation`
+//
+// Turns a finished experiment into the recipe for a REAL randomised controlled
+// trial that would confirm the effect (how many units, the split, which
+// categories to match the groups on) — or, when a plain trial can't be run, what
+// to change. One design family; the framing + size `basis` + visuals vary with
+// the verdict. Replicated verbatim (snake_case) in e3-ui's experiment types.
+// ============================================================================
+/** Why the trial is sized the way it is — set from the verdict. */
+export const DesignBasisType = VariantType({
+    /** Clear effect → power the trial to detect the observed effect. */
+    detect_observed: NullType,
+    /** Fuzzy / maybe-nothing → power to the smallest effect worth acting on. */
+    resolve_vs_null: NullType,
+    /** A trust check failed → randomise to remove the bias adjustment couldn't. */
+    de_bias: NullType,
+    /** No overlap → randomise within the comparable range. */
+    restrict_to_overlap: NullType,
+    /** No control group exists → hold back a random sample next time. */
+    create_control: NullType,
+});
+/** One sizing option — a split and the head-count it needs (even split first). */
+export const TrialOptionType = StructType({
+    label: StringType,
+    /** Fraction assigned to the treatment (0..1; 0.5 = even). */
+    treated_share: FloatType,
+    n_treated: IntegerType,
+    n_control: IntegerType,
+    n_total: IntegerType,
+});
+/** The "chance of detecting it" curve — total head-count → power (0..1). */
+export const PowerCurveType = StructType({
+    n: VectorType(IntegerType),
+    power: VectorType(FloatType),
+});
 /**
- * Average treatment effect with confidence interval from a fitted DML model.
- *
- * @param model - Fitted DML model blob
- * @param X - Effect modifier matrix to average over
- * @returns ATE with interval at the confidence level configured at training
+ * The validation-trial recipe — a randomised controlled trial sized from the
+ * observed effect (or the materiality threshold) and the outcome spread, with the
+ * groups matched on the confounders that were most imbalanced.
  */
-export const causal_dml_ate = East.platform("causal_dml_ate", [CausalDMLModelBlobType, MatrixType(FloatType)], CausalATEResultType);
+export const ExperimentDesignType = StructType({
+    verdict: ExperimentVerdictType,
+    basis: DesignBasisType,
+    /** Effect size the trial is powered to detect (observed, or materiality). */
+    target_effect: FloatType,
+    /** Outcome spread (pooled SD) used to size it. */
+    outcome_sd: FloatType,
+    target_power: FloatType,
+    alpha: FloatType,
+    /** Chance the CURRENT sample would already detect `target_effect`; `none` when there's no comparison group. */
+    current_power: OptionType(FloatType),
+    /** Categories both groups must be matched on (most-imbalanced confounders). */
+    match_on: ArrayType(StringType),
+    /** Ranked split options (even split first; cost-saving alternates). */
+    options: ArrayType(TrialOptionType),
+    /** The detect-chance curve for the chart. */
+    power_curve: PowerCurveType,
+    /** One generated, plain-language sentence framing the recipe. */
+    rationale: StringType,
+});
+/** Optional knobs for {@link causal_design_validation} (all developer-defaulted). */
+export const DesignConfigType = StructType({
+    /** Significance level (default 0.05). */
+    alpha: OptionType(FloatType),
+    /** Target chance of detecting the effect (default 0.8). */
+    target_power: OptionType(FloatType),
+    /** Smallest effect worth acting on — sizes the trial to this when set / when there's no trustworthy observed effect. */
+    materiality: OptionType(FloatType),
+    /** Treatment shares to offer as options (default [0.5]). */
+    treated_shares: OptionType(ArrayType(FloatType)),
+});
 /**
- * Accumulated local effects dose-response curve of a feature on an outcome.
- *
- * Fits a gradient boosting emulator on all non-outcome columns, then
- * computes the ALE curve of the feature - robust to correlated features,
- * unlike partial dependence.
+ * Design the real controlled trial that would validate a finished experiment.
+ * Generic over the row struct (same as {@link causal_experiment}); takes the data,
+ * the experiment config, the experiment result, and optional design knobs, and
+ * returns the trial recipe (sample size, split options, match-on categories, the
+ * power curve, and a plain-language rationale).
  *
- * @param data - Data matrix (rows = units, columns named by config.columns)
- * @param config - ALE configuration
- * @returns ALE curve with grid, centered effect, optional CI, and bin sizes
+ * @param data - The rows the experiment ran on
+ * @param config - The experiment configuration (names treatment / outcome / confounders)
+ * @param result - The {@link causal_experiment} result whose verdict drives the recipe
+ * @param design_config - Optional alpha / power / materiality / split knobs
+ * @returns The validation-trial recipe
  */
-export const causal_ale = East.genericPlatform("causal_ale", ["T"], [ArrayType(ROW_T), CausalALEConfigType], ALEResultType);
+export const causal_design_validation = East.genericPlatform("causal_design_validation", ["T"], [ArrayType(ROW_T), CausalExperimentConfigType, CausalExperimentResultType, DesignConfigType], ExperimentDesignType);
 // ============================================================================
 // Grouped Export
 // ============================================================================
-/**
- * Type definitions for causal inference functions.
- */
+/** Type definitions for causal inference. */
 export const CausalTypes = {
-    // Config types
+    // Shared vocabulary
     CausalWeightingSchemeType,
     CausalEstimatorType,
     CausalTargetUnitsType,
-    PropensityTrimType,
     CausalBootstrapConfigType,
-    CausalEffectConfigType,
-    CausalRefuterType,
-    CausalNuisanceModelType,
-    CausalDMLConfigType,
-    CausalALEConfigType,
-    // Model blob types
-    CausalDMLModelBlobType,
-    // Result types
-    CausalEffectResultType,
-    CausalRefuteResultType,
-    CausalATEResultType,
-    ALEResultType,
+    CiType,
+    // Experiment contract
+    RefuteSpecType,
+    CausalExperimentConfigType,
+    BalanceRowType,
+    OverlapDiagnosticType,
+    RefutationType,
+    DoseResponseType,
+    ExperimentVerdictType,
+    CausalExperimentResultType,
+    // Validation-design contract
+    DesignBasisType,
+    TrialOptionType,
+    PowerCurveType,
+    ExperimentDesignType,
+    DesignConfigType,
 };
 /**
- * Causal inference.
+ * Causal inference — one declarative entry point.
  *
- * Backdoor-adjusted effect estimation and refutation (DoWhy),
- * heterogeneous treatment effects via double machine learning
- * (EconML LinearDML), and accumulated local effects dose-response
- * curves (PyALE).
+ * `Causal.experiment(data, config)` runs a complete, honest causal experiment
+ * for a binary treatment and returns the naive vs adjusted effect, confounder
+ * balance, propensity overlap, a robustness check, and a verdict
+ * (`causal` / `modest` / `adjustment_insufficient` / `non_identifiable_positivity`
+ * / `not_estimable`). It refuses (`adjusted = none`) when the data can't support
+ * an estimate. DoWhy / EconML / PyALE are internal implementation it composes.
  *
  * @example
  * ```ts
- * import { East, FloatType, variant } from "@elaraai/east";
- * import { Causal, MatrixType } from "@elaraai/east-py-datascience";
+ * import { East, ArrayType, StructType, FloatType, BooleanType, variant } from "@elaraai/east";
+ * import { Causal } from "@elaraai/east-py-datascience";
  *
- * const estimate = East.function(
- *     [MatrixType(FloatType)],
- *     Causal.Types.CausalEffectResultType,
- *     ($, data) => {
- *         const config = $.let({
- *             columns: ["treated", "outcome", "confounder"],
- *             treatment: "treated",
- *             outcome: "outcome",
- *             common_causes: ["confounder"],
- *             categorical: variant('none', null),
- *             method: variant('some', variant('linear_regression', null)),
- *             target_units: variant('some', variant('ate', null)),
- *             trim: variant('none', null),
- *             bootstrap: variant('none', null),
- *             random_state: variant('some', 42n),
- *         }, Causal.Types.CausalEffectConfigType);
- *         return $.return(Causal.effect(data, config));
- *     }
- * );
+ * const Row = StructType({ treated: BooleanType, outcome: FloatType, z: FloatType });
+ * const run = East.function([ArrayType(Row)], Causal.Types.CausalExperimentResultType, ($, data) => {
+ *   const config = $.let({
+ *     treatment: "treated", outcome: "outcome", common_causes: ["z"],
+ *     categorical: variant('none', null),
+ *     method: variant('none', null), estimand: variant('none', null),
+ *     refute: variant('some', { placebo: true, random_common_cause: false }),
+ *     min_overlap: variant('some', 0.1), min_treatment_variation: variant('some', 0.02),
+ *     bootstrap: variant('none', null), random_state: variant('some', 42n),
+ *   }, Causal.Types.CausalExperimentConfigType);
+ *   return $.return(Causal.experiment([Row], data, config));
+ * });
  * ```
  */
 export const Causal = {
-    /**
-     * Estimate a backdoor-adjusted causal effect of treatment on outcome.
-     *
-     * Linear regression or inverse propensity score weighting (with
-     * optional propensity trimming), plus optional cluster bootstrap CI.
-     *
-     * @example
-     * ```ts
-     * import { East, FloatType, variant } from "@elaraai/east";
-     * import { Causal, CausalEffectConfigType, MatrixType } from "@elaraai/east-py-datascience";
-     *
-     * const attEstimate = East.function(
-     *     [MatrixType(FloatType)],
-     *     Causal.Types.CausalEffectResultType,
-     *     ($, data) => {
-     *         const config = $.let({
-     *             columns: ["treated", "outcome", "z1", "z2", "batch"],
-     *             treatment: "treated",
-     *             outcome: "outcome",
-     *             common_causes: ["z1", "z2"],
-     *             categorical: variant('none', null),
-     *             method: variant('some', variant('propensity_score_weighting', {
-     *                 weighting_scheme: variant('some', variant('ips_stabilized_weight', null)),
-     *             })),
-     *             target_units: variant('some', variant('att', null)),
-     *             trim: variant('some', variant('overlap', null)),
-     *             bootstrap: variant('some', {
-     *                 reps: 200n,
-     *                 cluster_column: variant('some', "batch"),
-     *                 confidence_level: variant('some', 0.95),
-     *             }),
-     *             random_state: variant('some', 42n),
-     *         }, CausalEffectConfigType);
-     *         return $.return(Causal.effect(data, config));
-     *     }
-     * );
-     * ```
-     */
-    effect: causal_effect,
-    /**
-     * Refute an estimated causal effect with placebo, random common cause,
-     * data subset, or unobserved-confounder sensitivity tests.
-     *
-     * @example
-     * ```ts
-     * import { East, FloatType, variant } from "@elaraai/east";
-     * import { Causal, MatrixType } from "@elaraai/east-py-datascience";
-     *
-     * const placebo = East.function(
-     *     [MatrixType(FloatType), Causal.Types.CausalEffectConfigType],
-     *     Causal.Types.CausalRefuteResultType,
-     *     ($, data, config) => {
-     *         const refuter = $.let(variant('placebo_treatment', {
-     *             num_simulations: variant('some', 50n),
-     *         }), Causal.Types.CausalRefuterType);
-     *         // new_effects should be near zero if the estimate is causal
-     *         return $.return(Causal.refute(data, config, refuter));
-     *     }
-     * );
-     * ```
-     */
-    refute: causal_refute,
-    /**
-     * Fit an EconML LinearDML estimator for heterogeneous treatment effects.
-     *
-     * @example
-     * ```ts
-     * import { East, FloatType, variant } from "@elaraai/east";
-     * import { Causal, CausalDMLConfigType, MatrixType, VectorType } from "@elaraai/east-py-datascience";
-     *
-     * const train = East.function(
-     *     [VectorType(FloatType), VectorType(FloatType), MatrixType(FloatType), MatrixType(FloatType)],
-     *     Causal.Types.CausalDMLModelBlobType,
-     *     ($, Y, T, X, W) => {
-     *         const config = $.let({
-     *             model_y: variant('some', variant('random_forest', {
-     *                 n_estimators: variant('some', 100n),
-     *                 min_samples_leaf: variant('some', 5n),
-     *                 max_depth: variant('none', null),
-     *             })),
-     *             model_t: variant('none', null),
-     *             discrete_treatment: variant('none', null),
-     *             cv_folds: variant('some', 2n),
-     *             confidence_level: variant('some', 0.95),
-     *             random_state: variant('some', 42n),
-     *         }, CausalDMLConfigType);
-     *         return $.return(Causal.dmlTrain(Y, T, X, variant('some', W), config));
-     *     }
-     * );
-     * ```
-     */
-    dmlTrain: causal_dml_train,
-    /**
-     * Per-row conditional average treatment effects from a fitted DML model.
-     *
-     * @example
-     * ```ts
-     * import { East, FloatType } from "@elaraai/east";
-     * import { Causal, MatrixType, VectorType } from "@elaraai/east-py-datascience";
-     *
-     * const cate = East.function(
-     *     [Causal.Types.CausalDMLModelBlobType, MatrixType(FloatType)],
-     *     VectorType(FloatType),
-     *     ($, model, X) => $.return(Causal.dmlEffect(model, X))
-     * );
-     * ```
-     */
-    dmlEffect: causal_dml_effect,
-    /**
-     * Average treatment effect with confidence interval from a fitted DML model.
-     *
-     * @example
-     * ```ts
-     * import { East, FloatType } from "@elaraai/east";
-     * import { Causal, MatrixType } from "@elaraai/east-py-datascience";
-     *
-     * const ate = East.function(
-     *     [Causal.Types.CausalDMLModelBlobType, MatrixType(FloatType)],
-     *     Causal.Types.CausalATEResultType,
-     *     ($, model, X) => $.return(Causal.dmlAte(model, X))
-     * );
-     * ```
-     */
-    dmlAte: causal_dml_ate,
-    /**
-     * Accumulated local effects dose-response curve of a feature on an outcome.
-     *
-     * @example
-     * ```ts
-     * import { East, FloatType, variant } from "@elaraai/east";
-     * import { Causal, CausalALEConfigType, MatrixType } from "@elaraai/east-py-datascience";
-     *
-     * const doseResponse = East.function(
-     *     [MatrixType(FloatType)],
-     *     Causal.Types.ALEResultType,
-     *     ($, data) => {
-     *         const config = $.let({
-     *             columns: ["dose", "z", "response"],
-     *             outcome: "response",
-     *             feature: "dose",
-     *             categorical: variant('none', null),
-     *             grid_size: variant('some', 10n),
-     *             include_ci: variant('some', true),
-     *             confidence_level: variant('some', 0.95),
-     *             emulator: variant('none', null),
-     *             random_state: variant('some', 42n),
-     *         }, CausalALEConfigType);
-     *         return $.return(Causal.ale(data, config));
-     *     }
-     * );
-     * ```
-     */
-    ale: causal_ale,
+    experiment: causal_experiment,
+    /** Design the real controlled trial that would validate an experiment result. */
+    designValidation: causal_design_validation,
     /** Type definitions */
     Types: CausalTypes,
 };