Skip to main content

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:

from geolift import GeoLiftAnalyzer, load_config

Specialist classes are available from their modules rather than the package root:

from geolift.donor_evaluator import DonorEvaluator
from geolift.power import SparseSCPowerCalculator

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.