Configuration Reference

GeoSC uses flat YAML keys for its configuration.

The example below reflects the supported YAML shape. The data-config/ directory is a source-tree example asset, not a packaged runtime asset, so built wheel and sdist installs should replace those demo paths with user-owned config and data paths.

Inference Config Parameters

Below are the standard configuration keys used in geolift_analysis_config.yaml:

schema_version: "1.0"
data_path: "data-config/synthetic_geolift_multi.csv"
location_col_name: "location"
date_col_name: "date"
date_format: "%d/%m/%Y"
duplicate_policy: "error"
missing_outcome_policy: "error"
outcome_col_name: "Y"
treatment_unit_ids: [501, 502, 503]
intervention_date_str: "01/03/2023"
estimator: "sparsesc"
cooldown_periods: 0
# measurement_start_date_str: "08/03/2023"  # Optional; must agree with cooldown_periods if set.
covariate_col_names: ["covariate_1", "covariate_2"]
sparse_sc_model_type: "retrospective"
sparse_sc_fast_estimation: true
sparse_sc_level: 0.95
sparse_sc_return_ci: true
sparse_sc_max_n_pl: 1000
sparse_sc_placebo_seed: 110011
min_pre_treatment_periods: 12
min_post_treatment_periods: 1
run_assumption_checks: false
require_assumption_checks: false
fail_on_assumption_error: true
parallel_trends_method: "regression"
spillover_method: "correlation"
assumption_alpha: 0.05
output_dir: "outputs/multicell_geolift_analysis"
create_plots: true

Cooldown And Measurement Window

cooldown_periods excludes an initial post-launch transition window from effect measurement. It defaults to 0, which preserves the existing behavior where the measurement window starts on intervention_date_str.

Cooldown counts observed data periods, not calendar days. For daily data, cooldown_periods: 7 excludes seven daily observations. For weekly data, cooldown_periods: 2 excludes two weekly observations.

When cooldown is positive:

  • pre-treatment fit uses dates before intervention_date_str;
  • cooldown dates are excluded from the estimator-facing panel;
  • measurement post-periods start at the resolved measurement start date;
  • min_post_treatment_periods is checked after cooldown exclusion.

You may supply measurement_start_date_str explicitly, but if it is supplied with cooldown_periods, both settings must resolve to the same observed period. Positive cooldown shortens the measurement window and can reduce power.

sparse_sc_T0 and sparse_sc_T1 are SparseSC history-length settings. They are not cooldown controls.

All file-based and direct-data panels are canonicalised before validation. Date labels become a sorted, timezone-naive DatetimeIndex; malformed or timezone-aware labels, duplicate periods after parsing, and treatment dates absent from the outcome panel are rejected rather than coerced.

Estimator Identity

estimator: "sparsesc" is the only supported estimator selector and is also the default when the key is omitted. Historical values sdid, sc, did, and regsynth all executed this same SparseSC path; they are now rejected because their names implied implementations that were not present. Replace any such value with estimator: "sparsesc".

SparseSC Runtime Keys

GeoSC validates keys that start with sparse_sc_ so misspellings fail before the adapter falls back to defaults. Supported SparseSC runtime keys are:

  • sparse_sc_model_type
  • sparse_sc_fast_estimation
  • sparse_sc_return_ci
  • sparse_sc_T0
  • sparse_sc_T1
  • sparse_sc_max_n_pl
  • sparse_sc_placebo_seed
  • sparse_sc_level
  • sparse_sc_lasso_max_iter
  • sparse_sc_lasso_tol
  • sparse_sc_cv_folds
  • sparse_sc_scoring
  • sparse_sc_gcv_mode

sparse_sc_placebo_seed defaults to 110011 and must be a non-negative integer. It controls only the sampled-placebo branch used when sparse_sc_max_n_pl caps the feasible placebo combinations. Exhaustive enumeration is unchanged. Results persist the seed, placebo mode, requested count, possible count, and effective count so sampled inference can be replayed.

Existing non-prefixed lasso options such as lasso_selection, lasso_fit_intercept, and lasso_normalize keep their legacy behavior and are not part of the sparse_sc_* allowlist.

Data Contract Policies

Inference defaults are fail-closed:

  • duplicate_policy: "error" rejects duplicate location-date rows. Use "mean" or "sum" only when that aggregation is statistically intended.
  • missing_outcome_policy: "error" rejects incomplete outcome panels. Explicit alternatives are "drop_unit", "drop_period", and "impute_with_report".

Every inference run writes data_validation.json next to the result artifacts. Review it before interpreting lift. The artifact includes raw outcome value checks plus separate input-panel and model-panel quality summaries, so missing values hidden by explicit duplicate aggregation remain auditable.

Inference also writes geolift_results.json with schema_version and status. Treat ok as “the configured contract completed”, not as a proof of causal validity. Treat partial as “estimate available but interpretation metadata incomplete”, and treat failed as unusable for decision-making.

