API Reference

Technical reference for the shipped GeoLift interfaces.

Interface Hierarchy

Primary operational interface:

  • installed geolift CLI

Programmatic interface:

  • GeoLiftAnalyzer
  • load_config
  • load_and_prepare_data
  • process_sparse_sc_results

Compatibility interfaces:

  • runme.py
  • recipes/

For the exact CLI command surface, see CLI Reference.

Installed CLI

Installed commands:

  • geolift power
  • geolift donors
  • geolift infer
  • geolift pipeline

Shared flags on all commands:

  • --config
  • --output-dir
  • --jobs
  • --use-gpu
  • --no-progress
  • --quiet

Infer-only flags:

  • --data
  • --create-plots
  • --no-create-plots

Pipeline-only flags:

  • --skip-power
  • --skip-donor
  • --only-inference
  • --report
  • --no-report

Pipeline config contract:

  • pipeline --config accepts one canonical stage YAML path
  • GeoLift resolves sibling canonical YAMLs from the same directory
  • there is no separate pipeline config schema

Core Classes

GeoLiftAnalyzer

Main orchestration class for causal inference analysis using SparseSC-backed estimation.

Initialization modes:

  1. File-based: config_path plus data_path
  2. Direct data: prepared outcomes_df plus unit_treatment_periods

File-based example with user-owned config and data paths:

from geolift import GeoLiftAnalyzer

analyzer = GeoLiftAnalyzer(
    config_path="/path/to/geolift_analysis_config.yaml",
    data_path="/path/to/input.csv",
)

Source-checkout example:

from geolift import GeoLiftAnalyzer

analyzer = GeoLiftAnalyzer(
    config_path="data-config/geolift_analysis_config.yaml",
    data_path="data-config/synthetic_geolift_multi.csv",
)

Direct-data example:

import pandas as pd
from geolift import GeoLiftAnalyzer

outcomes_df = pd.DataFrame(...)
unit_treatment_periods = pd.Series(...)

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_max_n_pl": 1000,
        "sparse_sc_level": 0.95,
    },
)

run_geolift_analysis()

Executes the full inference workflow and returns the compact top-level results dictionary.

Returned fields include:

  • att
  • p_value
  • ci_lower
  • ci_upper
  • se
  • significant

Detailed diagnostics remain on analyzer.diagnostics.

run_analysis()

Primary convenience entry point that delegates to run_geolift_analysis(). Either method is valid on the shipped class.

plot_results(output_path: str | None = None) -> str

Generates and saves the uplift time-series plot. When output_path is omitted, the plot is written to <output_dir>/uplift_timeseries.png.

Utility Functions

load_and_prepare_data(...)

from geolift.data_handler import load_and_prepare_data

File-based data preparation helper used by the analyser path.

load_config(path)

from geolift.config_manager import load_config

Loads one YAML config file.

process_sparse_sc_results(sparse_sc_results, config)

from geolift.results_processor import process_sparse_sc_results

Transforms SparseSC outputs into the compact top-level results plus the richer diagnostics payload.

Output Artifacts

Inference outputs:

  • geolift_results.json
  • geolift_diagnostics.json
  • uplift_timeseries.png when plot generation is enabled

Power outputs:

  • power_analysis_results.csv
  • power_curves.png

Donor outputs:

  • donor_eval_results.csv
  • donor_map_*.png

Pipeline reports:

  • geolift_pipeline_report.md
  • geolift_pipeline_report.html

Compatibility Surfaces

runme.py and the scripts in recipes/ remain available for compatibility. They are not the primary documented interface.

Migration map:

  • source-checkout: python runme.py -> geolift pipeline --config data-config/geolift_analysis_config.yaml
  • source-checkout: python recipes/power_calculator_sparsesc.py ... -> geolift power ...
  • source-checkout: python recipes/donor_evaluator.py ... -> geolift donors ...
  • source-checkout: python recipes/geolift_multi_cell.py ... -> geolift infer ...