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:
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.