Skip to main content

Subsections of Reference

CLI Reference

GeoSC installs geosc and the compatibility alias geolift. Both dispatch to the same parser.

geosc {power,donors,infer,pipeline} --config PATH [shared options]

Shared options

Option Meaning
--config PATH Required YAML path. For pipeline, it is an anchor in a directory containing all three canonical configs.
--output-dir PATH Overrides a stage output directory, or the pipeline output root.
--jobs N Overrides n_jobs; for power and donors it also enables parallel execution.
--use-gpu Requests supported GPU work. It does not enable GPU inference.
--no-progress Disables progress displays.
--quiet Reduces non-critical terminal output; artefacts are still written.

Inference-only options

Option Meaning
--data PATH Overrides data_path.
--create-plots Forces plot generation.
--no-create-plots Disables plot generation.

Pipeline-only options

Option Meaning
--skip-power Omits the power stage.
--skip-donor Omits donor evaluation.
--only-inference Omits both design stages.
--report / --no-report Enables or disables compact Markdown and HTML reports. Reports are enabled by default.

Exit codes

0 means the requested stage completed under its software contract. 1 means a stage failed during validation or execution, including inference returning status: failed. 2 means argument parsing or initial CLI configuration resolution failed. An ok exit does not establish causal validity. See Errors and Exit Codes.

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.

Errors and Exit Codes

Signal Meaning Recovery
Exit 0 Command completed its software contract. Inspect artefact statuses and diagnostics.
Exit 1 A resolved stage failed during validation or execution, or inference returned failed. Read the terminal error and stage logs; no reportable result is available.
Exit 2 Argument parsing or initial CLI configuration resolution failed. Correct the command syntax or config path/content.
GeoLiftConfigError Config file, value, or supported SparseSC key is invalid. Correct the named key or path.
GeoLiftDataError / analysis data error Panel cannot be prepared under the selected policy. Fix identifiers, dates, duplicates, gaps, non-finite values, or windows.
GeoLiftResultsError SparseSC output cannot satisfy the result contract. Preserve logs and inspect estimator output; do not substitute zeros.
GeoLiftPlotterError Plot construction failed. Use JSON results only after verifying they completed; fix map or plotting inputs separately.
Power valid: false No successful simulations or failure rate above threshold. Do not use the row for MDE; diagnose simulation failures.
Inference partial Estimate exists with warnings or incomplete uncertainty. Resolve or disclose every warning before use.
Inference failed Required result fields or gates failed. Do not report an effect; redesign or repair.

Unknown non-sparse_sc_* YAML keys are not comprehensively rejected. If a setting appears ineffective, compare it with the exact stage configuration reference rather than assuming it was applied.

Input Schema

Inference and power

Both stages consume a long CSV and pivot it to a unit-by-period outcome matrix.

Field role Required property
Geography Stable scalar identifier; treatment IDs must match after the stage’s documented coercion.
Period Both stages sort unique, timezone-naive dates; inference uses its configured date format, while power accepts ISO date/time strings and dd/mm/yyyy.
Outcome Numeric and finite under the configured data policy.
Covariates Optional inference columns named by covariate_col_names.

Inference requires every treated unit’s supplied treatment date to equal the common intervention_date. This is checked before cooldown periods are removed and estimator-facing treatment dates are moved to the common measurement start. Staggered launches and inconsistent global/unit dates are rejected, including when cooldown is zero. The control count must be at least the treated count; this alone does not satisfy cross-fitting or p-value-resolution requirements.

Fitting requires at least ten effective never-treated controls because the backend uses ten honest cross-fitting folds. Inference counts retained controls after preparation, including missing-data drops; power counts only the selected controls. Preparation can inspect a smaller panel, but inference dispatch rejects it before fitting, and power rejects it before fitting its DGP. No automatic fold reduction or small-pool estimator is supplied. Ten is an operational minimum, not a statistically qualified design size.

