Skip to main content

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.