statspai.geolift

geolift

Geo-experiment ("geo-lift") causal measurement.

Estimates the incremental lift of an intervention switched on in a set of treated geographies, against a synthetic counterfactual built from the untreated geographies. See :func:geolift.

geolift

geolift(data: DataFrame, outcome: str, geo: str, time: str, treated_geos: Any, treatment_time: Any, *, agg: str = 'mean', method: str = 'classic', alpha: float = 0.05, **synth_kwargs: Any) -> CausalResult

Estimate geo-experiment lift via synthetic control.

Parameters:

Name	Type	Description	Default
data	DataFrame	Long panel: one row per (geo, time).	required
outcome	str	Outcome / KPI column (e.g. sales, conversions).	required
geo	str	Geography (market) id column.	required
time	str	Time column.	required
treated_geos	scalar or sequence	The geography (or geographies) the intervention was switched on in.	required
treatment_time	any	First treated period (inclusive). Earlier periods train the synthetic control.	required
agg	('mean', 'sum')	How to aggregate multiple treated geos into one treated series.	'mean'
method	str	Synthetic-control method passed to :func:sp.synth (e.g. 'classic', 'augmented', 'sdid').	'classic'
alpha	float	Significance level forwarded to :func:sp.synth.	0.05
**synth_kwargs	Any	Extra keyword arguments forwarded to :func:sp.synth (e.g. covariates, inference).	{}

Returns:

Type	Description
CausalResult	estimand='ATT' — the average post-period lift of the treated markets. model_info adds treated_geos, agg, and a relative_lift_pct (lift as a share of the synthetic counterfactual).

Examples:

>>> import statspai as sp
>>> res = sp.geolift(
...     df, outcome='sales', geo='dma', time='week',
...     treated_geos=['NYC', 'LA'], treatment_time=40,
... )
>>> res.estimate, res.model_info['relative_lift_pct']