impute_with_report interpolates by observed-period position separately within the pre-treatment, cooldown, and measurement windows, filling endpoints from the same window. It rejects a unit/window with no observed outcome and never borrows across a boundary. This policy can affect estimates and does not establish that the missingness process is ignorable. Sum aggregation preserves an all-missing unit-period as missing so the chosen missing-outcome policy can handle it.

CSV covariates are baseline summaries. For each feature, GeoSC averages duplicate records within each retained pre-treatment unit-period, then averages the observed period values within each geography. Missing covariate observations are skipped; every retained unit/feature needs at least one observed numeric value, and infinity is rejected. Cooldown, post-treatment, and dropped outcome periods do not contribute. Static covariates therefore retain their value, while time-varying covariates become pre-period means. The direct API expects an already prepared finite numeric baseline table with the outcome panel’s index; the caller is responsible for its temporal provenance. Accepted direct baseline entries are normalised to float, matching file means; the caller’s original table is preserved.

Power uses DataFrame.pivot, so duplicate unit-period rows fail and missing cells remain in the wide matrix. Its shared calculator parses dates, rejects missing, timezone-aware, or duplicate periods, and sorts columns with their values before selecting the pre-period. Distinct labels that parse to the same timestamp are duplicates. Slash dates use the explicit %d/%m/%Y format; convert other string formats before use. The direct API also accepts naive datetime objects. Numeric period positions are not dates.

The direct power API requires unique, non-missing panel identifiers and unique, disjoint treatment_units and control_units present in that panel. Only those declared rows enter DGP fitting and simulation; their original row order is retained and caller-owned inputs are copied. File-driven power treats every non-treated input geography as a control, so its CSV must contain only eligible geographies.

Power does not apply inference’s explicit duplicate or missing-outcome policies. Missing or non-finite values in the eligible pre-period are rejected by DGP validation. Filtering eligible units and sorting dates do not establish a regular observation cadence or statistical calibration.

Donor evaluation

The donor stage expects literal source columns date, location, and either Y or metric. It uses rows before treatment_date. Each treatment-donor pair is aligned on unique parsed dates; duplicates or insufficient finite overlap produce incomplete metrics.

Adaptive scoring uses all geographies’ pre-treatment rows from the same parsed data used for pair evaluation, independently of treatment labels. At least two finite pre-treatment observations are required. The run records its resolved statistics and weights in donor_pool_quality.json.

Store the panel frequency, timezone policy, outcome unit, currency, attribution logic, geography version, extract timestamp, source owner, and row-count checks alongside the CSV. These are project data-governance requirements, not fields GeoSC can infer.

The shared inference CSV loader uses round-trip floating-point parsing to preserve values serialised from an in-memory panel. Equivalent direct and file inputs therefore avoid parser-induced rounding differences; numerical stability still depends on fit.

Subsections of Output Schemas

Donor Artefact Schemas

donor_eval_results.csv

Each row is a treated-candidate donor pair. Maintained columns include treatment and donor IDs; composite, fit, correlation, and seasonality scores; design-stage recommendation weight and role; rank; quality labels; warnings; metric failure reasons; correlation and its p-value; RMSE, percentage RMSE, MAPE, DTW; and metrics_complete.

Score normalisation and ranking occur within each treated geography. Cross- treatment score values are therefore not a common absolute scale.

donor_pool_quality.json

The shared JSON persistence contract applies: nested non-finite metrics become null, supported values are complete, and unsupported payloads fail explicitly. The JSON file is atomically replaced; the CSV and JSON pair is not a transaction.

Schema 1.0 records run configuration, an overall summary, and by_treatment summaries. Summary fields include recommendation counts, quality distribution, warning and metric-failure counts, weight role, maximum weight, dominant donor count, effective donor count, score and correlation summaries, strength score, and quality_assessment.

