Use the Python API

For file-based inference, initialise the public analyser with a config and data path:

from geolift import GeoLiftAnalyzer

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

if result["status"] == "failed":
    raise RuntimeError(result["errors"])
if result["status"] == "partial":
    print("Review warnings:", result["warnings"])

Direct-data construction is also supported by GeoLiftAnalyzer; the panel must be wide with units as rows and datetime-like periods as columns, with a unit- indexed treatment-period series. Use the Python API reference for signatures.

Power is available through geolift.power.SparseSCPowerCalculator. Donor screening is available through geolift.donor_evaluator.DonorEvaluator, but neither is re-exported from the package root. Prefer the CLI for versioned file-based runs because it writes the maintained artefact family.

Complete direct-data example

Run this from the repository root after installation. This example uses the shipped synthetic panel, treats three units from 2 March 2023, and leaves the other units untreated. It demonstrates the API contract, not causal validity.

import pandas as pd
from geolift import GeoLiftAnalyzer

panel = pd.read_csv("data-config/synthetic_geolift_multi.csv")
panel["date"] = pd.to_datetime(panel["date"], format="%d/%m/%Y")
outcomes = panel.pivot(index="location", columns="date", values="Y")
launch = pd.Timestamp("2023-03-02")
treatment_periods = pd.Series(pd.NaT, index=outcomes.index, dtype="datetime64[ns]")
treatment_periods.loc[[501, 502, 503]] = launch

analyser = GeoLiftAnalyzer(
    outcomes_df=outcomes,
    unit_treatment_periods=treatment_periods,
    intervention_date=launch,
    config={
        "sparse_sc_model_type": "retrospective",
        "sparse_sc_fast_estimation": True,
        "sparse_sc_max_n_pl": 100,
        "sparse_sc_placebo_seed": 110011,
        "sparse_sc_return_ci": True,
        "sparse_sc_level": 0.95,
    },
)
result = analyser.run_analysis()
print(result["status"], result["att"], result["p_value"])

Direct-data mode returns the result mapping. It does not write the file-mode artefact family automatically. Use the CLI or file-based constructor when those files are required.