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

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

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.

Constructor arguments

Argument	Default	Contract
`config_path`	`None`	YAML or JSON configuration path for file mode.
`data_path`	`None`	Long CSV path; use with `config_path`.
`outcomes_df`	`None`	Wide numeric DataFrame with units as rows and datetime periods as columns.
`unit_treatment_periods`	`None`	Series indexed by units, containing launch dates or missing values for controls.
`covariates_df`	`None`	Optional unit-indexed covariates in direct-data mode.
`intervention_date`	`None`	Global launch date in direct-data mode.
`config`	`None`	Runtime options; overrides file configuration at the top level.
`shapemap_file`	`None`	Retained constructor argument; the maintained inference plot does not use it.

Use one construction mode at a time. See the complete direct-data example.

Analysis methods

run_analysis() returns the primary result dictionary.
run_geolift_analysis() is the compatibility analysis entry point.
plot_results(output_path=None) writes the actual-versus-synthetic plot and returns its path after analysis.
run_assumption_validation() runs configured diagnostics; inspect their structured statuses rather than treating completion as identification.

File-based analysis writes the configured artefacts. Direct-data callers retain and serialise their own result and diagnostic mappings.

Root helpers

Callable	Inputs and return value
`load_config(file_path, validate=True)`	Loads YAML or JSON into a dictionary. Validation defaults to the common inference contract; use stage-specific CLI handling for donor or power configuration.
`load_and_prepare_data(...)`	Required arguments are `data_path`, `outcome_col_name`, `date_col_name`, `location_col_name`, `treatment_unit_ids` and `intervention_date_str`. Returns outcomes, treatment periods, covariates, locations, dates and resolved intervention date. `return_validation_report=True` appends the validation report.
`process_sparse_sc_results(sparse_sc_results, config)`	Returns `(results, diagnostics)` with explicit scale, uncertainty and status metadata. Prefer `GeoLiftAnalyzer` for ordinary use.
`plot_actual_vs_synthetic(...)`	Takes wide actual and synthetic DataFrames, `treatment_unit_ids`, `intervention_date` and `output_dir`. Optional `plot_filename` defaults to `actual_vs_synthetic.png`; optional `config` controls plotting. Writes the file and returns `None`.
`validate_geolift_dependencies(required=None)`	Checks import availability and raises `ImportError` for missing dependencies. It does not verify numerical compatibility or library versions.

The data loader also accepts covariate_col_names, date_format (default %Y-%m-%d), the documented duplicate and missing-outcome policies, cooldown and measurement-start options, and pre/post admissibility thresholds. Use explicit date formats. A prepared panel must still satisfy the inference contract.

Power calculator

Import SparseSCPowerCalculator from geolift.power. Construct it with outcomes_df, treatment_units, control_units, intervention_date and an optional config. Outcomes are a wide unit-by-period DataFrame. The constructor estimates the DGP from the pre-period.

calculate_power(effect_sizes, test_durations, n_simulations=1000, alpha=0.05, parallel=False, n_jobs=-1, effect_pattern="constant") returns a DataFrame with the power row contract. plot_power_curves(power_results, output_path=None, target_power=0.8) plots valid rows. Direct-data automatic DGP rank has a default maximum of 10; the CLI sets power_dgp_max_rank to 5. Set it explicitly when comparing runs.

Donor evaluator

Import DonorEvaluator from geolift.donor_evaluator and pass the stage’s params dictionary. run() loads the donor panel, scores candidates, creates recommendations and writes results. It returns a dictionary with evaluation_results and recommendations.

For staged control, use load_and_prepare_data(), evaluate_donors(), generate_recommendations() and save_results(evaluation_results, recommendations). plot_donor_map(treatment_unit, donor_units) writes a map when a usable shapemap is configured.

plot_donor_comparison, plot_normalized_donor_comparison and plot_scaled_donor_comparison are retained placeholders that only log a message. They do not generate figures and are not supported plotting capabilities.

Use a pre-treatment-only donor CSV to keep adaptive thresholds outcome-blind. Recommendation weights remain separate from fitted SparseSC weights.