run_config.adaptive_scoring records scope, treatment_date, n_observations, outcome_mean, outcome_std (sample standard deviation), coefficient_of_variation, metric_weights, rmse_thresholds, and dtw_thresholds. The scope is all_geographies_pre_treatment; each observed row contributes equally to these statistics. The existing weight branch uses standard deviation divided by mean, with a value of one when the mean is zero. These adaptive thresholds are recorded settings, not calibrated acceptance tests; the separate explicit quality-screen thresholds retain their role.

quality_assessment is a deterministic screening label derived from configured thresholds. It is not a test of exchangeability and does not guarantee good SparseSC fit.

run_config.dtw_radius is the fixed approximation search radius (1), dtw_backend identifies the effective FastDTW callable module, and dtw_local_cost is absolute_difference. Pair-specific standardisation precedes approximate alignment and distance is divided by finite overlap count. The radius does not bound calendar lag. These fields are additive in schema 1.0.

Inference Result Schemas

JSON persistence contract

Analysis, validation and donor JSON artefacts use strict JSON: non-finite Python/NumPy numbers and pandas missing scalars become null, including inside arrays and nested containers. null means unavailable; it does not establish the reason or change the recorded result status. Finite estimates, interval bounds and other supported values retain their values. Finite extended-precision NumPy floats that overflow or underflow Python’s float range raise an error rather than becoming unavailable or zero.

Lists and NumPy arrays are written in full, without truncation or flattening. DataFrames retain split orientation (index, columns, data); Series retain a mapping from labels to values. Dates and times use ISO strings. JSON object keys are strings: supported scalar and date/time keys are converted explicitly. Duplicate Series labels, keys that collide after conversion (such as 1 and "1"), non-finite keys and unsupported values raise an error rather than silently discarding or stringifying data. Tuple values become JSON arrays; tuple keys and arbitrary Python objects are unsupported.

The diagnostics whitelist still omits raw fitted matrices and frames; their existing availability metadata remains. Accepted containers have no artificial size cap, so callers remain responsible for the size of explicitly supplied payloads. Historical files with non-standard NaN/Infinity tokens or truncated data must be regenerated from the original analysis inputs.

All analysis payloads are converted before any existing artefact is replaced. Each JSON file is written to a unique temporary file and atomically replaced; failed writes clean up their temporary file and preserve that destination. The artefact family is not a transaction: an I/O failure after an earlier successful replacement can leave files from different runs. JSON configuration saves reject non-finite settings rather than turning them into null, and serialisation errors leave the existing configuration file intact.

geolift_results.json

Schema 1.0 contains the primary unscaled result:

Field Contract
status ok, partial, or failed.
estimand att_unscaled.
att Average post-period treated-minus-counterfactual effect in outcome units.
p_value Two-sided in-space placebo p-value for the average effect.
p_value_method in_space_placebo.
n_placebos, max_n_placebos, possible_placebos, p_value_placebo_mode, placebo_seed, p_value_granularity Finite reference-set metadata.
ci_lower, ci_upper, ci, ci_source Unscaled SparseSC placebo interval or explicit unavailability.
se / se_available No estimator-provided standard error is claimed.
se_approx_from_ci Optional normal approximation from interval width; not a sampling SE.
significance_available, significant Detection availability and p_value < alpha flag.
analysis_window Launch, cooldown, and measurement metadata.
assumption_status, assumption_required, assumption_checks_completed Diagnostic/gate summary; advisory never establishes identification.
warnings, errors, caveats Interpretation controls.

Rendered inference contract

CLI, recipe and pipeline summaries lead with status, errors and warnings. A failed or unknown status, non-empty errors, missing unscaled estimand or non-finite ATT withholds primary inference. Otherwise, significance_available and the stored significant flag determine the displayed decision. An unavailable decision is not reported as non-significance; a retained finite p-value is explicitly diagnostic when significance is unavailable.

