Fixed Effects

What is a Fixed Effect?

A fixed effect is a covariate whose coefficient is shared across all observations: a single parameter $\beta_j$ that does not vary by group, location, or time. In a typical regression formula:

Each $\beta_j$ is one fixed effect. The intercept $\beta_0$ is a fixed effect too, automatically added unless you remove it.

The Linear Predictor

In generalized linear (mixed) models, the expected value of the response $\mathbf{y}$ is connected to a linear predictor $\boldsymbol{\eta}$ via a link function $g(\cdot)$:

Fixed Effects in the Latent Field

In INLA, fixed effects are part of the latent Gaussian field $\mathbf{x}$. By default they get an independent Gaussian prior (a joint prior with a user-supplied correlation matrix is also possible, see correlation_matrix below):

where $\mu_j$ is the prior mean and $\tau_j$ is the prior precision. The pyINLA defaults are listed below.

You can override these globally or per-coefficient through control['fixed'] (see below).

Adding Fixed Effects in pyINLA

pyINLA describes the model with a Python dict. The "fixed" key holds a list of terms: a string is looked up as a column in data, a vector is taken as raw values, and a (name, values) tuple lets you supply a labelled column directly. The intercept is included by default and is controlled separately through model["intercept"].

Quickstart with synthetic data

The example below is fully runnable: it generates a small synthetic dataset and fits a Gaussian regression with three covariates.

import numpy as np
import pandas as pd
from pyinla import pyinla

# Synthetic dataset: y = 2 + 0.05*age + 0.7*(sex=='M') + 0.02*income + noise
rng = np.random.default_rng(0)
n = 200
age    = rng.normal(50, 10, n)
sex    = rng.choice(["F", "M"], size=n)
income = rng.normal(60, 15, n)
y = (2.0
     + 0.05 * age
     + 0.7 * (sex == "M").astype(float)
     + 0.02 * income
     + rng.normal(0, 0.5, n))

df = pd.DataFrame({"y": y, "age": age, "sex": sex, "income": income})

model = {
    "response": "y",
    "fixed":    ["age", "sex", "income"],
}

result = pyinla(model=model, family="gaussian", data=df)
print(result.summary_fixed)

Output

                 mean        sd  0.025quant  0.5quant  0.975quant      mode           kld
(Intercept)  1.858775  0.243689    1.380424  1.858775    2.337126  1.858775  1.989465e-09
age          0.053095  0.003561    0.046104  0.053095    0.060087  0.053095  1.989470e-09
sexM         0.689530  0.068038    0.555975  0.689530    0.823086  0.689530  1.989433e-09
income       0.019892  0.002264    0.015448  0.019892    0.024336  0.019892  1.989472e-09

This fits four fixed effects: (Intercept), age, sexM (the sex column is categorical and gets expanded; F is the reference level), and income.

Intercept only ($\eta_i = \beta_0$)

The intercept is added automatically when "fixed" is empty:

# intercept is included by default
model = {"response": "y", "fixed": []}

# or explicitly
model = {"response": "y", "fixed": [], "intercept": True}

One covariate ($\eta_i = \beta_0 + \beta_1 z_i$)

# Refer to a column 'z' in your DataFrame
model = {"response": "y", "fixed": ["z"]}
result = pyinla(model=model, family="gaussian", data=df)

Multiple covariates ($\eta_i = \beta_0 + \beta_1 z_{1i} + \beta_2 z_{2i}$)

model = {"response": "y", "fixed": ["z1", "z2"]}

Direct vectors (no DataFrame)

You can also pass raw vectors instead of column names. The response can be a vector too, so a DataFrame is optional:

# raw vectors (each must have len == len(y))
model = {"response": y, "fixed": [z]}

# labelled tuples for readable output
model = {"response": y, "fixed": [("z", z)]}

# a (n x p) matrix expands to columns name1, name2, ...
model = {"response": y, "fixed": [("feat", X)]}  # X.shape == (n, p)

# raw (n x p) matrix without a label: columns are auto-named
# fixed_<col_idx> (sequential), matching R's `y ~ X` formula expansion
model = {"response": y, "fixed": [X]}        # X.shape == (n, p)

Removing the Intercept

Use the token "-1" or "0" in the fixed list, or set model["intercept"] = False:

# with a token
model = {"response": "y", "fixed": ["-1", "age", "sex"]}

# equivalent
model = {"response": "y", "fixed": ["age", "sex"], "intercept": False}

You may also supply a custom intercept vector via model["intercept"] = vector (length $n$); it appears as (Intercept) in the output.

Categorical Covariates

Non-numeric named columns are automatically expanded into dummy variables (via pandas.get_dummies, named name + level with no separator, e.g. groupA, groupB). pyINLA uses treatment contrasts: with an intercept (the default), the first sorted level is dropped to avoid collinearity; without an intercept (intercept=False), all levels are kept.

