Skip to main content

Power Configuration

Key Type/default Contract
schema_version string, 1.0 Config version.
data_path string Long CSV.
date_col, location_col, outcome_col strings Source columns; periods must be ISO date/time strings or dd/mm/yyyy.
treatment_locations list Treated units; numeric-looking strings are coerced to integers.
treatment_date ISO date string Split used to estimate the pre-period DGP.
duration list of integers Simulated post-period lengths. Alias: test_durations.
effect_sizes list of floats Relative injected lifts. Alias: effect_size.
alpha float, 0.05 Finite numeric scalar detection threshold in (0, 1); boolean, string and container values fail.
target_power float, 0.80 CLI MDE/report threshold; must be in (0, 1].
n_simulations positive integer, 1000 Attempts per grid row; booleans, strings and fractional counts fail before coercion.
effect_pattern string, constant constant, immediate, ramp, or decay.
random_seed integer or null Reproducible configuration seed.
power_dgp_rank integer or null Explicit SVD rank.
power_dgp_max_rank integer, 5 in CLI Automatic rank cap.
sparse_sc_max_n_pl positive integer, 100 Requested placebo cap.
sparse_sc_model_type string, retrospective Only supported power model; other requests fail.
sparse_sc_fast_estimation boolean, true Power requires the fast RidgeCV path; false requests fail.
sparse_sc_cv_folds integer or null Match-space CV folds >=2, or native leave-one-out default.
sparse_sc_scoring string or null r2, neg_mean_squared_error, neg_root_mean_squared_error, neg_mean_absolute_error, or native default.
sparse_sc_gcv_mode string or null auto, svd, eigen or native default; only with null CV folds.
parallel, n_jobs boolean, integer Grid-level CPU parallelism.
use_gpu boolean Optional unseeded DGP acceleration request.
use_progress boolean, true Stage preference; --no-progress overrides it.
output_dir string CSV and plot directory.

The calculator sorts parsed period columns chronologically before selecting pre-treatment outcomes. Timezone-aware, missing, or duplicate periods are rejected, including distinct labels that identify the same timestamp. Slash dates are strictly day/month/year, so convert month-first or other date strings to ISO before running the file-driven stage. date_format is not a power configuration key.

All non-treated CSV geographies enter the control pool; remove ineligible rows from the input. The direct Python calculator instead uses exactly its supplied treatment_units and control_units. Unknown, duplicated, missing, or overlapping identifiers fail before DGP fitting.

The selected pool must contain at least ten controls for the backend’s ten-fold honest cross-fitting procedure, in addition to having at least as many controls as treated geographies. The constructor rejects smaller pools before DGP fitting; extra undeclared panel rows do not count. No automatic fold reduction or qualified small-pool alternative is provided. This count check does not establish adequate placebo resolution, campaign power or calibration.

constant and immediate currently produce the same full effect in every period. ramp moves linearly from zero to the full effect. decay applies the full effect initially and a hard-coded exponential decay rate of 0.1 per period. Unknown patterns fail.

The direct calculator, CLI and recipe share the same supported estimator surface. Inference retains additional modes; power explicitly rejects a non-retrospective model or full-estimation request. It also rejects supplied sparse_sc_T0, sparse_sc_T1, sparse_sc_return_ci, sparse_sc_level and sparse_sc_placebo_seed, including null values: simulated windows and per-draw seeds belong to the calculator. Its Monte Carlo Wilson interval is distinct from a SparseSC effect interval.

Both stages share a builder for accepted method/CV settings. Honest cross-fitting remains ten folds with seed 110011. Match-space CV must fit the smallest held-out training pool; with ten controls, at most nine remain for retrospective fitting. R2 scoring additionally needs at least two observations in each validation fold. Null scoring means native negative MSE for leave-one- out, or R2 for explicit folds. The supported scorer subset works with continuous multi-output targets; other recognised sklearn names can be incompatible. See the RidgeCV contract.

sparse_sc_lasso_max_iter, sparse_sc_lasso_tol, lasso_selection, lasso_fit_intercept and lasso_normalize are retired and rejected because the governed fast learner does not consume them. Remove these keys.

The inference and power YAML files are independent. Match their estimator options and intended placebo caps explicitly; inference’s native default cap is 10000, whereas power defaults to 100 and bounds it by feasible assignments. Shared options do not import inference cooldown, covariates or assumption gates. Every new power row records estimator_settings. Older/non-default-setting rows should be regenerated for method provenance; this additive field does not change schema 2.0 numeric eligibility or certify calibration.

Supported boolean fields accept booleans or the established case-insensitive text forms (true/false, yes/no, on/off, t/f, y/n, 1/0). Numeric zero/one are rejected; a null uses the field’s default. Pipeline stages resolve these settings from their own YAML and explicit CLI overrides, so the chosen anchor does not change another stage’s progress preference. The direct power calculator copies its configuration before normalising flags. Semantic setting validation runs for selected pipeline stages; invalid settings in a skipped stage do not block selected stages. The canonical files must still exist, and the anchor file must be readable YAML.

Ordinary power/MDE eligibility requires zero failed draws. The former power_failure_rate_threshold key is retired and explicitly rejected; remove it rather than setting a different threshold. Power row schema 2.0 records conditional rejection and completion bounds separately from ordinary power. Regenerate schema 1.0 CSVs before using decision plots or MDE summaries.