GeoSC is a Python toolkit and command-line interface (CLI) for designing and
analysing geo-level marketing experiments with SparseSC synthetic control.
It supports three operational stages: power analysis, donor screening, and
inference. The stages share an outcome panel and design decisions, but their
artefacts are not automatically passed from one stage to the next.
Use GeoSC only when the treated geography, eligible donor pool, treatment
timing, outcome definition, and contamination risks can be defended. A
successful command or a small p-value does not establish those conditions.
Comparing methods: read method comparisons
before comparing GeoSC MDEs or effects with TBR, GeoX, or matched markets.
Repo-local example assets such as data-config/ only work from a source
checkout. Built distributions install the Python package and CLI but do not
ship data-config/, recipes/, or shapemap/.
Subsections of GeoSC 0.4.0 Documentation
Explanation
Understand the methods, assumptions, and interpretation limits of GeoSC.
GeoSC reports an unscaled average post-period treated-minus-counterfactual
difference. Calling it causal requires more than estimator completion.
For treated set and measured post periods , the
target can be written conceptually as
The observed treated outcome supplies . SparseSC estimates the
unobserved from eligible donor outcomes.
A causal interpretation needs a stable outcome definition; treatment timing
and assignment measured correctly; donors unaffected by treatment; no
uncontrolled geography-specific shock aligned with launch; adequate pre-period
support for the counterfactual; and an estimand whose geography and period match
the business question. These conditions are design arguments, not outputs of
the optimiser.
GeoSC’s raw pre-trend comparison is advisory because it compares unweighted
group-mean slopes. Synthetic control instead fits a donor combination: treated
slopes near two can be matched by mixing donors with slopes zero and four,
even when most donors have slopes near zero and the raw mean comparison rejects.
This counterexample establishes a mismatch between the raw test and synthetic
matchability; it does not establish that the constructed design is causally valid.
Prespecify held-out synthetic-fit checks for model adequacy and keep the causal
identification argument separate. The distinction between a weighted comparison,
pre-intervention validation and contextual requirements is discussed in
Abadie’s methodological review.
Neither raw-trend non-rejection nor good synthetic fit proves exchangeability
or rules out launch-aligned confounding.
Only GeoSC’s experimental pre-period placebo diagnostic can be explicitly
required as an operational gate. Its procedure is unchanged and is not
calibrated here; passing it does not establish identification. The interference
screen is advisory and has no exposure model. Power addresses detection under
a simulated DGP, not identification. State each evidence source separately.
Cooldown, Seasonality, and Anticipation
Cooldown excludes observed periods between launch and measurement. It is useful
when response builds gradually, attribution matures, or short-term launch noise
is outside the estimand. It also removes data and can reduce power.
GeoSC counts observed periods. With daily data, cooldown_periods: 7 excludes
seven observed days; missing dates make that different from seven calendar
days. The resolved analysis window is persisted in validation and result
artefacts.
Cooldown does not fix anticipation. If customers or media respond before the
declared launch, the pre-period is contaminated. Move the intervention boundary
only when the behavioural timing supports it, not to improve fit.
Power’s native CLI does not apply the inference cooldown resolver. Set the
power split and simulated duration to represent the actual measurement design,
and document the translation.
Historical data should cover comparable seasonal conditions. The factor VAR(1)
DGP has no explicit day-of-week, holiday, or campaign-season terms. A long but
non-comparable history can be worse than a shorter seasonally relevant window;
use pre-specified sensitivity checks.
Design Rejection
GeoSC should reject or defer a design when the requested causal statement is not
supported. At minimum, stop when:
treatment, outcome, geography, or measurement window is unresolved;
treatment exposure cannot be separated from donors;
the panel cannot satisfy the explicit data contract;
no substantively eligible donor pool remains;
pre-period fit is materially inadequate or dependent on an implausible donor;
placebo support cannot resolve the pre-specified alpha;
power is inadequate for the commercially plausible effect range;
simulation failures or DGP sensitivity make MDE unstable;
required assumption checks fail or inference status is failed;
conclusions reverse under small, equally defensible specifications.
Some failures can be repaired by changing geography, outcome, history, duration,
or eligibility. That creates a new design and requires a new power assessment.
If no repair is defensible before treatment, document the experiment as
descriptive or infeasible. A forced estimate is not a more helpful answer.
Donor Quality
Donor quality has two distinct meanings in GeoSC.
The donor stage measures pairwise pre-period similarity. Correlation captures
co-movement; RMSE and MAPE capture level error; normalised DTW captures temporal
shape. Composite scores are relative within each treated geography and support
screening. They do not estimate final counterfactual weights.
Inference measures joint synthetic-control fit. Several individually modest
donors can combine well, while a highly correlated donor can receive little
weight. Review fitted pre-period error and the SparseSC weight distribution.
Strong screening scores do not establish donor exchangeability. Eligibility
also requires no treatment exposure, comparable outcome measurement, and no
post-launch shock that differentially moves the donor. Conversely, poor overlap,
incomplete metrics, concentrated recommendation weights, or weak joint pre-fit
are direct reasons to reconsider the design.
Donor selection must be outcome-blind with respect to the measured post period.
Changing the pool after seeing lift invalidates ordinary interpretation unless
the search and multiplicity are explicitly modelled.
Frequently Asked Questions
Is a donor the same as a control?
A donor is an eligible control geography that can contribute to a synthetic
counterfactual. In code, power calls all non-treatment units controls. Preserve
the eligibility distinction in design documentation.
Do donor recommendations flow into inference?
No. The pipeline runs stages independently. Filter and version the panel if the
donor screen changes the eligible universe, then rerun affected stages.
Is GeoSC power simulation-based?
Yes. It estimates a factor-VAR DGP from the pre-period, simulates post-periods,
injects effects, calls SparseSC, and counts p-values below alpha. It is more
computationally intensive than a closed-form MDE but not automatically more
accurate.
Does power use the complete inference workflow?
No. It uses the SparseSC estimator and detection rule inside simulation but has
a narrower configuration and does not run inference data policies, cooldown,
assumption gates, or result processing.
Why can estimated power decrease at a larger effect or duration?
Finite Monte Carlo estimates can fluctuate. Large reversals can also indicate
failures, coarse placebo support, a weak DGP, or specification sensitivity.
Increase simulations and investigate; do not label an empirical rolling-window
diagnostic a theoretical monotonic power curve.
What does MDE mean here?
For a duration, it is the smallest valid effect on the tested grid reaching
configured target_power. It is not expected campaign lift and is not
interpolated.
How is a relative effect injected?
GeoSC multiplies one pooled mean across treated units and all pre-periods by the
relative effect, then adds the same absolute path to each treated unit.
What does valid mean in power output?
At least one simulation succeeded and failure rate did not exceed the threshold.
It says nothing about DGP plausibility or causal identification.
What is the top-level inference p-value?
It is a two-sided, add-one-corrected in-space placebo p-value for the absolute
average post-period effect. It is not a post/pre MSPE-ratio p-value.
Can a small donor pool produce significance?
Only at the resolution allowed by its effective placebo count. The smallest
step is 1 / (n_placebos + 1) under the implemented calculation.
Does status: ok prove the campaign caused lift?
No. It means the software result contract completed. Identification depends on
eligibility, isolation, measurement, timing, pre-fit, and sensitivity evidence.
Does GeoSC calculate ROI or iROAS?
No. Combine a defensible incremental outcome with campaign cost and the correct
commercial value or margin definition downstream.
Does GeoSC support GPU inference?
No. Optional CuPy work is limited to supported unseeded power DGP paths. Seeded
power and main SparseSC inference are CPU-based.
Method Comparisons
Compare estimands and decision rules before comparing numbers.
Time-based regression on aggregated treatment and control signals
Model-based intervals; design power depends on the implementation
Stable treatment-control relationship, match quality, model form, assignment constraints
Meridian GeoX
Randomised or stratified assignment with TBR inference at the documented launch boundary
Product-specific
Randomisation, balance, TBR stability, and delivery integrity
Meta GeoLift
Augmented synthetic control with generalised synthetic-control components
Conformal and package-specific procedures
L2 imbalance, augmentation model, market selection, test fit
Bayesian causal-impact tools
Structural time-series counterfactual
Posterior distribution
Prior/model fit and posterior predictive behaviour
GeoSC’s native power module is simulation-based, but that does not imply a TBR
or GeoX MDE is necessarily analytic; implementations vary. GeoSC repeatedly
simulates a factor-VAR post period, injects effects, and calls SparseSC. A TBR workflow may
use a fitted treatment-control regression, residual variance, analytic formula,
resampling, or simulation.
Before comparing MDEs align outcome and transformation, treatment geography,
control eligibility, pre-period, measurement and cooldown windows, lift
denominator, effect pattern, alpha, target power, one- or two-sided rule,
failure handling, and whether placebo assignments are sampled. Before comparing
effects align the estimand, scale, aggregation, and uncertainty interpretation.
A material discrepancy is a diagnostic. Decompose it rather than averaging the
answers or assuming the larger MDE is conservative. GeoSC is useful when
individual donor diagnostics, Python operation, and auditable artefacts matter;
it is not automatically superior to a well-specified regression design.
These references describe their respective implementations. They do not imply
that an internal or modified workflow uses the same defaults.
Multi-Treatment Designs
GeoSC supports several treated geographies, but interpretation and computation
change.
The top-level effect is joint across the treated set; it is not a separate ATT
for each geography. Placebo assignments must contain the same number of control
units as the treated set, giving possible assignments.
Each physical control contributes one residual path, so two treated units and
ten controls give 45 assignments. Controls with identical residual values
remain separate geographies. An assignment cannot contain the same geography
twice, although separate sampled assignments can repeat.
SparseSC work can grow rapidly, so sparse_sc_max_n_pl may trigger sampling.
There must be at least as many controls as treated units. This subset
feasibility rule does not establish sufficient p-value resolution or satisfy
the separate cross-fitting requirements; a larger control pool may be needed.
Power injects the same absolute effect path into every treated unit, based on
the pooled treated pre-period mean. This is not unit-specific proportional lift.
When treated units have very different outcome levels, supplement the standard
run with a carefully labelled sensitivity analysis or avoid describing the
injected effect_size as each unit’s own percentage lift.
All treated units must share one launch date equal to intervention_date.
GeoSC checks supplied dates before excluding cooldown periods and retiming the
estimator to the common measurement start. Staggered dates and a shared date
that differs from intervention_date are rejected. The private SparseSC
estimator also rejects staggered and dose-normalised requests; they require
different assignment rules.
Regenerate multi-treatment p-values, intervals, and power outputs produced
before the distinct-geography correction, including runs with a small placebo
cap. Earlier construction replicated the control block once per treated unit;
a low cap could hide the count mismatch without repairing the reference set.
The correction preserves fitted weights and point effects. It does not qualify
the placebo exchangeability assumptions or establish simulation calibration.
Placebo Inference
GeoSC uses SparseSC in-space placebo inference because geo experiments often
have too few treated units for conventional large-sample approximations.
For each treated-sized subset of eligible controls, SparseSC constructs an
honest placebo effect. The top-level p-value compares the absolute average
treated effect with the absolute average placebo effects and applies an add-one
correction. It is two-sided.
Read the empirical reference set
This uses the same synthetic example
as the counterfactual chart. With one treated geography and 49 controls, all 49
single-control placebo assignments are enumerated. The bars show honest placebo
mean effects from the native result; marks below the axis locate each value.
Orange shading identifies both tails where the absolute placebo mean is at
least as large as the absolute observed mean. The printed numerator includes
one for the add-one correction. Histogram bins are only a display choice;
counts and the p-value are computed from individual placebo values, including ties.
The finest p-value step is 1/50, or 0.02, in this example. No Gaussian distribution
is fitted. The figure explains the implemented comparison; it does not establish
exchangeability or statistical calibration. The numerical source
records the observed mean, every placebo mean and the counted exceedances.
Each eligible physical control appears once in the reference matrix. A subset
contains distinct geographies, even when some residual paths have equal values.
All treated units share one launch and measurement window.
The unchanged backend uses ten honest cross-fitting folds, so GeoSC requires
at least ten effective controls before SparseSC fitting. At the ten-control
boundary, each fold holds out one control and retains nine for fitting in the
retrospective fast-path fixture. This is an operational feasibility check,
not a qualification of error rates or donor exchangeability. Adding periods
or treated geographies does not increase the control count. Match-space CV
settings have separate training-size constraints; lowering sparse_sc_cv_folds
does not change honest cross-fitting.
When feasible assignments exceed sparse_sc_max_n_pl, SparseSC samples
assignments using sparse_sc_placebo_seed; otherwise it enumerates them. The
result reports the possible and effective counts and labels the mode exact,
sampled, or unknown.
Here exact means exhaustive enumeration of the supported physical-geography
assignment set; it does not assert exact causal calibration. Sampled draws
can repeat an assignment across draws, so the effective count is the number of
draws, not necessarily the number of unique assignments.
Finite support matters. With effective placebos the nominal resolution
is . If this exceeds alpha, significance at that alpha cannot be
attained. Sampling adds reference-set variability even when the optimiser is
stable; preserve the seed.
The p-value is calibrated only relative to the placebo assignment logic and its
exchangeability assumptions. Non-comparable donors, spillover, differential
measurement changes, or poor pre-fit can make a numerically small p-value
misleading. SparseSC placebo intervals are likewise finite-reference-set
quantities, not model-free guarantees.
Power and MDE Methodology
GeoSC power is a simulation-based design diagnostic. For each effect and
duration, let N be attempted simulations, S successful estimates, F=N-S failed
estimates, and R successful estimates with p < alpha. Ordinary power is R/N and
is available only when F=0. If any draw fails, primary power and its Wilson
interval are unavailable, and the row cannot support ordinary MDE recommendations.
The successful-draw rate remains explicitly named:
Failed draws have unknown rejection outcomes. The observed all-attempt rate
therefore has completion bounds:
For eight rejecting successes and two failures, conditional rejection is 100%
and the completion bounds are 80% to 100%; ordinary power is unavailable. These
are missing-outcome completion bounds for the simulated sample, not confidence
intervals or bounds on true population power. When every draw fails, conditional
rejection is unavailable and the completion bounds are [0,1]. When none fails,
the bounds collapse to the observed rate, while Monte Carlo uncertainty remains.
A row is valid only when its complete positive integer attempt count contains
zero failures. This does not establish DGP credibility, absence of future
failures, identification, or statistical calibration. There is no permissive
failure-rate override; power_failure_rate_threshold is retired.
Implemented workflow
For every effect-duration grid point, GeoSC:
pivots the long CSV to a unit-by-period matrix and sorts parsed dates with
their outcomes at the shared calculator boundary;
uses periods before treatment_date as the fixed observed pre-period;
demeans each unit, fits an SVD factor model, and estimates factor dynamics;
simulates a post-period panel;
computes one baseline as the mean across all treated units and all pre-periods;
multiplies that pooled baseline by effect_size and applies the resulting
same absolute effect path to every treated unit;
appends simulated post data to the observed pre-period;
calls SparseSC with treated periods at the split and counts
results.p_value < alpha.
The direct calculator excludes rows outside its declared treatment and control
sets before DGP fitting, retaining eligible rows in source order. File-driven
power defines those sets as the configured treated geographies and all other
CSV geographies. Unit identifiers must be unique and non-missing, and the two
sets must be disjoint and present in the panel.
This denominator means a configured 10% lift is relative to the pooled treated
pre-period mean. It is not a separate 10% of each treated unit’s own baseline.
The output records the baseline and full absolute injection.
The power loop uses the SparseSC estimator and its top-level placebo p-value,
but it is not identical to geosc infer. It does not run inference’s panel
policies, cooldown resolver, assumption checks, CI configuration, result
processor, or full SparseSC config surface. βSame inference pathβ is therefore
too strong; align panels and settings explicitly.
Power supports retrospective fast RidgeCV detection and shares inference’s
method/CV option builder for that path. It rejects other method requests and
simulation-owned window, CI or placebo-seed keys rather than discarding them.
Accepted CV controls are consumed by the native learner and recorded as JSON
estimator_settings in each row. Both stages retain their independent YAML
and placebo caps, so align the intended procedure explicitly.
Ignored lasso controls are retired. Match-space scoring uses a documented
continuous multi-output regression subset; recognising a sklearn scorer name
alone is insufficient because an incompatible scorer can yield all-NaN CV
scores without raising an exception. Native checks verify the supported
criteria on a manufactured panel; they do not establish campaign calibration.
Each successful simulation must return a finite real numeric p-value in
[0, 1]; booleans, strings, arrays, missing values and out-of-range values count
as failures. The original scalar is used for range checks and the strict
p_value < alpha comparison, avoiding rounding across a boundary. Invalid
outputs appear in n_invalid_p_values; other failures appear in
n_estimation_failures, and both contribute to n_failed.
The diagnostic conditional_power divides detections by successful estimates.
It must not be substituted for ordinary power or used to select an MDE. A failed
row remains unavailable even if the lower completion bound exceeds target power;
no failure-handling estimand is silently introduced. The corrections do not
establish empirical size, coverage or power calibration.
Effect patterns
constant and immediate: full absolute effect in every simulated period;
ramp: linear sequence from zero to full effect, inclusive;
decay: full effect followed by decay;
any other value: configuration error.
The 0.1 decay rate is not configurable in version 0.4.0.
Grid-based MDE
For duration and target power , GeoSC reports the smallest valid
tested effect that reaches the target:
target_power defaults to 0.80 in the CLI and pipeline but is configurable. No
interpolation is performed. If no effect reaches the target, MDE is above the
tested range.
Monte Carlo uncertainty
The CSV includes a Wilson interval around the estimated detection proportion.
Its confidence setting uses the configured alpha. This interval describes
finite simulation uncertainty, not DGP misspecification, donor-selection
uncertainty, or future-campaign uncertainty. If it straddles target power,
increase n_simulations before making a threshold decision.
Worked output
duration
effect_size
power
interval
failure_rate
valid
28
0.05
0.42
0.36β0.48
0.00
true
28
0.10
0.76
0.71β0.81
0.00
true
28
0.15
0.91
0.87β0.94
0.00
true
35
0.10
0.84
0.79β0.88
0.00
true
42
0.10
unavailable
unavailable
0.25
false
At 80% target power, the 28-period grid-based MDE is 15% and the 35-period MDE
is 10%. The 42-period row is withheld because some draws failed.
Power is computationally intensive because total work scales approximately with
effect sizes Γ durations Γ simulations Γ SparseSC fit and placebo cost. This
differs from a closed-form regression MDE, but computational intensity is not by
itself evidence of better calibration.
Power DGP Assumptions
GeoSC estimates its power data-generating process (DGP) from the pre-period
outcome matrix.
Each unit is demeaned. Singular value decomposition produces factor loadings
and factor scores. When rank is automatic, GeoSC chooses the first rank reaching
about 80% cumulative singular-value variance, bounded by
power_dgp_max_rank and a short-panel VAR feasibility cap. It then estimates a
VAR(1) intercept, transition matrix, and Gaussian innovation covariance on the
factor series.
Simulation draws the initial factor state from the estimated marginal normal
distribution; it is not conditioned on the final observed factor state. Later
states follow the fitted VAR(1). Outcomes combine fixed unit loadings, simulated
factors, stored unit means, and independent Gaussian idiosyncratic noise with
one pooled residual standard deviation.
Consequences:
cross-unit dependence is represented through common factors;
lag-one factor dependence is represented;
calendar seasonality is not modelled explicitly;
the fitted VAR transition is not constrained to be dynamically stable;
idiosyncratic variance is homoskedastic across units and periods;
non-Gaussian tails, structural breaks, intermittent zeros, and conditional
start-state dynamics may be poorly represented;
rank selection is a heuristic, not cross-validated DGP truth.
Validate simulated moments and time-series behaviour against the use case. Run
sensitivity to history, rank, effect pattern, and eligible controls. If design
decisions change materially, report DGP dependence rather than one definitive
MDE.
SparseSC Estimator
GeoSC’s only implemented estimator selector is sparsesc. SparseSC learns a
regularised match space and donor weights from pre-treatment outcomes and
optional covariates.
Conceptually, it chooses unit weights and match-space weights to
reduce treated-versus-synthetic pre-period discrepancy subject to regularisation:
This is an explanatory simplification, not a line-by-line restatement of every
vendored optimisation path. With sparse_sc_fast_estimation: true, GeoSC calls
the vendored fast path, which uses RidgeCV-backed match-space machinery. The
full path uses SparseSC’s penalty search and coordinate-descent machinery.
Regularisation controls overfit; it does not make an ineligible donor valid.
Inspect pre-fit, fitted unit weights, weight concentration, and sensitivity to
substantive donor exclusions. The selected_weight from GeoSC’s donor stage is
not ; fitted weights are exposed in inference diagnostics.
The package vendors a pinned, locally governed SparseSC fork. See
Vendored Dependencies for provenance.
Spillover, Contamination, and Concurrent Media
Synthetic control requires the donors to represent untreated outcomes. This can
fail when audience delivery crosses boundaries, national media reaches both
groups, travellers move between geographies, retail or supply changes differ by
region, or another campaign starts near treatment.
Concurrent activity is not automatically fatal. A national or business-as-usual
channel can be part of the baseline if its effect and delivery are sufficiently
common across treated and donor geographies. Differential delivery correlated
with treatment is the problem. Record channel, dates, spend or delivery where
available, targeting logic, and expected geographic reach.
GeoSC’s interference screen compares outcome behaviour and can return signal,
no_signal, or indeterminate. It has no exposure model and cannot establish
whether media caused the pattern. Use campaign logs, geographic delivery data,
and domain evidence. Keep the screen advisory.
If contamination is material and cannot be represented or excluded, reject the
design or change the estimand. Do not reinterpret contaminated donors as valid
because pre-period fit was good.
Synthetic-Control Formalism
Let be the outcome for unit and period . Let
denote treated units, eligible donors, and
the last pre-treatment period after any window resolution.
For one treated unit, a synthetic counterfactual has the form
The maintained retrospective fast estimator uses pre-treatment features and
post-period control outcomes to learn the match space. It does not fit to the
treated post-period outcomes. The period effect is
and GeoSC’s top-level unscaled ATT is the average of that effect over measured
post periods:
Read the fitted counterfactual
This illustrative synthetic example has one treated geography, 49 eligible
controls, 40 pre-period days, three cooldown days and 17 measured days. The
upper panel compares observed outcomes with the fitted synthetic trajectory.
The lower panel shows their difference; its dashed line averages only measured
days. The three cooldown days are excluded from fitting and the reported effect,
so the synthetic line has a gap there. The filled area between the upper lines
shows an outcome difference, not a confidence interval.
The generator adds four outcome units per day after launch, but the chart shows
the estimated effect rather than substituting that known injection. Its
counterfactual and placebo figures come from the same native GeoSC analysis.
See the numerical source and
reproduction instructions.
This is an explanation of the calculation, not a calibration study or campaign result.
The implementation also supports multiple treated units. SparseSC constructs a
joint treated effect and an in-space placebo reference set formed from treated-
sized subsets of controls. With controls and treated units, the
exhaustive assignment count is
GeoSC’s top-level p-value is not a post/pre mean-squared prediction-error
ratio. If is the average placebo effect for assignment
, SparseSC uses the two-sided absolute-effect comparison with add-one
correction:
where is the effective exhaustive or sampled placebo count. The finest
attainable step under this calculation is . The result is an
empirical comparison against the eligible placebo assignments; its causal
meaning depends on the design.
Getting Started
Install GeoSC, understand the workflow, and complete your first analysis.
GeoSC separates design questions that are often blurred together.
Solid arrows show the actual pipeline order. Dashed arrows are analyst decisions,
not automatic filtering or pipeline gates. If power or donor quality is inadequate,
revise the panel or design and rerun affected stages before interpreting inference.
The panel count matches the illustrative 50-geography example in the
counterfactual chart;
the figure does not present simulated power results.
Stage
Question
Main artefact
Important limit
Power
Could the proposed design detect effects on the tested grid under the fitted simulation DGP?
power_analysis_results.csv
It does not forecast campaign lift or establish identification.
Donors
Which eligible geographies have useful pairwise pre-period similarity to each treated geography?
donor_eval_results.csv
Recommendations and selected_weight are screening outputs, not fitted SparseSC weights.
Inference
How did treated outcomes differ from the SparseSC counterfactual during the measurement period?
geolift_results.json
Causal interpretation remains conditional on design assumptions.
In GeoSC, a control is a geography not assigned treatment in the input to a
stage. A donor is a control geography eligible to contribute to a synthetic
counterfactual. Operationally, analysts often use the words interchangeably,
but eligibility should be determined before model fitting.
The pipeline executes power, donors, then infer. It does not use donor
recommendations to filter the later power or inference inputs. Power uses every
non-treatment unit in its input panel as a control. Inference uses the control
units present in its prepared panel. If a screening decision should constrain a
later stage, create a filtered canonical panel or config and record that hand-off.
Before running any stage, define:
the outcome and its unit of measurement;
the treated geography or geographies;
the treatment launch, cooldown, and measurement window;
donor eligibility and exclusions;
the effect scale, alpha, target power, and reporting rule;
plausible spillover, concurrent-media, and measurement-change mechanisms.
Reject or redesign the study if these decisions cannot be defended. GeoSC is a
measurement engine, not a machine for laundering an infeasible design into a
number.
First Successful Run
This run checks the installed CLI and artefact path using the source checkout’s
synthetic data. It is a software smoke test, not evidence that the demo is a
credible client design.
A successful command returns exit code 0 and writes these files under the
configured inference output directory:
geolift_results.json;
geolift_diagnostics.json;
data_validation.json;
assumption_validation.json.
Inspect them in this order:
data_validation.json: confirm the panel, periods, units, and data policies.
geolift_results.json: require status: "ok" or investigate every warning
on a partial result. Never report a failed result.
geolift_diagnostics.json: review pre-period fit, placebo support, and donor
weight concentration.
assumption_validation.json: regression/visual pre-trends and interference
are advisory; only an explicitly requested placebo diagnostic can gate results.
Next, replace the demo config with a copy tied to your panel. Follow
Prepare an Input Panel before using client
data.
Installation
GeoSC 0.4.0 supports Python 3.10 to 3.13. Use an isolated virtual environment.
Obtain the wheel or source archive from the private GitHub release.
Access requires repository permission. This beta does not establish statistical
calibration; review the inference and power limitations before using results.
The build installs both geosc and the compatibility command geolift.
It does not include the repository’s data-config/, recipes/, or shapemap/
directories. Supply your own input CSV and YAML files.
Source installation makes the shipped synthetic panel and stage configs
available under data-config/.
Optional GPU dependency
CuPy is optional and is used only by parts of unseeded power-analysis DGP
estimation or generation when the supported GPU path is available. Main
SparseSC inference is CPU-based. A configured random_seed disables GPU DGP
and generation paths to preserve reproducible draws. Install a CuPy build that
matches the local CUDA runtime; for example:
python -m pip install cupy-cuda12x
GeoSC falls back to CPU when the requested GPU path is unavailable. Record the
reported dgp_backend and generation_backend; do not infer GPU use from the
configuration alone.
Development and documentation
pyproject.toml contains the runtime dependencies and optional tooling. The
former duplicated requirements.txt is no longer maintained.
Relearn renders TeX during the build using KaTeX. The previous custom MathJax
footer is obsolete. Built HTML and synchronised Hugo content are generated
artefacts; edit docs/ first.
How-to Guides
Prepare data, choose donors, run analyses, and review results with these guides.
Average difference, in outcome units per observed period, between treated
outcomes and their SparseSC counterfactual over the declared measurement
window for the declared treated geographies.
GeoSC labels this att_unscaled. The top-level att is the average across the
post-period effect path. If several geographies are treated, the SparseSC
procedure forms a joint treated effect; do not describe the result as a
unit-specific effect unless a separate analysis supports that claim.
Set:
intervention_date_str: first observed treatment period;
cooldown_periods: observed periods after launch excluded from measurement;
optional measurement_start_date_str: explicit start that must agree with the
cooldown calculation;
min_pre_treatment_periods and min_post_treatment_periods: admissibility
thresholds where supplied.
Cooldown periods are neither pre-period fit data nor measured post-period data.
They count observations, not calendar units. A seven-period cooldown is seven
days only for a complete daily panel.
Pre-specify the end of measurement by trimming the input panel to the intended
window. The shipped inference config has no active end_date key.
Define Treatment and Donor Eligibility
Create and freeze an eligibility table before running GeoSC. Treat it as the
analysis-universe contract: it records which geographies are treated, which
untreated geographies are eligible controls, which geographies are excluded, and
why.
Use one row per geography:
Column
Purpose
unit_id
Geography identifier used in the input panel.
role
treated, eligible_control, or excluded.
included_in_panel
Whether the unit is present in the versioned panel used by a stage.
reason
Design reason for inclusion or exclusion.
decision_date
Date the eligibility decision was made.
owner
Person or team accountable for the decision.
contamination_notes
Known campaign, operational, or measurement contamination.
leakage_notes
Geographic adjacency or audience leakage concerns.
Example:
unit_id
role
included_in_panel
reason
decision_date
owner
contamination_notes
leakage_notes
region_ne
excluded
false
Adjacent to treatment region and exposed to overlapping out-of-home media.
2026-08-05
Measurement lead
Same creative ran during the test window.
Commuter leakage into treatment area.
Eligible controls should be unaffected by treatment, measured consistently, and
plausible counterfactual contributors. Pre-period correlation and donor-screen
scores are diagnostics; they are not eligibility rules and do not prove
exchangeability. Exclude geographies only for design reasons established before
reviewing post-treatment outcomes.
Freeze the Universe
Define treated units and the first observed treatment period.
Remove contaminated, leaking, inconsistently measured, or otherwise
ineligible controls.
Materialise the approved treated units and eligible controls as a versioned
panel.
Run power, donor evaluation, and inference from that versioned panel.
If donor screening changes the eligible universe, create a new panel version
and rerun the affected stages.
Do not tune exclusions, treatment dates, or donor membership after seeing
post-treatment lift. That creates a different design and invalidates ordinary
interpretation unless the search and multiplicity are explicitly modelled.
What GeoSC Includes
Power treats every non-treatment unit in its input as a control. Donor
evaluation scores every eligible non-treatment unit in its own input. Inference
uses the controls in its prepared panel, where controls are units without a
treatment period. GeoSC does not automatically apply donor recommendations to
the other stages.
For several treated geographies, confirm that the eligible control pool can
support joint in-space placebo assignments: with controls and
treated units, the exhaustive assignment count is , provided
. If the eligible control pool is too small, placebo inference is
infeasible or too coarse for the planned alpha.
Revisit eligibility, geography level, outcome, and comparable history.
Coarse p-value granularity
Too few effective placebo assignments
Add eligible controls or reduce treated count only if the design permits it.
Fewer than ten retained controls
Infeasible ten-fold honest cross-fitting
Add eligible controls and check data-policy drops; changing match-space CV folds cannot enable this pool.
Dominant fitted donor weight
Counterfactual depends on one geography
Audit that donor and run exclusion sensitivity.
High power failure rate
SparseSC or DGP instability
Inspect exceptions, rank, panel completeness, and placebo feasibility.
High grid-based MDE
Noise or weak counterfactual relative to plausible lift
Redesign duration, outcome, treated scale, or method before launch.
Interference signal
Outcome changes among controls are compatible with contamination
Investigate exposure using campaign and geographic evidence; the screen is not causal proof.
Result partial
Missing uncertainty or warnings
Resolve the stated fields before decision use.
Do not tune exclusions, dates, or donors by searching for significance. If the
remedy changes the design, rerun power and record the new specification.
Evaluate Donors
Run donor evaluation on pre-treatment data after applying substantive
eligibility exclusions.
The evaluator aligns each treatment-donor pair by time, then calculates Pearson
correlation and its p-value, root mean squared error (RMSE), percentage RMSE,
mean absolute percentage error (MAPE), and normalised dynamic time-warping
(DTW) distance. It normalises metrics within each treated geography, combines
them using adaptive weights, and ranks complete rows.
Review:
overlap_count, treatment_coverage, and donor_coverage before scores;
metrics_complete and metric_failure_reasons;
correlation, rmse, mape, and dtw, not only composite_score;
warning_flags, quality bands, concentration, and effective donor count;
maps only as a geographic diagnostic, not as proof of comparability.
selected_weight is normalised from positive composite scores among the
recommended donors. Its role is design_stage_recommendation_weight; it is not
a fitted SparseSC counterfactual weight.
The evaluator’s output is a screening artefact. If it changes the donor pool,
filter the canonical panel and rerun power and inference. To render maps, see
Use Shapemaps.
DTW standardises each pair’s finite, timestamp-aligned overlap using its own
mean and population standard deviation. FastDTW uses scalar absolute local cost,
a fixed approximation search radius of one, and divides the resulting distance
by the overlap count. Constant series become zero vectors. The radius controls
the approximation neighbourhood around a recursively estimated path; it does
not bound the displacement between aligned dates.
Version 0.4.0 replaces the history-dependent approximation radius. This can
change DTW, composite rankings, recommendation weights and seasonality_score
(which aliases normalised DTW). Regenerate recommendations and inspect the
underlying metrics. Backend and radius are recorded in quality JSON; rankings
are screening outputs and have no calibrated acceptance guarantee.
How to Use Shapemaps
GeoSC donor-stage maps use shapemap_file to read a GeoPandas-compatible vector
file and shapemap_id_column to choose the geography ID used for joins. The
values in that ID column must match the unit IDs used in your experiment data,
such as DMA IDs, postcode districts, postcode areas, or another market key.
The inference and power stages do not consume shapemap configuration.
Built wheel and sdist installs do not include the repository-local shapemap/
directory. Packaged users should provide map files from their own runtime
environment.
GeoSC can read formats supported by GeoPandas, including GeoJSON, TopoJSON,
Shapefile, and GeoPackage inputs when the local geospatial stack supports them.
Repository-local shapemap examples are available for common markets:
shapemap/uk/postcode_areas.geojson
shapemap/uk/postcode_districts.geojson
shapemap/us/dma_legacy_normalized.geojson
shapemap/fr/fr_nuts3.geojson
shapemap/de/de_nuts3.geojson
shapemap/uk/meta_commuting_zones.geojson
shapemap/us/meta_commuting_zones.geojson
shapemap/fr/fr_meta_commuting_zones.geojson
shapemap/de/de_meta_commuting_zones.geojson
These are source-checkout assets. They are not included in built wheel or sdist
artifacts.
Meta Commuting Zones are also available as optional geographies for
Meta-aligned study design. They are commuting/economic zones, not Meta
ad-targeting boundaries.
UK Postcode District Example
For UK production workflows, postcode district is often the practical market
geography:
Do not commit or distribute postcode geometry unless the source license permits
that use. The repository records shapemap provenance policy in
shapemap/README.md and shapemap/manifest.yaml.
For UK data:
OS Code-Point Open is an open postcode unit point dataset, not polygon geometry.
OS Code-Point with Polygons is the appropriate official polygon source when
you have the necessary access and licensing.
ONS Postcode Directory is useful for postcode-to-geography lookup workflows.
Troubleshooting
If donor maps do not highlight treatment or donor units:
confirm the shapemap contains the configured shapemap_id_column
confirm the shapemap ID values exactly match the experiment unit IDs
normalize both sides to the same case and spacing convention
confirm the file can be opened by geopandas.read_file
scripts/validate_shapemap.py reports missing expected IDs, duplicate IDs,
blank IDs, null or empty geometry, invalid geometry, row counts, unique ID
counts, and the detected CRS.
Prepare an Input Panel
Use a long CSV with one row per geography and observed period. The inference
loader requires configured date, geography, and outcome columns; treatment is
defined in YAML, not read from a treatment flag in the CSV.
Required checks
Use stable geography identifiers and one geographic level.
Use a regular time interval appropriate to the campaign and outcome.
Confirm that every intended unit-period has one finite outcome.
Make the intervention date an observed period.
Preserve enough observations before and after the resolved measurement start.
Use a consistent outcome definition, currency, attribution window, and data
production process across geographies and time.
Inference defaults to duplicate_policy: error and
missing_outcome_policy: error. Alternative policies are explicit analytical
decisions. mean or sum changes duplicate rows before pivoting;
drop_unit, drop_period, or impute_with_report changes the estimable panel.
With impute_with_report, interpolation and endpoint filling use observations
from the same pre-treatment, cooldown, or measurement window. A geography with
no observed outcome in a window fails; supply data or choose an explicit drop
policy. The method uses observed-period positions rather than elapsed time, so
keep the observation cadence appropriate to the analysis.
Optional covariates are numeric pre-period baseline means. They use only
retained outcome periods, average duplicate records within a period before
averaging periods, and skip missing covariate observations. Every unit/feature
needs an observed finite baseline. For direct-data runs, prepare this baseline
table before passing covariates_df; GeoSC cannot infer its source dates.
Do not use locale-dependent date parsing in an audited run. After execution,
review data_validation.json; a successful model does not supersede a failed
data contract.
Produce a Stakeholder Summary
Lead with the decision and its conditions. A compact summary should include:
treated geography, outcome, launch, cooldown, and measurement dates;
eligible donor universe and material exclusions;
design-stage MDE at the stated target power and plausible lift range;
inference status, ATT in outcome units, interval, p-value, and placebo count;
pre-period fit and donor concentration;
concurrent media, spillover, data, and sensitivity caveats;
a clear recommendation: proceed, interpret cautiously, redesign, or reject.
Example:
GeoSC estimated average incremental revenue of Β£X per week against the
pre-specified SparseSC counterfactual over dates AβB. The two-sided in-space
placebo p-value was P using N placebo assignments; the interval was [L, U].
Interpretation is conditional on the recorded donor-eligibility and treatment-
isolation assumptions. The design-stage grid-based MDE was M% at T% target
power, so effects below M% were not reliably detectable under the fitted DGP.
Do not translate statistical significance into ROI without campaign cost and a
commercial value definition. Do not describe status: ok as proof of causal
validity.
Use the interval level recorded in ci.level, independently of the configured
significance threshold. An 80% average-ATT interval must not be labelled 95%,
and its bounds must remain in the ATT’s unscaled outcome units. Scaled
diagnostic bounds cannot fill missing primary uncertainty. The uplift plot’s
horizontal band concerns average ATT uncertainty, not coverage of the effect
path.
For partial results, retain warnings and state which quantities remain
available. For failed or unknown status, report errors and unavailable
inference instead of interpreting retained diagnostic numbers. Read
significance_available before the stored significant flag; an unavailable
decision is not evidence of no effect. The maintained renderers apply these
rules consistently and the HTML report escapes artifact-derived text.
Run Inference
Freeze the panel and inference YAML before viewing post-treatment results, then
run:
Use --data to override only the CSV path and --no-create-plots to suppress
plotting. The command returns non-zero when the stage raises an error or the
result status is failed.
Review outputs in this order:
data_validation.json for panel construction and window metadata;
assumption_validation.json for advisory pre-trends/interference and any
explicitly requested experimental pre-period placebo gate;
geolift_results.json for status, unscaled ATT, p-value, interval, placebo
count, granularity, warnings, and errors;
geolift_diagnostics.json for pre-fit and fitted donor-weight diagnostics;
uplift_timeseries.png as a visual diagnostic.
Summary intervals use the recorded ci.level and unscaled nested bounds.
Disabled or unavailable primary intervals remain unavailable, even when scaled
diagnostics exist. Partial plots display their limitations; failed or incomplete
primary results cannot generate uplift plots. Regenerate older dictionaries
missing status, estimand or nested interval metadata rather than assigning a
default confidence level. See the result contract.
Describe the result as an estimated difference from the configured SparseSC
counterfactual. Causal interpretation requires defensible donor exchangeability,
treatment isolation, stable measurement, timing, and absence of material
unmodelled shocks. The advisory interference screen cannot prove or disprove
spillover.
Read the estimated effect
This synthetic example illustrates the distinction between the outcome path,
period effects and their measurement-period average. It is not an output from
your campaign. Read the worked explanation
before interpreting the equivalent diagnostics in your own run.
Run Power Analysis
Define a plausible effect grid and duration grid, then run:
geosc power --config data-config/power_analysis_config.yaml --jobs -1
Use a fixed random_seed for an audited run. Seeded runs use CPU simulation
paths. Start with a small n_simulations only to debug the configuration, then
increase it until Monte Carlo intervals are adequate for the decision.
For each row:
require valid: true;
inspect failure_rate and warnings;
compare power with its Wilson interval;
verify the DGP rank, explained variance, backends, placebo support, and
injection metadata;
interpret MDE as the smallest tested effect reaching target_power for
a duration.
GeoSC does not interpolate between effect sizes. If no grid value reaches the
target, report MDE as greater than the maximum tested effect. The CLI’s default
planning threshold is 80%; it is configurable through target_power and is not
a statistical property of SparseSC.
Power uses the SparseSC estimator and p-value detection rule inside each
simulation, but it does not execute the full inference workflow. It does not
run inference data policies, cooldown resolution, assumption checks, result
processing, or plotting. Align the power input panel and intervention split with
the intended inference design yourself.
Run Sensitivity Analysis
Pre-specify a small set of defensible perturbations:
alternative comparable pre-period windows;
exclusion of a substantively suspect or dominant donor;
plausible cooldown or measurement-start choices;
DGP rank and effect-pattern choices for power;
outcome definitions fixed before post-period inspection;
eligible geography aggregations justified by media delivery and spillover.
For each run, save its panel hash, config, artefacts, and rationale. Compare ATT,
intervals, p-values, pre-fit, donor weights, placebo support, MDE, and failure
rates. Distinguish robustness to a design choice from fishing over arbitrary
specifications.
If the decision changes under small, equally defensible perturbations, report
the result as specification-sensitive. Do not average incompatible estimands.
Run the Pipeline
Place the three canonical stage configs in one directory, then point the
pipeline at any one of them:
The required filenames are power_analysis_config.yaml,
donor_eval_config.yaml, and geolift_analysis_config.yaml. The command runs
power, donors, then inference and writes Markdown and HTML summaries by default.
--output-dir creates the legacy stage subdirectories below the supplied root.
--jobs and --use-gpu are passed as runtime overrides, subject to each
stage’s support.
The pipeline is an orchestrator, not a design-state engine. Donor
recommendations do not filter power or inference inputs. The compact report is
not a decision gate; inspect each underlying artefact and record any manual
panel hand-off.
Use the Python API
For file-based inference, initialise the public analyser with a config and data
path:
Direct-data construction is also supported by GeoLiftAnalyzer; the panel must
be wide with units as rows and datetime-like periods as columns, with a unit-
indexed treatment-period series. Use the Python API reference
for signatures.
Power is available through geolift.power.SparseSCPowerCalculator. Donor
screening is available through geolift.donor_evaluator.DonorEvaluator, but
neither is re-exported from the package root. Prefer the CLI for versioned
file-based runs because it writes the maintained artefact family.
Validate a Power Simulation
Treat a power run as a model requiring diagnostics.
Reproducibility
Repeat the same CPU run with the same seed and compare the CSVs. Record the
package version, input hash, YAML, seed, and execution backends.
Monte Carlo precision
Use power_ci_lower and power_ci_upper. If the interval straddles the target
power, increase simulations before making a boundary decision. The interval
quantifies simulation-count uncertainty only; it does not include uncertainty
about the DGP specification.
DGP plausibility
Review dgp_rank, dgp_explained_var, and dgp_factor_dynamics. Compare
observed and simulated distributions outside GeoSC where the decision is
material: unit means and variances, cross-unit correlations, autocorrelation,
seasonal patterns, extremes, and zeros. The current DGP does not model calendar
effects or heteroskedastic idiosyncratic noise explicitly.
Grid stability
Power should usually rise with larger injected effects in a well-resolved
simulation, but finite Monte Carlo estimates can move up or down. Investigate
large reversals, high failure rates, coarse placebo p-values, or sensitivity to
rank, history window, seed, donor eligibility, and effect pattern.
Do not call the run validated merely because all rows are valid. That flag
requires zero failed simulations. Failed rows retain a conditional rejection
rate and completion bounds, but ordinary power and its interval are unavailable.
Do not select a design from those conditional rates or interpret an all-failed
row as zero power. Remove the retired power_failure_rate_threshold key and
regenerate older CSVs; decision consumers require current schema 2.0.
Reference
Look up CLI and Python interfaces, configuration, and artefact contracts.
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
Check supported settings and defaults before configuring each stage.
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.
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.
Recommended external contract
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.
Output Schemas
Interpret fields, diagnostic statuses, and limits in generated artefacts.
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.
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.
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:
fromgeoliftimportGeoLiftAnalyzer,load_config
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.
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.
Tutorials
Work through examples connecting design decisions, commands, and outputs.
This tutorial uses the repository’s synthetic panel to exercise all three
stages and their explicit hand-offs.
1. Inspect the stage configs
The pipeline requires three canonical filenames in one directory:
power_analysis_config.yaml;
donor_eval_config.yaml;
geolift_analysis_config.yaml.
Confirm that all three identify the same outcome, geography universe, treatment
units, and launch date. The key names differ by stage; use the stage-specific
configuration reference.
The command runs power, donor evaluation, and inference independently. It then
summarises their artefacts. It does not feed recommended donors into inference.
3. Review the design outputs
Open multicell_power_analysis/power_analysis_results.csv. Retain only rows
where valid is true. MDE is the smallest tested effect_size that reaches
target_power for a duration; it is grid-based and conditional on the simulated
DGP.
Open multicell_donor_eval/donor_pool_quality.json. Treat
quality_assessment: "INSUFFICIENT", incomplete metrics, dominant recommendation
weights, or poor overlap as redesign signals.
4. Review inference
Open multicell_geolift_analysis/geolift_results.json. The primary estimate is
the unscaled post-period average effect (att). The top-level p_value is the
two-sided in-space placebo p-value for that average effect. Scaled quantities
remain diagnostics and must not be combined with the unscaled interval.
5. Record the hand-off
If the donor screen changes eligibility, materialise a new panel containing the
treated units and approved donors. Rerun power and inference on that same panel.
Record the input hash, configs, exclusions, software version, and random seeds.
Failed Donor Design
Consider a treated geography with five recommended donors. Two have incomplete
metrics, one receives 70% of the design-stage recommendation weight, and the
pool-level quality_assessment is INSUFFICIENT.
This is not a prompt to fit SparseSC and hope regularisation fixes the design.
The donor screen says the counterfactual may depend on weak or concentrated
comparators. Review time overlap, outcome definitions, treatment leakage,
regional shocks, and geography aggregation. Exclude a donor only for a
pre-specified eligibility reason, not because its removal improves the eventual
effect estimate.
If eligibility changes, rerun donor screening, power, and inference on the same
revised geography universe. If no defensible pool remains, reject the design and
state which condition failed. See Design Rejection.
Underpowered Design
Suppose a valid power grid contains the following rows for a 28-period test:
effect_size
power
Monte Carlo interval
valid
0.04
0.31
0.27β0.35
true
0.06
0.55
0.50β0.60
true
0.08
0.73
0.68β0.77
true
0.10
0.84
0.80β0.88
true
At an 80% target, the grid-based MDE is 10%. This does not mean that the
campaign is expected to deliver 10%, or that effects below 10% are zero. It
means the configured procedure detected smaller injected effects less often
than the planning threshold under this DGP.
If commercially plausible lift is 4%, the design is underpowered for that
decision. Do not solve the problem by reporting an optimistic grid point or by
choosing a longer period after seeing outcomes. Consider more comparable
donors, lower-noise outcomes, a defensible larger treated population, a longer
pre-specified measurement window, or a different design. If none is available,
record the design as infeasible before launch.
Also inspect failures. A row with high estimated power and valid: false is not
a usable design result. Power is divided by successful simulations, so ignored
failures could otherwise make it look better than it is.