Skip to main content

Subsections of Configuration

Donor Configuration

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.

Inference Configuration

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.

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.