# ai-for-genome-interpretation-lab/pyreml architecture

> Architecture diagram of the GitHub repository ai-for-genome-interpretation-lab/pyreml, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ai-for-genome-interpretation-lab/pyreml
- Repository: https://github.com/ai-for-genome-interpretation-lab/pyreml
- Video tour (about a minute): https://gitdiagram.com/ai-for-genome-interpretation-lab/pyreml/video

## Overview

pyreml fits linear mixed models by building fixed- and random-effect designs, estimating covariance parameters with REML, and exposing fitted estimates and predictions. The main workflow runs through MixedModel, which coordinates Gaussian components, structured variance solving, and optimization. Separate genetic helpers prepare pedigree data and relationship matrices that users can supply as covariance inputs. The README also documents multivariate, random-regression, heteroscedastic, factor-analytic, spatial, and unobserved-level prediction capabilities. These are represented at their documented runtime entry points; unsampled internals and uncertain call links are omitted.

Main entry points: [`pyreml/MixedModel.py`](https://github.com/ai-for-genome-interpretation-lab/pyreml/blob/main/pyreml/MixedModel.py) (MixedModel), [`pyreml/GaussianComponents.py`](https://github.com/ai-for-genome-interpretation-lab/pyreml/blob/main/pyreml/GaussianComponents.py) (Random and residual), [`pyreml/Optimizer.py`](https://github.com/ai-for-genome-interpretation-lab/pyreml/blob/main/pyreml/Optimizer.py) (OptiMix), [`pyreml/Variance.py`](https://github.com/ai-for-genome-interpretation-lab/pyreml/blob/main/pyreml/Variance.py) (Variance structure)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_modeling["Model specification"]
  node_mixedmodel["MixedModel<br/>[MixedModel.py]"]
  node_components["Random and residual"]
  node_design["Model designs<br/>[MixedModel.py]"]
end

subgraph group_covariance["Covariance and solving"]
  node_variance["Variance structure<br/>[Variance.py]"]
  node_solve["Likelihood solves<br/>[Variance.py]"]
end

subgraph group_fitting["Estimation and results"]
  node_optimizer["OptiMix<br/>[Optimizer.py]"]
  node_fitted["Fit statistics<br/>[MixedModel.py]"]
  node_prediction["Effect prediction"]
end

subgraph group_genetics["Genetic utilities"]
  node_kinships["Pedigree preparation<br/>[kinships.py]"]
  node_relationship["Relationship matrices<br/>[kinships.py]"]
  node_larix[("Larix dataset<br/>[larix.py]")]
end

node_user(("Analyst"))
node_observations["Observation data"]
node_patsy["Patsy formulas"]
node_torch["PyTorch"]

node_user -->|"specifies model"| node_mixedmodel
node_observations -->|"provides data"| node_mixedmodel
node_mixedmodel -->|"builds designs"| node_design
node_design -->|"builds formula matrices"| node_patsy
node_mixedmodel -->|"uses effects"| node_components
node_components -->|"builds formula matrices"| node_patsy
node_mixedmodel -->|"builds decomposition"| node_variance
node_components -->|"supplies covariance blocks"| node_variance
node_variance -->|"provides structure"| node_solve
node_mixedmodel -->|"runs fitting"| node_optimizer
node_optimizer -->|"evaluates loss"| node_mixedmodel
node_mixedmodel -->|"evaluates likelihood"| node_solve
node_solve -.->|"uses tensor operations"| node_torch
node_optimizer -.->|"uses optimizers"| node_torch
node_mixedmodel -->|"computes estimates"| node_fitted
node_mixedmodel -->|"dispatches effect results"| node_components
node_user -->|"prepares pedigree"| node_kinships
node_kinships -->|"computes matrices"| node_relationship
node_user -->|"requests genomic matrix"| node_relationship
node_relationship -->|"supplies covariance"| node_components
node_user -->|"loads example data"| node_larix
node_components -->|"predicts new levels"| node_prediction
node_fitted -->|"returns results"| node_user
node_prediction -->|"returns predictions"| node_user

click node_mixedmodel "https://github.com/ai-for-genome-interpretation-lab/pyreml/blob/main/pyreml/MixedModel.py"
click node_components "https://github.com/ai-for-genome-interpretation-lab/pyreml/blob/main/pyreml/GaussianComponents.py"
click node_design "https://github.com/ai-for-genome-interpretation-lab/pyreml/blob/main/pyreml/MixedModel.py"
click node_variance "https://github.com/ai-for-genome-interpretation-lab/pyreml/blob/main/pyreml/Variance.py"
click node_solve "https://github.com/ai-for-genome-interpretation-lab/pyreml/blob/main/pyreml/Variance.py"
click node_optimizer "https://github.com/ai-for-genome-interpretation-lab/pyreml/blob/main/pyreml/Optimizer.py"
click node_fitted "https://github.com/ai-for-genome-interpretation-lab/pyreml/blob/main/pyreml/MixedModel.py"
click node_prediction "https://github.com/ai-for-genome-interpretation-lab/pyreml/blob/main/pyreml/GaussianComponents.py"
click node_kinships "https://github.com/ai-for-genome-interpretation-lab/pyreml/blob/main/pyreml/kinships.py"
click node_relationship "https://github.com/ai-for-genome-interpretation-lab/pyreml/blob/main/pyreml/kinships.py"
click node_larix "https://github.com/ai-for-genome-interpretation-lab/pyreml/blob/main/pyreml/larix.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mixedmodel,node_components,node_design toneBlue
class node_variance,node_solve toneAmber
class node_optimizer,node_fitted,node_prediction toneMint
class node_kinships,node_relationship,node_larix toneRose
class node_user,node_observations,node_patsy,node_torch toneIndigo
```

## Components

### Model specification

- [MixedModel](https://github.com/ai-for-genome-interpretation-lab/pyreml/blob/main/pyreml/MixedModel.py): `pyreml/MixedModel.py`
- [Random and residual](https://github.com/ai-for-genome-interpretation-lab/pyreml/blob/main/pyreml/GaussianComponents.py): `pyreml/GaussianComponents.py`
- [Model designs](https://github.com/ai-for-genome-interpretation-lab/pyreml/blob/main/pyreml/MixedModel.py): `pyreml/MixedModel.py`

### Covariance and solving

- [Variance structure](https://github.com/ai-for-genome-interpretation-lab/pyreml/blob/main/pyreml/Variance.py): `pyreml/Variance.py`
- [Likelihood solves](https://github.com/ai-for-genome-interpretation-lab/pyreml/blob/main/pyreml/Variance.py): `pyreml/Variance.py`

### Estimation and results

- [OptiMix](https://github.com/ai-for-genome-interpretation-lab/pyreml/blob/main/pyreml/Optimizer.py): `pyreml/Optimizer.py`
- [Fit statistics](https://github.com/ai-for-genome-interpretation-lab/pyreml/blob/main/pyreml/MixedModel.py): `pyreml/MixedModel.py`
- [Effect prediction](https://github.com/ai-for-genome-interpretation-lab/pyreml/blob/main/pyreml/GaussianComponents.py): `pyreml/GaussianComponents.py`

### Genetic utilities

- [Pedigree preparation](https://github.com/ai-for-genome-interpretation-lab/pyreml/blob/main/pyreml/kinships.py): `pyreml/kinships.py`
- [Relationship matrices](https://github.com/ai-for-genome-interpretation-lab/pyreml/blob/main/pyreml/kinships.py): `pyreml/kinships.py`
- [Larix dataset](https://github.com/ai-for-genome-interpretation-lab/pyreml/blob/main/pyreml/larix.py): `pyreml/larix.py`

### Other components

- **Analyst**
- **Observation data**
- **Patsy formulas**
- **PyTorch**

## Connections

- Analyst → MixedModel: specifies model
- Observation data → MixedModel: provides data
- MixedModel → Model designs: builds designs
- Model designs → Patsy formulas: builds formula matrices
- MixedModel → Random and residual: uses effects
- Random and residual → Patsy formulas: builds formula matrices
- MixedModel → Variance structure: builds decomposition
- Random and residual → Variance structure: supplies covariance blocks
- Variance structure → Likelihood solves: provides structure
- MixedModel → OptiMix: runs fitting
- OptiMix → MixedModel: evaluates loss
- MixedModel → Likelihood solves: evaluates likelihood
- Likelihood solves → PyTorch: uses tensor operations
- OptiMix → PyTorch: uses optimizers
- MixedModel → Fit statistics: computes estimates
- MixedModel → Random and residual: dispatches effect results
- Analyst → Pedigree preparation: prepares pedigree
- Pedigree preparation → Relationship matrices: computes matrices
- Analyst → Relationship matrices: requests genomic matrix
- Relationship matrices → Random and residual: supplies covariance
- Analyst → Larix dataset: loads example data
- Random and residual → Effect prediction: predicts new levels
- Fit statistics → Analyst: returns results
- Effect prediction → Analyst: returns predictions