Reference

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.

Configuration

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; only pre-period rows are scored.
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.

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.
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 Optional covariates passed to the loader.
treatment_unit_ids list Treated geography identifiers.
intervention_date_str string First observed treated period.
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 Incomplete-panel handling.
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.

SparseSC runtime keys:

Key Default or role
sparse_sc_model_type SparseSC model type, normally retrospective.
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 Maximum placebo assignments used.
sparse_sc_placebo_seed Non-negative seed for sampled placebo assignments; default 110011.
sparse_sc_level Requested interval level.
sparse_sc_lasso_max_iter, sparse_sc_lasso_tol Forwarded as fast-path CV options; the RidgeCV-backed path may ignore them. They do not configure the full path.
sparse_sc_cv_folds, sparse_sc_scoring, sparse_sc_gcv_mode Supported adapter controls.

Assumption keys are run_assumption_checks, require_assumption_checks, fail_on_assumption_error, parallel_trends_method, spillover_method, and assumption_alpha. Only the parallel-trends diagnostic is gate-eligible. The interference screen is always advisory.

The non-prefixed compatibility keys lasso_selection, lasso_fit_intercept, and lasso_normalize are forwarded only when the fast path is selected. Their support depends on the installed scikit-learn API; prefer the documented sparse_sc_* controls for new configurations.

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.

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.
treatment_locations list Treated units; numeric-looking strings are coerced to integers.
treatment_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 Detection threshold; must be in (0, 1).
target_power float, 0.80 CLI MDE/report threshold; must be in (0, 1].
n_simulations integer, 1000 Repetitions per grid row.
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.
power_failure_rate_threshold float, 0.20 Maximum valid row failure rate.
sparse_sc_max_n_pl positive integer, 100 Requested placebo cap.
parallel, n_jobs boolean, integer Grid-level CPU parallelism.
use_gpu boolean Optional unseeded DGP acceleration request.
output_dir string CSV and plot directory.

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 CLI power path forwards a deliberately narrower SparseSC configuration than inference: fast estimation, placebo cap, DGP controls, seed, GPU request, and progress state. Inference options such as cooldown, assumption checks, CI level, and lasso controls are not inherited.

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 Parseable date or time label; inference canonicalises to a sorted, timezone-naive DatetimeIndex.
Outcome Numeric and finite under the configured data policy.
Covariates Optional inference columns named by covariate_col_names.

Power currently uses DataFrame.pivot, so duplicate unit-period rows fail and missing cells remain in the wide matrix. It does not apply inference’s explicit duplicate or missing-outcome policies. Validate and canonicalise the panel before power analysis.

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.

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.

Output Schemas

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

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.

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.

Inference Result Schemas

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 Gate summary.
warnings, errors, caveats Interpretation controls.

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. assumption_validation.json schema 1.1 records gate-eligible parallel-trends status plus an advisory interference screen with signal, no_signal, or indeterminate status.

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 (1.0).
target_power CLI planning threshold copied from YAML.
effect_size, duration, alpha Simulated grid and detection threshold.
power n_significant / n_successful.
power_ci_lower, power_ci_upper Wilson interval using alpha as the interval tail setting.
n_simulations, n_successful, n_significant, n_failed Monte Carlo counts.
failure_rate, failure_rate_threshold, valid Failure diagnostics. valid 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 Explicit detection and denominator labels.
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.

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

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.

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.

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.

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.