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.