Interactions

Use "z1*z2" for main effects plus their interaction, or "z1:z2" for the product term only. Three-way forms "z1*z2*z3" and "z1:z2:z3" are supported the same way. Duplicates are removed automatically.

# main effects + interaction (expanded internally)
model = {"response": "y", "fixed": ["z1*z2"]}

# product term only
model = {"response": "y", "fixed": ["z1", "z2", "z1:z2"]}

# three-way: z1, z2, z3, all pairwise + triple product
model = {"response": "y", "fixed": ["z1*z2*z3"]}

Interaction strings require the referenced variables to exist as named columns in data. If you don't have a DataFrame, precompute the products and pass them as labelled vectors, e.g. ("z1:z2", z1 * z2).

Nonlinear Transforms

Helpers like I(x^2) are not parsed yet. Build the column yourself and add it to your DataFrame:

df["age_sq"] = df["age"] ** 2
model = {"response": "y", "fixed": ["age", "age_sq"]}

Term Forms (At a Glance)

Each entry in model["fixed"] can be one of:

Other behaviour worth knowing:

• Intercept: included by default. Use model["intercept"] = False (or pass a length-$n$ vector for a custom intercept, labelled (Intercept)) or place the token "-1" or "0" inside "fixed" to drop it. Mixing add ("1") and drop ("-1"/"0") tokens in the same list raises an error.
• De-duplication and order: duplicate terms are dropped; the order of entries in "fixed" determines the order of fixed-effect components in the output.
• Whitespace: term strings are trimmed, so " x1 " resolves to "x1".
• Repeated names: if the same covariate is supplied more than once (e.g. as both a column reference and a labelled vector), only the first occurrence is kept and later duplicates are silently dropped.
• Missing or non-finite values in numeric covariates are treated as $0$.
• Data optional: you can omit data entirely if you pass the response and all fixed terms as vectors. Interaction strings still require named columns.

Configuring Priors with control['fixed']

The control['fixed'] dictionary controls priors and reporting for all fixed effects. Below are the available keys with their defaults.

How mean and prec resolve per coefficient

Both keys accept either a single number or a dict. They follow the same lookup logic, so the rules below apply to both.

Concrete example with model["fixed"] = ["age", "sex", "income"]:

control = {"fixed": {"mean": {"age": 1.0, "default": 0.5}}}
# resolved means: age = 1.0, sex = 0.5, income = 0.5

Names in the dict must match the expanded coefficient names, not the original column names. For a categorical covariate region expanded to regionB, regionC, target the dummies ("regionB": ...), not the source column.

Examples

The snippets below all reuse the df data frame and model dict from the previous section.

Tighter prior on all slopes:

result = pyinla(
    model=model,
    family="gaussian",
    data=df,
    control={"fixed": {"prec": 1.0}},
)
print(result.summary_fixed)

Per-coefficient priors:

control = {
    "fixed": {
        "mean":           {"age": 0.0, "income": 0.0},
        "prec":           {"age": 10.0, "income": 1.0},
        "mean_intercept": 2.0,
        "prec_intercept": 0.01,
    }
}
result = pyinla(model=model, family="gaussian", data=df, control=control)
print(result.summary_fixed)

Request the posterior correlation matrix:

control = {"fixed": {"correlation_matrix": True}}
result = pyinla(model=model, family="gaussian", data=df, control=control)

print(result.summary_fixed)              # per-coef posterior table
print(result.correlation_matrix_fixed)   # labelled NxN DataFrame
print(result.covariance_matrix_fixed)    # companion covariance

Output of result.correlation_matrix_fixed

             (Intercept)         z
(Intercept)     1.000000  0.031479
z               0.031479  1.000000

The matrix is a pandas.DataFrame whose rows and columns are labelled with the fixed-effect names after factor expansion ((Intercept), z, sexM, ...). Both correlation_matrix_fixed and covariance_matrix_fixed are None when the flag is off.

What You Get Back

After fitting, the result object exposes posterior summaries for each fixed effect:

Connecting Fixed Effects to the Response

pyINLA supports many likelihoods through the family= argument. The three most common choices, written in terms of the linear predictor $\boldsymbol{\eta}$, are below.

Other families are available (Gamma, Negative Binomial, survival models, Beta, etc.). See the Likelihoods page for the full catalogue.

Interpreting Fixed-Effect Coefficients

The meaning of a coefficient depends on the link scale (see Link Functions). The cards below cover the three most common cases.

Fixed‑Effect Extensions

Most fixed covariates belong in model['fixed'] and can have label‑specific priors via control['fixed']. When you need special treatment for a single slope, there are two useful patterns: