API Reference

Technical reference for GeoLift classes and functions.

Core Classes

GeoLiftAnalyzer

Main class for running causal inference analyses using SparseSC.

The analyzer supports two initialization modes:

  1. File-based: Initialize with config_path and data_path

  2. Direct data: Initialize with prepared data structures

Initialization

File-based initialization:
from geolift.analyzer import GeoLiftAnalyzer

analyzer = GeoLiftAnalyzer(
    config_path='data-config/geolift_analysis_config.yaml',
    data_path='data-config/synthetic_geolift_multi.csv',
    shapemap_file='shapemap/nielsentopo.json'  # optional
)
Direct data initialization:
import pandas as pd
from geolift.analyzer import GeoLiftAnalyzer

# Prepare your data
outcomes_df = pd.DataFrame(...)  # Shape: (units, time_periods)
unit_treatment_periods = pd.Series({
    'unit_1': '2023-06-01',  # Treatment unit
    'unit_2': None,          # Control unit
    'unit_3': None           # Control unit
})

analyzer = GeoLiftAnalyzer(
    outcomes_df=outcomes_df,
    unit_treatment_periods=unit_treatment_periods,
    intervention_date='2023-06-01',
    config={'sparse_sc_model_type': 'retrospective', 'sparse_sc_lasso_max_iter': 5000}
)

Methods

run_geolift_analysis()

Execute the complete GeoLift causal inference analysis pipeline.

Returns: Dictionary containing:

  • att: Average Treatment Effect (ATT)

  • p_value: Statistical significance

  • ci_lower, ci_upper: Confidence interval bounds

  • Other diagnostic information is available via the analyzer’s diagnostics attribute

Example:

# For file-based initialization
results = analyzer.run_geolift_analysis()

# Access results
print(f"ATT: {results['att']:.2f}")
print(f"P-value: {results['p_value']:.3f}")

# Plot results
analyzer.plot_results(output_path="path/to/output.png")
plot_results(output_path: str | None = None) -> str

Generate and save a time-series visualization of period-by-period ATT, the overall ATT line, and CI band (if available). Returns the saved image path. When output_path is None, saves to <output_dir>/uplift_timeseries.png.

Recipe Scripts

DonorEvaluator

Script for identifying optimal control markets. Located in recipes/donor_evaluator.py.

# Run as a standalone script
python recipes/donor_evaluator.py --config data-config/donor_eval_config.yaml

Configuration

The donor evaluator requires a YAML configuration file with the following structure:

# donor_eval_config.yaml (example)
data_path: "data-config/synthetic_geolift_multi.csv"
shapemap_file: "shapemap/nielsentopo.json"
treatment_locations: ["501", "502", "503"]
pre_treatment_periods: 60
evaluation_metrics: ["correlation", "rmse", "mape", "dtw"]
min_donors: 10
max_donors: 30
output_dir: "outputs/multicell_donor_eval"
parallel: true
n_jobs: -1

Power Analysis

Script for power analysis and experimental design. Located in recipes/power_calculator_sparsesc.py.

# Run as a standalone script (GPU optional)
python recipes/power_calculator_sparsesc.py \
  --config data-config/power_analysis_config.yaml \
  --use-gpu --jobs -1

Configuration

The power calculator requires a YAML configuration file with the following structure:

# power_analysis_config.yaml (example)
effect_sizes: [0.01, 0.02, 0.05, 0.1, 0.15]
alpha: 0.05
output_dir: "outputs/multicell_power_analysis"
n_simulations: 500
model_type: "sparsesc_simulation"
parallel: true
n_jobs: -1
use_gpu: true

Inference (Stage 3)

Script for running SparseSC inference and saving results/plots. Located in recipes/geolift_multi_cell.py.

python recipes/geolift_multi_cell.py --config data-config/geolift_analysis_config.yaml

Configuration (excerpt)

data_path: "data-config/synthetic_geolift_multi.csv"
location_col_name: "location"
date_col_name: "date"
date_format: "%d/%m/%Y"
outcome_col_name: "Y"
treatment_unit_ids: [501, 502, 503]
intervention_date_str: "01/03/2023"
output_dir: "outputs/multicell_geolift_analysis"
create_plots: true

Diagnostics and Results

The analyzer stores a compact dictionary of top-level results (e.g., att, p_value, CI bounds) and keeps detailed diagnostics (weights, synthetic controls, effect paths) in analyzer.diagnostics.

Utility Functions

Data Preparation

from geolift.data_handler import load_and_prepare_data

Configuration Management

from geolift.config_manager import load_config
cfg = load_config('data-config/geolift_analysis_config.yaml')

Result Classes

GeoLiftResults

Contains analysis results and methods for interpretation.

Attributes

  • absolute_lift (float): Absolute treatment effect

  • relative_lift (float): Relative treatment effect (percentage)

  • confidence_interval (tuple): Lower and upper confidence bounds

  • p_value (float): Statistical significance p-value

  • roi (float): Return on investment

  • incremental_revenue (float): Total incremental revenue

Methods

summary()

Print comprehensive results summary.

plot_time_series()

Generate time series plot showing treatment vs synthetic control.

plot_lift_analysis()

Create pre/post treatment comparison plots.

export_html_report(filename, **kwargs)

Export results to HTML report.

Parameters:

  • filename (str): Output filename

  • include_technical_details (bool, optional): Include statistical details. Default: True

DonorResults

Contains donor evaluation results.

Attributes

  • best_donors (list): List of optimal control market IDs

  • donor_weights (dict): Weights for each donor market

  • correlation_matrix (DataFrame): Correlation between treatment and potential donors

Methods

plot_donor_map()

Visualize donor markets on geographic map.

summary()

Print donor evaluation summary.

from geolift.data_handler import load_and_prepare_data


### Configuration Management

```python
from geolift.config_manager import load_config
cfg = load_config('data-config/geolift_analysis_config.yaml')

CLI Entrypoints (recipes)

GeoLift provides recipe scripts under recipes/ for common workflows:

  • Power Analysis: recipes/power_calculator_sparsesc.py

  • Donor Evaluation: recipes/donor_evaluator.py

  • Inference: recipes/geolift_multi_cell.py

Configuration Schema

YAML Configuration

# See the YAML files in data-config/ for full examples used by the recipes.

Error Handling

Common Exceptions

GeoLift raises GeoLiftAnalyzerError (analysis), GeoLiftDataError (data prep), and GeoLiftConfigError (configuration) with descriptive messages. Wrap calls in try/except if you need to catch and handle errors programmatically.

Advanced Usage

For advanced usage of SparseSC, see the upstream documentation. GeoLift wraps SparseSC with a pipeline-focused API and recipes.

For more examples and advanced usage patterns, see Advanced Topics.