The nested ci object supplies canonical lower, upper and level values. Rendering requires ci.available: true, ci.source: sparsesc_unscaled_placebo, ci_source: unscaled, finite ordered bounds and a numeric level strictly in (0, 1). For ci.level: 0.8, the label is 80% CI for average ATT (unscaled). Top-level bounds alone do not establish availability or level, and scaled diagnostics never replace the primary interval. Unavailable intervals retain their recorded unavailable_reason when present.

plot_results() rejects failed or incomplete primary results. Partial plots show status, warnings and uncertainty/significance limitations. The horizontal band represents the interval for the average ATT, not pointwise or simultaneous coverage of the period-by-period effect path. Older incomplete dictionaries must be regenerated; these presentation checks do not change schema 1.0 or the estimator’s numerical output.

geolift_diagnostics.json

Contains pre-period RMS effect and p-value, scaled post-effect diagnostics, period effects, fitted donor-weight summaries, synthetic-control availability, assumption state, analysis window, and warnings/errors. Scaled effects are not interchangeable with the unscaled top-level ATT and interval.

Validation artefacts

data_validation.json records file and model panel construction. When imputation is used, imputation.method is linear_interpolate_within_analysis_windows and imputation.windows records affected-cell counts, period counts, and start/end dates for pre_treatment, cooldown, and measurement. Input missing counts remain available after preparation. When CSV covariates are supplied, covariates records method: pre_treatment_period_mean, the intervention date, retained pre-period count, missing pre-value count, and missing-value handling rule. These are additive fields in schema 1.0.

assumption_validation.json uses schema 1.2. Regression and visual pre-trend checks and the interference screen have gate_eligible: false, with signal, no_signal or indeterminate statuses. A regression signal concerns mean raw unit slopes, not the fitted synthetic trajectory. An unavailable or failed advisory diagnostic remains visible without changing estimator status or significance availability.

Only the experimental pre-period placebo method can have gate_eligible: true and pass, fail, error or skipped status. Its numerical procedure is unchanged; passing means only that its configured discrepancy criterion was met. It does not establish causal identification or calibrated error rates.

When checks ran without an eligible gate, overall_status is advisory and overall_valid is null. Otherwise the overall status reflects eligible placebo checks, or is skipped when none ran. overall_valid refers only to that diagnostic gate. all_checks_completed concerns eligible gate checks when present, otherwise advisory checks; an indeterminate check is incomplete. Remove required-gate requests from regression/visual configurations, or explicitly request parallel_trends_method: placebo. Regenerate schema 1.1 artefacts before current release validation.

Pipeline Report Schema

The pipeline writes geolift_pipeline_report.md and geolift_pipeline_report.html. Each identifies the three config paths and summarises available stage artefacts.

The power section reports grid-based MDE by duration at configured target_power and excludes rows where valid is false. The donor section lists the five highest composite-score rows per treatment from the CSV. The inference section reports available ATT, p-value, interval, and assumption status.

These reports are convenience summaries. They do not contain the full data validation, power failure diagnostics, donor pool quality JSON, assumption checks, or sensitivity evidence. Audit and interpret the source artefacts.

Power Analysis Results Schema

power_analysis_results.csv has one row per effect-size and duration pair.

Field Meaning
schema_version Row contract version (2.0); older rows are withheld from decision consumers.
estimator_settings Deterministic JSON recording effective native method/CV/defaults, match-space learner, cross-fitting folds/seed, T0/T1, placebo cap and effect-CI request. Additive schema 2.0 provenance.
target_power CLI planning threshold copied from YAML.
effect_size, duration, alpha Simulated grid and detection threshold.
power n_significant / n_simulations, available only when every draw succeeds.
conditional_power n_significant / n_successful; unavailable when no draws succeed.
power_all_attempt_lower_bound, power_all_attempt_upper_bound n_significant / n_simulations and (n_significant + n_failed) / n_simulations; completion bounds, not confidence intervals.
power_ci_lower, power_ci_upper Wilson interval for a complete run, using alpha as the tail setting; unavailable if any draw fails.
n_simulations, n_successful, n_significant, n_failed Monte Carlo counts.
n_invalid_p_values, n_estimation_failures Invalid estimator output versus generation/estimation failures; their sum equals n_failed. Failure categories retained from the previous schema.
failure_rate, valid Failure diagnostics; valid requires zero failures. It does not validate DGP plausibility.
random_seed, simulation_seed, placebo_seed_root, placebo_seed_strategy Reproducibility metadata.
dgp_rank, dgp_explained_var, dgp_factor_dynamics Fitted DGP metadata.
requested_max_n_pl, possible_placebos, effective_max_n_pl, p_value_placebo_mode Placebo support.
dgp_backend, generation_backend, seeded_reproducibility_mode Execution metadata.
effect_pattern, effect_baseline, effect_full_absolute, effect_baseline_definition Injection contract.
detection_rule, power_denominator Strict detection rule and primary denominator all_simulations.
warnings Semicolon-delimited row warnings.

