Getting Started
Install GeoSC, understand the workflow, and complete your first analysis.
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:
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.
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.
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/.
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:
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.
pyproject.toml contains the runtime dependencies and optional tooling. The
former duplicated requirements.txt is no longer maintained.
The tested static-site toolchain is Hugo Extended 0.169.0 with Relearn
9.4.0. Install that theme in a fresh checkout before running Hugo:
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.