Reference
Look up CLI and Python interfaces, configuration, and artefact contracts.
Look up CLI and Python interfaces, configuration, and artefact contracts.
GeoSC installs geosc and the compatibility alias geolift. Both dispatch to
the same parser.
| 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. |
| Option | Meaning |
|---|---|
--data PATH |
Overrides data_path. |
--create-plots |
Forces plot generation. |
--no-create-plots |
Disables plot generation. |
| 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. |
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.
Check supported settings and defaults before configuring each stage.
| 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.
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.
| 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.
| 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.
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.
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.
Interpret fields, diagnostic statuses, and limits in generated artefacts.
donor_eval_results.csvEach 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.jsonThe 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.
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.jsonSchema 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. |
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.jsonContains 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.
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.
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.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.
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:
Specialist classes are available from their modules rather than the package root:
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.
GeoLiftAnalyzerUse 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.
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.
For every production run retain:
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.
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:
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.
Use a MyST math directive for display equations that contain Markdown-sensitive operators or subscripts:
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.
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.