HSGP for econometricians

A Hilbert space Gaussian process (HSGP) approximates a Gaussian process with a finite basis expansion. Its coefficients have covariance-dependent priors. Use it to specify a smooth conditional component and assess its interaction with the other model components.

Basis size and effective flexibility

The basis count m sets the size of the approximation. It is different from an OLS residual-degrees-of-freedom calculation. Coefficient shrinkage depends on covariance amplitude and lengthscale. It can reduce effective flexibility relative to an unpenalised expansion, but does not guarantee a particular effective degree count or prevent overfitting.

HSGP.parameterize_from_data(...) and approx_hsgp_hyperparams(...) provide recommendations under their covariance and lengthscale assumptions. This is an available construction route. It is not used for every configuration. The boolean time-varying defaults in PanelMMM use m=200 and resolve L from the data when it is unspecified.

A finite m does not perfectly reproduce the full GP. Extra basis coefficients have continuous priors; shrinkage does not set them exactly to zero. Fits with m=50 and m=500 need not be identical. Basis size, domain boundary L, lengthscale assumptions and inference accuracy all affect the approximation. Check stability of the quantities you intend to report across reasonable settings. Record the settings rather than selecting them solely to obtain a preferred media estimate.

The PyMC HSGP reference explains the reduced-rank approximation and the roles of m and L.

Baseline and media attribution

A smooth baseline can compete with media that varies on similar time scales. HSGP regularisation can stabilise estimation, but cannot guarantee separation of these components. Basis orthogonality in the mathematical construction does not make the realised baseline orthogonal to observed media regressors.

Multicollinearity concerns limited independent variation between regressors. Backdoor confounding concerns treatment assignment and the outcome-generating process. They are different problems. Neither HSGP nor satisfactory predictive fit establishes a causal media effect.

Compare attribution under plausible baseline, lengthscale and media priors. Treat contributions as conditional model allocations unless a separate identification argument supports a causal interpretation.

Holidays and dated events

Use control columns when binary holiday indicators match the intended model. Use EventEffect with add_events(...) when a continuous dated response shape is appropriate. A Gaussian event basis is an assumption about temporal shape; it is not intrinsically more realistic than a dummy variable.

This example builds an event model from the repository’s timeseries demo. Run it from the repository root. The following fit uses a small sampling budget for workflow illustration and does not establish statistical adequacy.

import pandas as pd
from pymc_extras.prior import Prior

from ammm.mmm import GeometricAdstock, LogisticSaturation
from ammm.mmm.events import EventEffect, GaussianBasis
from ammm.mmm.panel import PanelMMM

dataset = pd.read_csv("data/demo/timeseries/dataset.csv")
dataset["date"] = pd.to_datetime(dataset["date"])
X = dataset.drop(columns="revenue")
y = dataset["revenue"]

df_holidays = pd.DataFrame({
    "name": ["Black Friday 2023"],
    "start_date": ["2023-11-24"],
    "end_date": ["2023-11-25"],
})
holiday_effect = EventEffect(
    basis=GaussianBasis(),
    effect_size=Prior("Normal", mu=0, sigma=1, dims="holiday"),
    dims="holiday",
)
mmm = PanelMMM(
    date_column="date",
    target_column="revenue",
    channel_columns=[f"channel_{i}" for i in range(1, 7)],
    adstock=GeometricAdstock(l_max=4),
    saturation=LogisticSaturation(),
)
mmm.add_events(df_events=df_holidays, prefix="holiday", effect=holiday_effect)
mmm.build_model(X, y)
idata = mmm.fit(X, y, draws=200, tune=200, chains=2, cores=2, random_seed=42)

Current event serialisation retains the event DataFrame and effect specification. See Save and Load.

Periodic HSGP and Fourier seasonality

HSGPPeriodic represents a repeating function with a fixed period and shared basis coefficients. It does not by itself let the seasonal shape drift across years. Fixed Fourier seasonality also repeats. Drift requires additional structure that explicitly varies the seasonal function over time.

The approaches differ in basis construction and prior assumptions. HSGP remains a finite basis approximation; it does not require the full dense GP covariance inversion described by an exact GP. Runtime depends on basis size, model dimensions and posterior geometry. Do not assume a universal speed or statistical ranking.

A general HSGP trend with low-order Fourier seasonality is one available specification. Check whether the data distinguish those components from media before using their decomposition for decisions.