Direct calls to SparseSCPowerCalculator.calculate_power() do not add the CLI’s target_power column; target power affects MDE selection, not simulation.

New rows use estimator_settings.model_type: retrospective, fast: true and match_space: ridge_cv. cv_options records explicit settings with null native defaults for cv, scoring and gcv_mode. Honest cross-fitting uses ten folds and seed 110011; T0, T1, max_n_pl and ret_CI: false describe the simulated native call. Per-draw placebo seeds remain described in the existing row seed fields. This does not capture every private solver detail or prove calibration.

Older schema 2.0 rows can lack this new provenance. Numeric decision eligibility is unchanged; regenerate rows when method provenance is required, especially if earlier non-default settings were supplied and silently ignored.

A successful draw must return a finite real numeric p-value in [0, 1]. Missing values, arrays, strings and booleans are invalid outputs. Valid zero and one are retained, and significance uses the original scalar’s strict p_value < alpha comparison. Counts and warnings distinguish invalid p-values from execution failures. If any draw fails, ordinary power and its primary interval bounds are NaN in the DataFrame and empty cells in the CSV. The row is valid: false and cannot produce ordinary plots or MDE recommendations. The conditional rejection rate remains diagnostic; all-failed rows have unavailable conditional rates and all-attempt completion bounds [0, 1].

Completion bounds describe the observed attempts with unknown failed-draw rejection outcomes. They do not include Monte Carlo uncertainty or bound true population power. With no failures they collapse to the observed rejection rate, although its Wilson interval still has sampling width.

The retired failure_rate_threshold output is absent. Remove the retired power_failure_rate_threshold input and regenerate old results. Decision consumers require schema 2.0, complete positive whole attempt counts, matching success counts, zero failures, true validity, and finite numeric primary fields. They normalise accepted CSV numbers before sorting, comparisons and plotting; unsupported or malformed rows remain excluded even with a stale true flag.

Python API Reference

The package root exports the following maintained names:

Name Purpose
__version__ Installed GeoSC version.
GeoLiftAnalyzer File-based or direct-data SparseSC analysis façade.
load_config Load YAML or JSON and optionally validate the common config contract.
load_and_prepare_data Prepare a long input CSV for inference.
process_sparse_sc_results Convert a SparseSC result into result and diagnostic dictionaries.
plot_actual_vs_synthetic Plot observed and synthetic outcome paths.
validate_geolift_dependencies Check required import availability.
GeoLiftConfigError Configuration error.
GeoLiftDataError Data loading or panel error.
GeoLiftResultsError SparseSC result-processing error.
GeoLiftPlotterError Plot construction error.

Import from geolift:

from geolift import GeoLiftAnalyzer, load_config

Specialist classes are available from their modules rather than the package root:

from geolift.donor_evaluator import DonorEvaluator
from geolift.power import SparseSCPowerCalculator

