Random Effects
Model unobserved heterogeneity, correlation structures, and hierarchical dependencies using latent Gaussian components via random=[...].
What are Random Effects?
Random effects capture variation that cannot be explained by fixed covariates alone. They are essential for:
- Hierarchical data - students within schools, patients within hospitals
- Repeated measurements - multiple observations per subject over time
- Spatial correlation - nearby locations share similar characteristics
- Overdispersion - extra variability beyond what the likelihood explains
In pyINLA, random effects are specified using the random key in your model dictionary, with each effect defined by an id (the grouping variable) and a model (the correlation structure).
Quick Syntax
formula = {
'response': 'y',
'fixed': ['x1', 'x2'], # Intercept included by default
'random': [
{'id': 'group_id', 'model': 'iid'}, # Group-level random intercepts
]
}
result = pyinla(formula=formula, family='gaussian', data=df)Available Models
IID (Independent)
Independent and identically distributed random effects. Perfect for group-level intercepts, overdispersion, and simple hierarchical structures.
IIDKD (k-dimensional)
Correlated k-dimensional random effects with Wishart prior. For random intercept-slope models and multivariate outcomes.
RW1 (Random Walk)
First-order random walk for smooth temporal trends. Ideal for time series with local dependence.
RW2 (Second-order)
Second-order random walk for smoother temporal trends. Penalizes curvature for gradual, smooth changes over time.
AR1 (Autoregressive)
First-order autoregressive process with correlation parameter. Classic time series dependence structure with exponentially decaying correlation.
AR(p) (Higher-order)
Autoregressive process of order p (1-10) with PACF parameterization. For complex temporal dependence beyond simple exponential decay.
Seasonal
Periodic seasonal effects where sums over m consecutive values are IID Gaussian. For monthly, quarterly, or other cyclic patterns.
Besag (ICAR)
Intrinsic Conditional Autoregressive model for areal spatial data. Captures spatial dependence where neighboring regions have similar values.
BYM2
Besag-York-Mollie reparameterization with PC priors. Combines structured (ICAR) and unstructured (IID) spatial effects with interpretable hyperparameters.
SPDE (Matérn)
Stochastic Partial Differential Equation approach for continuous spatial fields with Matérn covariance. Uses triangular meshes and PC priors.
fbesag (Partitioned)
Adaptive Besag where the graph is split into P partitions and each partition has its own log-precision. Useful when different regions need different smoothness. Accessed via the pyinla.gmrfs wrapper.
Generic0 (User-supplied Q)
Bring your own structure matrix C; pyinla scales it by a precision hyperparameter to give Q = τ · C. The most flexible building block; use when Besag/RW1/etc. don't capture the dependence you have in mind.
Hyperparameter Customization
Each random effect has hyperparameters (e.g., precision for IID) that control the variance structure. You can customize these using the hyper key:
'random': [
{
'id': 'group_id',
'model': 'iid',
'hyper': [{
'prior': 'pc.prec', # PC prior for precision
'param': [1, 0.01], # P(sigma > 1) = 0.01
'initial': 4, # Starting value for log(precision)
'fixed': False # Estimate (don't fix)
}]
}
]Choosing the Right Model
- IID - Use when groups are exchangeable with no inherent ordering or spatial structure
- IIDKD - Use for correlated multivariate random effects (e.g., random intercepts and slopes)
- RW1/RW2 - Use for temporal data where adjacent time points should be similar
- AR1 - Use for time series with exponentially decaying correlation
- AR(p) - Use for time series with complex dependence requiring higher-order autoregression
- Seasonal - Use for periodic patterns (monthly, quarterly, weekly cycles)
- Besag (ICAR) - Use for areal spatial data where neighboring regions have similar values
- BYM2 - Use for disease mapping combining structured and unstructured spatial effects with interpretable priors
- SPDE (Matérn) - Use for continuous spatial data (point-referenced) with Matérn covariance via mesh approximation
- fbesag (Partitioned) - Use when a Besag graph has subregions that should be smoothed at different scales (e.g. one log-precision per partition). Accessed through the
pyinla.gmrfswrapper rather than asmodel='…'. - Generic0 - Use when none of the named structures fit and you want to supply your own precision matrix:
Q = τ · Cwith C provided by you.
Supported Latent Model Reference
The latent model types recognised by pyINLA, grouped by use case.
Exchangeable / IID Models
| Keyword | Description |
|---|---|
iid | Independent and identically distributed random effects |
iidkd | k-dimensional correlated IID |
Temporal Models
| Keyword | Description |
|---|---|
rw1 | First-order random walk |
rw2 | Second-order random walk (smoother) |
ar1 | First-order autoregressive |
ar | Higher-order AR(p), p=1-10 |
seasonal | Seasonal/periodic effects |
Spatial Models
| Keyword | Description |
|---|---|
besag | Intrinsic CAR (ICAR) model |
bym | Original BYM (structured + unstructured spatial). Prefer bym2. |
bym2 | Reparameterized BYM with PC priors |
| SPDE object | SPDE approach for Matérn fields (limited safety-layer surface) |
pyinla.gmrfs.fbesag(…) | Partitioned Besag with one log-precision per partition (cgeneric wrapper, not a model='…' keyword) |
Design Matrix / Linear Models
| Keyword | Description |
|---|---|
linear | Latent single-slope with explicit Gaussian prior |
clinear | Constrained linear effect (slope bounded via reparameterization) |
Custom Precision Models
User-supplied precision matrix C; pyinla wraps it with one precision hyperparameter.
Both model="generic" and model="generic0" are accepted and resolve to the same precision structure.
| Keyword | Precision matrix Q | Hyperparameters |
|---|---|---|
generic0 | Q = τ · C | log τ |