Equations and Reporting • mlmr

Why Equations Matter

Mixed-effects and multilevel models are often taught through notation before they are taught through software syntax. mlmr keeps those two views connected: the app shows the fitted model formula, level-by-level equations, the combined equation, random-effects structure, and reproducible R code.

This is especially useful when a model includes centering, dummy-coded predictors, interactions, random slopes, or multiple grouping factors.

Level-by-Level Equations

The Results > Equations tab displays the model in a level-by-level format. For a two-level model, the Level 1 equation represents the lower-level outcome model, while the Level 2 equations describe how intercepts and slopes are modeled across higher-level units.

The display is intentionally stacked so each coefficient is visible on its own line. This makes it easier to see which predictors are attached to which coefficient and which coefficients have random components.

mlmr assigns each predictor to a level from the fitted data. A predictor that is constant within every unit of a grouping factor is treated as measured at that level. As a result:

Level-1 predictors appear in the Level 1 equation with their own coefficient;
higher-level predictors appear in the equation for the intercept;
a cross-level interaction appears in the equation for the lower-level slope it moderates, so $\gamma_{11}$ is the effect of the first Level-2 predictor on the first Level-1 slope;
each dummy code of a categorical predictor has its own coefficient.

The same equations are available in code:

library(mlmr)

dat <- example_hsb(n_schools = 12, min_students = 10, max_students = 14)
spec <- mlm_spec(
  outcome = "mathscore",
  fixed = list(
    ses = list(center = "CWC"),
    meanses = list(center = "GMC"),
    sector = list(center = "none")
  ),
  grouping = list(schoolid = "schoolid"),
  random = list(schoolid = list(intercept = TRUE, slopes = "ses",
    correlation = TRUE)),
  interactions = list(c("ses", "sector")),
  data = dat
)
result <- suppressWarnings(mlm_fit(spec))
eq <- mlm_latex_equations(result)
eq$level
#> [1] "Level 1"            "Level 2 (schoolid)"
writeLines(strsplit(eq$equations[[2]], "\\\\ ", fixed = TRUE)[[1]])
#> \beta_{0j} = \gamma_{00} + \gamma_{01}\mathrm{meanses\_GMC}_{j} + \gamma_{02}\mathrm{sectorPublic}_{j} + u_{0j}
#> \beta_{1j} = \gamma_{10} + \gamma_{11}\mathrm{sectorPublic}_{j} + u_{1j}

The coefficient key links each symbol to a row of the fixed-effects table:

eq$key
#>     Symbol          Coefficient  Estimate
#> 1 gamma_00          (Intercept) 73.030331
#> 2 gamma_01          meanses_GMC 10.800555
#> 3 gamma_02         sectorPublic -5.041393
#> 4 gamma_10              ses_CWC  6.044229
#> 5 gamma_11 ses_CWC:sectorPublic  1.446145

Three-level nested models use $\pi$ , $\beta$ , and $\gamma$ coefficients for Levels 1, 2, and 3. Generalized models are written for the linear predictor $\eta$ , with the link function shown and no Level-1 residual. Models with crossed grouping factors do not have a level-by-level form, so they are written as a single mixed-model equation.

Combined Equation

The combined equation substitutes the higher-level equations into the lower-level equation. This provides a compact view of the full model and helps users see how fixed effects, interactions, random effects, and residual terms enter the same model.

The combined equation is also exported as raw LaTeX so it can be copied into a manuscript, dissertation, or Quarto document.

Tau Variance-Covariance Matrix

The Tau matrix describes the variance-covariance structure of the random effects. In mlmr, the Tau display distinguishes:

random intercept variances;
random slope variances;
estimated covariances among random effects;
covariances fixed at zero when random effects are specified as independent.

The accompanying label table maps each random effect, such as u_0j or u_1j, to the corresponding coefficient. The indices match the level-by-level equations: u_1j is the random component of the slope $\beta_{1j}$ .

APA-Style Tables

The Results > Tables tab includes APA-style displays for:

fixed effects;
dummy coding;
variance components;
intraclass correlations.

The fixed-effects table includes estimates, standard errors, test statistics, p values, and 95% confidence intervals. For logistic and count models the app adds exponentiated coefficients (odds ratios or incidence rate ratios) with their intervals; in code, use mlm_apa_tables(result, exponentiate = TRUE). The table output is designed for quick inspection in the app and for manuscript export.

Export Options

The Report & Code tab exports several reproducible artifacts:

a Quarto-ready report (.qmd);
a reproducible R script (.R);
raw LaTeX for equations and tables (.tex);
separate APA table exports for Word-compatible, HTML, and LaTeX workflows.

The intent is that every graphical decision in the app can be carried into a transparent reporting workflow.

Recommended Reporting Workflow

Fit the model in the app.
Review diagnostics and convergence warnings.
Inspect the fixed-effects and variance-component tables.
Review the level-by-level and combined equations.
Export the Quarto report and raw LaTeX.
Render the Quarto report to HTML, Word, or PDF.
Edit the interpretation for the specific research question and manuscript context.

Manuscript Support

The reporting tools are meant to support manuscript preparation, not merely app display. The fixed-effects table includes estimates, standard errors, test statistics, p values, and confidence intervals. The LaTeX export provides raw table and equation code that can be pasted into Overleaf or a Quarto document.

The equations section is especially useful for theses, dissertations, and methods courses because it keeps three representations together:

the fitted lme4 formula;
the level-by-level multilevel equations;
the combined equation with the random-effects variance-covariance structure.

This makes it easier to check whether the statistical model, the manuscript notation, and the reproducible R code all describe the same analysis.

Reporting R Packages

Reproducible manuscripts should also report the software environment used for the analysis. mlmr provides a small helper for this:

mlmr::mlm_software_table()
mlmr::mlm_software_apa()

The Shiny app includes the same information in the Results > Tables tab, the raw LaTeX export, and the Quarto report. This gives users a ready-to-edit software statement for APA-style manuscripts and supplemental materials.

Users who write manuscripts with papaja can also ask mlmr for ready-to-run package citation code:

cat(mlmr::mlm_papaja_code(), sep = "\n")

The generated code uses papaja::r_refs() to create a BibTeX file and papaja::cite_r() to create an APA-style R/package citation statement. papaja is optional; it is not required to install or launch mlmr.

Interpretation Caution

mlmr helps users produce readable output, but it does not replace statistical judgment. Users should still evaluate model assumptions, convergence warnings, singular fits, distributional choices, centering decisions, missing data, and whether the random-effects structure is supported by the design and sample size.