SparseSCPowerCalculator(outcomes_df, treatment_units, control_units, intervention_date, config=None) copies its input and retains only the declared treated and control geographies in their source row order. Supply unique, non-missing identifiers present in the panel, with disjoint groups. Period columns may be naive datetimes, ISO date/time strings, or day-first dd/mm/yyyy strings; the calculator rejects invalid or duplicate periods and sorts dates with their outcomes before DGP fitting. Other string formats must be converted explicitly. Use a naive pandas.Timestamp for intervention_date.

calculate_power() requires a finite numeric scalar alpha in (0, 1) and parses its parallel flag explicitly. The calculator copies and normalises supported boolean settings before fitting. Invalid p-values count as failed draws, with separate invalid-output and execution-failure counts; successful draws retain the original scalar for the strict significance comparison. Ordinary power and its interval require zero failed attempts. Otherwise they are NaN, while conditional_power and all-attempt completion bounds remain diagnostic. Simulation counts must be positive integers before coercion. The former failure-rate threshold key/recipe argument is removed; power rows use schema 2.0, and old CSVs must be regenerated for recommendations. Inference configuration and standalone result processing also validate alpha. Strings such as "0.05" are rejected as thresholds; use numeric 0.05.

Power supports the retrospective fast RidgeCV path. Its config accepts sparse_sc_model_type, sparse_sc_fast_estimation, sparse_sc_max_n_pl, sparse_sc_cv_folds, sparse_sc_scoring and sparse_sc_gcv_mode. Unsupported methods, simulation-owned history/CI/seed keys and inactive lasso controls fail before DGP fitting. Accepted method/CV options share inference’s builder and are recorded in the JSON estimator_settings column. Inference’s additional methods, covariates, windows and assumption checks are not a power-workflow equivalence claim. See the power config contract for supported values and migration.

SparseSC fitting requires at least ten effective never-treated controls under the backend’s unchanged ten-fold honest cross-fitting rule. The power constructor checks its selected controls before DGP fitting. Analyzer preparation can inspect smaller panels, but dispatch rejects them before native fitting, including after data-policy drops. An undersized pre-period placebo diagnostic returns unavailable (passes=None). Regression/visual trend methods retain their own requirements. This minimum does not qualify match-space CV options, p-value resolution or statistical calibration.

GeoLiftAnalyzer

Use GeoLiftAnalyzer(config_path=..., data_path=..., config=...) for file mode. The optional config mapping overrides top-level keys after file loading. Use the constructor’s direct-data arguments for an already prepared wide outcome panel. run_analysis() returns the main result mapping and writes artefacts for file-based runs. plot_results() writes the maintained inference plot.

The plot requires a non-failed, finite att_unscaled result and records partial status and limitations. Its band uses the recorded nested ci availability, source, level and bounds, and describes average ATT uncertainty, not pathwise coverage. Missing metadata never creates a default 95% label or a scaled fallback. Failed/incomplete primary results raise GeoLiftAnalyzerError when plotting. The estimator and returned inference schema are unchanged.

File covariates are means over retained pre-treatment periods. Direct covariates_df inputs are already prepared finite numeric baseline tables; callers must exclude post-treatment information before constructing them. Both input paths isolate imputation within pre-treatment, cooldown, and measurement windows, rejecting a unit/window with no observed outcome.

DonorEvaluator resolves adaptive settings when evaluate_donors() loads the data. Before evaluation those settings are unresolved. The specialist calculate_adaptive_thresholds helper accepts prepared post/outcome data, selects pre-treatment rows, and performs no file read.

Stability boundary

The table above describes the public root exports declared by geolift.__all__. Other modules are usable but may have a narrower compatibility contract. The vendored sparsesc package is not a GeoSC public API.

Reproducibility

For every production run retain:

  • GeoSC version and Git commit when run from source;
  • Python version and dependency environment;
  • exact YAML files and CLI command;
  • input file hash, extract timestamp, and geography version;
  • output artefacts and logs;
  • all random seeds and reported backend fields;
  • eligibility, exclusions, estimand, and window decisions.