Assumption Gates

  • run_assumption_checks: false skips the parallel-trends diagnostic and advisory interference screen, but still writes assumption_validation.json with overall_status: "skipped".
  • require_assumption_checks: true makes only the gate-eligible parallel-trends diagnostic a hard result gate. A failed gate marks geolift_results.json as status: "failed".
  • fail_on_assumption_error: true treats parallel-trends validator exceptions as failed gates when checks are run. An interference-screen exception is recorded as indeterminate and remains advisory.
  • parallel_trends_method supports "placebo", "regression", and "visual".
  • spillover_method supports "correlation", "change", and "visual" for the advisory interference screen.

The interference screen reports signal, no_signal, or indeterminate and adds a result caveat where appropriate; it never changes result status or significance. Neither a signal nor no signal identifies treatment exposure or proves the presence or absence of spillover. A future hard interference gate would need a pre-specified exposure, network, or geographical-interference design; GeoSC does not implement one.

Power Config Parameters

Power analysis accepts the demo keys in data-config/power_analysis_config.yaml, including:

random_seed: 12345
alpha: 0.05
n_simulations: 300
sparse_sc_max_n_pl: 100
power_dgp_rank: null
power_dgp_max_rank: 5
power_failure_rate_threshold: 0.2
effect_pattern: "constant"
use_gpu: false

random_seed makes repeated runs with the same config reproducible. Each power_analysis_results.csv row records n_failed, failure_rate, valid, random_seed, simulation_seed, dgp_rank, dgp_explained_var, requested_max_n_pl, possible_placebos, effective_max_n_pl, dgp_backend, generation_backend, seeded_reproducibility_mode, and effect_pattern. Rows with valid: false exceeded the configured failure tolerance or had no successful simulations. power_failure_rate_threshold must be a finite number in [0, 1]; non-finite values are rejected at construction. When random_seed is set, GPU DGP estimation and GPU post-period generation are disabled so seeded CPU simulation draws are reproducible. The shipped demo config sets use_gpu: false to match this seeded reproducibility default.

The factor-model DGP supports SVD extraction only. power_dgp_rank controls the number of SVD factors, and power_dgp_max_rank caps automatic rank selection. GeoSC estimates VAR(1) dynamics on the selected factor series and stores the transition, intercept, innovation covariance, and initial factor distribution in the DGP metadata used for simulation. Automatic rank selection applies an additional effective cap so the selected rank is estimable by the VAR(1) regression on short pre-period panels. Explicit power_dgp_rank values that cannot support VAR(1) estimation fail with an actionable error instead of silently switching DGP families. Unsupported extraction methods such as pca are rejected rather than treated as aliases.

Generated post-period panels use the VAR(1) temporal parameters whenever they are present. Covariance matrices are symmetrized and regularized with a small diagonal floor; invalid factor dynamics or failed factor draws raise errors instead of falling back to diagonal covariance. Because the current GPU path does not implement the VAR(1) generator contract, post-period generation for estimator-produced power DGPs is reported as cpu_numpy_generator even when GPU SVD estimation was requested and available. Power values are Monte Carlo estimates, not guarantees; compare them with power_ci_lower, power_ci_upper, n_simulations, and failure_rate.

If a power-analysis design has fewer control units than treatment units the calculator now fails fast at construction with a ValueError rather than forwarding an infeasible placebo count to SparseSC. plot_power_curves filters rows with valid: false out of the decision plots (logging the count of excluded rows) and skips plot creation entirely when no valid rows remain.

Donor Config Parameters

Donor evaluation accepts donor_dominance_threshold in addition to the existing metric thresholds. donor_eval_results.csv includes rank, quality_band, warning_flags, and selected_weight. selected_weight is a normalized recommendation weight within the ranked donor set; it is not a fitted SparseSC weight. The stage also writes versioned donor_pool_quality.json with threshold settings, warning-flag counts, selected-weight concentration, effective donor count, and by-treatment quality summaries.

The maintained artifact contract is enforced by release preflight and described in the output sections of API Reference, Interpreting Results, and the stage-specific how-to guides.

Shapemap Keys

Donor maps use:

shapemap_file: "/path/to/markets.geojson"
shapemap_id_column: "id"

shapemap_file may point to any GeoPandas-readable vector file. The configured shapemap_id_column must contain IDs that exactly match the treatment and donor unit IDs in the analysis data. For UK production workflows, postcode district IDs such as SW1A or postcode area IDs such as SW can be used when the data and shapemap are both normalized to the same geography. See How to Use Shapemaps for examples.

Release Certification Boundary

scripts/verify_release_candidate.py includes a named statistical certification gate for the 0.3.0 beta. The gate runs the maintained wrapper tests for SparseSC parity, effect recovery, treatment timing and orientation, artifact parity, result uncertainty and placebo semantics, donor semantics, power semantics, assumption-validator metadata, and release-preflight schema regressions.

Passing the gate means the tested GeoSC wrapper contract is intact for the declared SparseSC operational surface. It does not prove donor exchangeability, absence of spillovers, correct campaign timing, outcome suitability, credible power DGP assumptions, or acceptable placebo p-value granularity for a specific measurement decision.