Formula Syntax Reference¶

Aurora-GLM supports R/mgcv-compatible formula syntax for GAM and GAMM models. The formula parser lives in aurora.models.gam.formula.

Basic syntax¶

Formulas follow the pattern response ~ terms:

y ~ s(x1) + s(x2) + x3

Left of ~: response variable name or column index
Right of ~: predictor terms separated by +
s(...): smooth term
bare names: parametric (linear) term

Smooth terms¶

Syntax	Meaning
`s(x)`	Smooth of x with default settings (B-spline, k=10)
`s(x, k=15)`	Smooth with 15 basis functions
`s(x, n_basis=12)`	Explicit n_basis parameter
`s(x, basis='cubic')`	Natural cubic spline basis
`s(x, k=10, m=3)`	B-spline with penalty order 3
`s(x, sp=0.1)`	Fixed smoothing parameter

from aurora.models.gam import fit_gam_formula

# Default B-spline
result = fit_gam_formula("y ~ s(x1)", data)

# More basis functions for complex patterns
result = fit_gam_formula("y ~ s(x1, k=20)", data)

# Natural cubic spline
result = fit_gam_formula("y ~ s(x1, basis='cubic')", data)

Parametric terms¶

Bare variable names are treated as linear (parametric) predictors:

y ~ s(x1) + x2 + x3

Here x2 and x3 enter linearly, while x1 has a smooth effect. The intercept is included automatically.

Random effects¶

lme4-style random effects use the (effects | group) syntax:

Syntax	Meaning
`(1 \| subject)`	Random intercept for each subject
`(x \| subject)`	Random slope of x (no intercept)
`(1 + x \| subject)`	Random intercept and slope
`(x + y \| subject)`	Two random slopes (no intercept)
`(1 \| clinic/subject)`	Nested: subjects within clinics
`(1 \| subject) + (1 \| clinic)`	Crossed: subjects and clinics

from aurora.models.gamm import fit_gamm

# Random intercept
result = fit_gamm("y ~ x + (1 | subject)", data)

# Random intercept + slope
result = fit_gamm("y ~ x + (1 + x | subject)", data)

# Nested random effects
result = fit_gamm("y ~ x + (1 | clinic/subject)", data)

# Crossed random effects
result = fit_gamm("y ~ x + (1 | subject) + (1 | clinic)", data)

Tensor products¶

Note

Tensor product smooths (te(x1, x2) in mgcv) are not currently supported by the formula parser. Formulas accept univariate smooths s(...), parametric terms, and random effects only.

Data input modes¶

The formula interface accepts two data formats:

Dict with named arrays:

data = {"y": y_array, "temp": temp_array, "pressure": pressure_array}
result = fit_gam_formula("y ~ s(temp) + s(pressure)", data)

2D array with column indices:

# Column 0 = response, columns 1-3 = predictors
M = np.column_stack([y, x1, x2, x3])
result = fit_gam_formula("0 ~ s(1) + s(2) + 3", M)

pandas DataFrame (recommended for GAMM):

import pandas as pd
df = pd.DataFrame({"y": y, "x1": x1, "subject": subject})
result = fit_gamm("y ~ x1 + (1 | subject)", df)

Combined example¶

A GAMM formula combining all features:

y ~ s(time, k=15) + s(age, basis='cubic') + treatment + bmi + (1 + time | subject)

This specifies:

s(time, k=15): smooth time effect with 15 basis functions
s(age, basis='cubic'): smooth age effect with natural cubic spline
treatment: parametric (linear) treatment effect
bmi: parametric BMI effect
(1 + time | subject): random intercept and slope per subject