pyLGM

General-purpose latent Gaussian models for Python — the model class behind INLA.
Deterministic Bayesian inference for structured data. No MCMC, no new dependencies.

Documentation · How it works · Comparison · Examples · Theory

What it does

Declare structure — groups, space, time, frequency, networks — and pyLGM returns a posterior for each component, not just a prediction. Fits run in seconds through Laplace approximations and INLA-style integration, and are deterministic: same data, same answer, no convergence diagnostics.

Partial pooling in one picture: noisy small-area rates (left, near zero) are pulled toward their neighbours, while well-observed areas keep their signal. Marker size is the expected count. From the disease-mapping example.

Install

pip install pylgm
pip install "pylgm[spark]"   # optional: Spark data boundary

Requires Python ≥ 3.11.

30-second example

A Poisson model with a per-region random intercept, fit with the Laplace engine:

import pandas as pd
from pylgm import Fixed, IID, LGM, Poisson

frame = pd.DataFrame({
    "region": ["north", "north", "north", "south", "south", "south"],
    "time":   [1, 2, 3, 1, 2, 3],
    "x":      [0.0, 0.5, 1.0, 0.0, 0.5, 1.0],
    "count":  [3, 5, 8, 2, 3, 5],
})

model = LGM(
    response="count",
    likelihood=Poisson(),                                # canonical log link
    predictor=Fixed("1 + x")                             # fixed effects
        + IID("region", index="region", precision=2.0),  # random intercept per region
    panel=("region",),
    time="time",
)

result = model.fit(frame, engine="laplace")
print("fitted_mean:", result.fitted_mean.round(3).tolist())
# fitted_mean: [3.254, 4.986, 8.15, 2.201, 3.373, 5.513]

The same model can be declared in YAML and loaded with pylgm.config.load_model.

Reproducing a published result

examples/columbus_spatial_econometrics reproduces the reference result of spatial econometrics — Anselin (1988), Table 12.1, 49 Columbus OH neighbourhoods:

OLS matching the published numbers exactly verifies the data and spec; the SAR fit then lands next to the published ML spatial-error estimates, and recovers the finding that ignoring spatial correlation overstates the income effect by 1.76×.

A network that changes every year

examples/state_income_dynamic_network fits 48 US states over 1997–2007 with one network per year, then knocks out 20% of the panel and restores it:

~5× closer than the obvious baselines. The same example reports where it loses — a last-value forecast beats it on level forecasts, because the fitted γ ≈ 1 says log income is near a random walk.

Why not just use XGBoost?

Often you should — and the comparison page says so with measured numbers rather than adjectives. Both problems below are simulated, so the true surface is known and scored directly:

pyLGM wins where the per-unit sample is thin but the units are related, and returns 95% intervals that cover the truth 99% of the time. Gradient boosting wins where the signal is interactions among covariates and you have the rows to learn them. Reproduce both with examples/method_comparison.

What's in the box

Documentation

Full docs: https://ardea00.github.io/pylgm/

• How it works — one fit() call end to end, then prediction and forecasting
• Comparison — against regression, gradient boosting and MCMC, including where pyLGM loses
• Theory — the model class and every structured effect, with references
• Examples — 21 runnable scripts

Roadmap

What's shipped and what's next is on the roadmap; scope and compatibility policy on the internals page.

Contributing

Issues and pull requests welcome — see docs/development.md for the test setup. main is protected: PRs need the full CI matrix green before merge.

License

MIT