Getting Started

Concepts and Workflow

GeoSC separates design questions that are often blurred together.

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.

geosc infer \
  --config data-config/geolift_analysis_config.yaml \
  --no-create-plots

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: distinguish the gate-eligible parallel-trends diagnostic from the advisory interference screen.

Next, replace the demo config with a copy tied to your panel. Follow Prepare an Input Panel before using client data.

Installation

GeoSC 0.3.0 supports Python 3.10 to 3.13. Use an isolated virtual environment.

Install a maintained build

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install /path/to/geosc-0.3.0-py3-none-any.whl
geosc --help

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.

Install from a source checkout

git clone https://github.com/tandpds/GeoSC.git
cd GeoSC
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python -m pip install -e .
geosc --help

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.