pyreml

pyreml is a general-purpose linear mixed model solver. It fits linear mixed models for a wide range of applications: quantitative genetics, spatial statistics, health sciences, among others.

Models are fitted by direct differentiation of the Restricted Maximum Likelihood (REML), using PyTorch for variance parameter estimation. It benefits from PyTorch parallelization and GPU acceleration.

Installation

Install pyreml with pip or conda:

pip install pyreml

The model

pyreml fits the linear mixed model:

\[ \mathbf{y} = \mathbf{X}\mathbf{\beta} + \mathbf{Z}\mathbf{u} + \mathbf{r}, \qquad \mathbf{u} \sim \mathcal{N}(\mathbf{0}, \mathbf{G}), \qquad \mathbf{r} \sim \mathcal{N}(\mathbf{0}, \mathbf{R}), \]

where \(\mathbf{X}\) and \(\mathbf{Z}\) are the incidence matrices of the fixed effects \(\mathbf{\beta}\) and the random effects \(\mathbf{u}\), and \(\mathbf{G}\) and \(\mathbf{R}\) are the covariances of \(\mathbf{u}\) and \(\mathbf{r}\). These two covariances are assembled from the structures declared by the user (see Variance structures).

Example

As an illustrative example, let’s realize the genetic analysis of the larix dataset, using the genetic helpers provided by pyreml. This model provides a heteroscedastic structure to the residuals.

from pprint import pprint
from pyreml import (
    MixedModel,
    Random,
    Residual,
    A_pedigree,
    prepare_pedigree,
    larix as df,
)

df = df[df["year"] == 2000].copy()
ped = prepare_pedigree(df[["ID","SIRE","DAM"]])
K = A_pedigree(ped)

model = MixedModel.from_dataframe(
    data     = df,
    response = "height",
    fixed    = "1 + C(BLOC)",
    random   = Random(
        formula      = "1",
        unit         = "ID",
        right_hand   = "str",
        covariance   = K,
        matrix_index = ped["id"].tolist(),
    ),
    residual = Residual(
        right_hand = "het",
        het_formula = "1 + C(BLOC)",
    ),
    device = "cuda",
)

model.fit()

pprint(model.random[0].variance)
pprint(model.residual.variance)
model.random[0].table.head()

Manual contents

Citation

Please cite this package as:

Marchal, A., & Raimondi, D. (2026). pyreml - general-purpose linear mixed model solver [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.20826541

Code

The code is available at this address.

License

pyreml is distributed with a GPL-3.0 license.