Configuration
Check supported settings and defaults before configuring each stage.
Check supported settings and defaults before configuring each stage.
| Key | Type/default | Contract |
|---|---|---|
schema_version |
string, 1.0 |
Config version. |
data_path |
string | Long CSV containing date, location, and Y or metric. |
date_format |
string or omitted | Explicit source date format. |
treatment_locations |
list | Treated identifiers, compared after string conversion. |
treatment_date |
string | Pre/post split; pair metrics and adaptive settings use only pre-period rows. |
max_donors |
integer, 10 |
Maximum complete recommendations per treated unit. |
min_correlation_threshold |
float, 0.7 |
Adds low-correlation warnings. |
max_rmse_threshold |
float or null | Adds high-RMSE warnings. |
donor_dominance_threshold |
float, 0.5 |
Adds dominance warnings for recommendation weights. |
min_excellent_donors |
integer, 3 |
Pool-summary threshold. |
min_good_donors |
integer, 5 |
Pool-summary threshold. |
mape_thresholds |
mapping | acceptable (default 30) controls high-MAPE warnings; other labels are retained compatibility settings. |
shapemap_file |
string or null | GeoPandas-readable vector file. |
shapemap_id_column |
string | Geography key in the vector file. |
output_dir |
string | Artefact directory. |
parallel |
boolean | Parallel pair scoring. |
n_jobs |
integer | Worker count; -1 uses all cores. |
The current donor stage always computes correlation, RMSE, MAPE, and DTW.
There are no active evaluation_metrics, pre_treatment_periods, min_donors,
limit_donor_pool, top_correlated_donors, acceptable_mape, or
correlation_thresholds keys.
Adaptive weights and thresholds are resolved during evaluation from the same
CSV load as pair metrics. Their scope is all geographies’ pre-treatment rows,
independent of treatment labels. At least two finite observations are required;
missing, infinite, or nonnumeric pre-period outcomes fail rather than triggering
silent defaults. donor_pool_quality.json records the inputs and settings.
Missing observation dates or a missing launch date fail before pre/post
classification, because undated rows cannot establish pre-treatment membership.
The shipped inference YAML is the canonical example. Active keys are listed
below; unknown non-sparse_sc_* keys are not comprehensively rejected, so a
misspelling can be ignored. Compare production configs with this table.
| Key | Type/default | Contract |
|---|---|---|
schema_version |
string, 1.0 |
Supported config schema. |
alpha |
float, 0.05 |
Finite numeric scalar strictly in (0, 1); booleans, strings and containers fail. |
data_path |
string | Input CSV for file mode. |
location_col_name |
string | Geography identifier column. |
date_col_name |
string | Period column. |
date_format |
string | Explicit pandas date format. |
outcome_col_name |
string | Numeric outcome column. |
covariate_col_names |
list or null | Numeric features summarised by mean over retained pre-treatment periods. |
treatment_unit_ids |
list | Treated geography identifiers. |
intervention_date_str |
string | Common launch period for every treated geography. Direct-API unit dates must equal intervention_date before cooldown. |
cooldown_periods |
non-negative integer, 0 |
Observed periods excluded after launch. |
measurement_start_date_str |
string or null | Optional explicit start; must agree with cooldown. |
duplicate_policy |
error, mean, sum |
Duplicate unit-period handling. |
missing_outcome_policy |
error, drop_unit, drop_period, impute_with_report |
Imputation stays within pre-treatment, cooldown and measurement windows; a unit/window without observations fails. |
min_pre_treatment_periods |
integer | Minimum pre-period observations when supplied. |
min_post_treatment_periods |
integer | Minimum measured post-period observations when supplied. |
estimator |
sparsesc |
Only implemented estimator selector. |
output_dir |
string | Artefact directory. |
create_plots |
boolean | CLI plot default. |
use_progress |
boolean, true |
Stage progress preference; --no-progress disables it. |
SparseSC runtime keys:
| Key | Default or role |
|---|---|
sparse_sc_model_type |
retrospective, prospective or prospective-restricted. |
sparse_sc_fast_estimation |
Selects SparseSC fast fitting path. |
sparse_sc_return_ci |
Requests placebo confidence intervals. |
sparse_sc_T0, sparse_sc_T1 |
SparseSC history-length controls; not cooldown semantics. |
sparse_sc_max_n_pl |
Positive integer cap; the old constructor-only limit of 1000 is removed. Native default is 10000. |
sparse_sc_placebo_seed |
Non-negative seed for sampled placebo assignments; default 110011. |
sparse_sc_level |
Requested interval level. |
sparse_sc_cv_folds |
Null for native leave-one-out or an integer >=2; requires enough samples in the smallest match-space fit. |
sparse_sc_scoring |
Null or r2, neg_mean_squared_error, neg_root_mean_squared_error, neg_mean_absolute_error. |
sparse_sc_gcv_mode |
Null, auto, svd or eigen; only valid with null CV folds. |
Assumption keys are run_assumption_checks, require_assumption_checks,
fail_on_assumption_error, parallel_trends_method, spillover_method, and
assumption_alpha. Regression and visual pre-trends and the interference screen
are advisory. require_assumption_checks: true requires an explicit
parallel_trends_method: placebo; regression, visual and the default regression
method are rejected when a required gate is requested. Disable the required
gate to retain raw pre-trend diagnostics without suppressing inference.
fail_on_assumption_error applies only to eligible placebo diagnostic errors.
The retained placebo gate is experimental, unchanged numerically and not a
test that establishes causal identification.
The ignored keys sparse_sc_lasso_max_iter, sparse_sc_lasso_tol,
lasso_selection, lasso_fit_intercept and lasso_normalize are retired;
supplying any now fails with an instruction to remove it. Match-space CV
controls are fast-path RidgeCV options and are rejected with full estimation,
including explicit null keys. They do not configure the full-path optimiser.
Method and match-space options use the same builder as the supported power
path. The native ten-fold cross-fitting rule and seed 110011 remain explicit.
For retrospective matching, the smallest training pool contains
N0 - ceil(N0/10) controls. Explicit CV folds cannot exceed that pool; R2
scoring needs two or more validation observations per fold. Null scoring uses
native negative MSE for leave-one-out and R2 otherwise. Other inference model
modes retain their existing native training semantics and require their own
design qualification.
There is no active treatment_col or end_date key. Define treatment through
treatment_unit_ids; trim the input panel to a pre-specified end date. Inference
also does not consume shapemap_file or shapemap_id_column; shapemap-backed
maps belong to the donor stage.
Several treated IDs form one joint group. Placebos use treated-sized subsets
of distinct controls, requiring at least as many controls as treated units.
Inference dispatch requires ten retained controls for the unchanged ten-fold
honest cross-fitting rule, independently of the treated-count constraint.
Data-policy drops can therefore make a formerly feasible panel ineligible.
sparse_sc_cv_folds configures fast-path match-space CV, not honest cross-fitting;
it cannot enable a pool with fewer than ten controls. Its own training-size
constraints and p-value resolution remain separate. Staggered
launches and dose-normalised inference are unsupported.
| 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.