Inference defaults sampled-placebo work to sparse_sc_placebo_seed: 110011. Power uses random_seed to spawn per-grid seeds and then per-simulation placebo seeds. Repeated seeded CPU runs with identical inputs and configuration are designed to reproduce their simulation rows. Parallel and sequential seeded runs share the configuration-seed strategy.

When a power seed is set, GPU DGP estimation and generation are disabled. An unseeded GPU run is performance-oriented and should not be treated as bitwise reproducible. Floating-point results can also vary across platforms and library versions; preserve the environment where exact replay matters.

Placebo sampling is reproducible only when the seed and eligible unit ordering are unchanged. Record possible_placebos, effective_max_n_pl, mode, and seed.

Documentation figures

The counterfactual, placebo and workflow SVGs share one illustrative panel: seed 29, one treated geography, 49 controls, 40 pre-period days, three cooldown days and 17 measured days. The treated geography’s untreated trajectory is a convex mix of three generated controls with added noise; four outcome units per day are injected after launch. Control outcomes include generated post-launch shocks. This deliberately constructed example is not a calibration study.

Rebuild the figures from a source checkout with the declared dependencies:

python scripts/build_docs_figures.py
python scripts/sync_docs_site.py
hugo --source docs-site --panicOnWarning

The script makes one native inference call after GeoSC resolves the cooldown. It retains honest placebo means from that call rather than reconstructing them from non-honest control predictions. It checks that the plotted measured gap averages to the reported ATT and that the displayed two-sided add-one p-value matches the native result. It performs no power grid or calibration study.

The numerical source records the seed, configuration summary and plotted values, with null for the excluded cooldown predictions. The native learner retains its documented deterministic CV seeds; no capped-placebo sampling is needed for this exhaustive single-treatment run. Numerical results can vary with dependency versions; regenerate all three figures together instead of mixing runs. Stable SVG settings omit timestamps and preserve text labels for browser zoom and accessibility.

Mathematical notation

Use a MyST math directive for display equations that contain Markdown-sensitive operators or subscripts:

```{math}
x_i + y_i = z_i
```

Sphinx reads the directive directly. The synchroniser converts its opening fence to math for Relearn’s native renderer, preserving the TeX body. The verified website build uses Hugo Extended 0.169.0 and Relearn 9.4.0, which renders math during the build. No custom client-side MathJax loader is needed.

Vendored Dependencies

GeoSC vendors Microsoft’s SparseSC under src/sparsesc/ from https://github.com/microsoft/SparseSC at upstream commit 3b4d2ebd87b41fc8e0ec3e97fcb2be1b689275c0. It is a governed integration fork. The authoritative local modifications and update procedure are recorded in src/sparsesc/PROVENANCE.md.

The maintained inference surface uses a common launch, equal unit weights for the group effect, and treated-sized subsets of distinct physical controls. Private staggered and dose-normalised requests are rejected. The fork also has pre-existing RidgeCV match-space and zero-RMSPE scaling changes; it is not numerically interchangeable with the pinned upstream implementation.

Changes to the vendored tree require a provenance update and wrapper-boundary verification. It is excluded from first-party formatting and typing checks. scripts/verify_release_candidate.py exercises the maintained integration surface; passing that gate does not validate a client design.

src/sparsesc/utils/AzureBatch/ remains part of the governed fork. Removal requires a separate SparseSC provenance-backed phase.

src/synthdid/, if retained in a checkout, is not used by the primary GeoLiftAnalyzer workflow and is not a documented estimator option.

SparseSC retains its upstream MIT licence. Both archives include the pinned upstream notice at src/sparsesc/LICENSE (wheel package path sparsesc/LICENSE) and PROVENANCE.md; wheel licence metadata also carries the notice. GeoSC-owned code remains proprietary under the root LICENSE.

The documentation website uses Relearn 9.4.0 with its build-time KaTeX math renderer. Website assets retain the Relearn licence and KaTeX licence. These website dependencies do not change the packaged analytical estimator or GeoSC’s proprietary terms.