Create Tables and Equations for a Fitted mlmr Model
mlm_reporting.RdCreates manuscript-oriented outputs from a fitted mlmr model. These helpers return APA-style tables, level-by-level equations, combined equations, and LaTeX equation displays.
Usage
mlm_apa_tables(result, format = c("list", "html", "latex"),
exponentiate = FALSE)
mlm_equations(result)
mlm_latex_equations(result)Arguments
- result
A fitted result returned by
mlm_fit.- format
Output format for APA tables:
"list","html", or"latex". The list format returns individual data frames; HTML and LaTeX formats return complete manuscript-oriented table documents.- exponentiate
Logical; if
TRUE, the fixed-effects table for a generalized model with a logit or log link gains exponentiated coefficients and their intervals: odds ratios (OR) for logit models, incidence rate ratios (IRR) for Poisson and negative-binomial models, andexp(b)for other log-link models. Ignored for Gaussian models and other links.
Value
mlm_apa_tables() returns a named list of tables, an HTML document, or a
LaTeX document. mlm_equations() returns plain-text equation descriptions.
mlm_latex_equations() returns a list with the level labels
(level), one LaTeX string per level (equations), the combined
equation (combined), one Tau matrix display per grouping factor
(tau), a coefficient key linking each equation symbol to a fixed-effect
estimate (key), the notation used (notation), and a short
explanatory note (note).
Details
The fixed-effects table includes estimates, standard errors, large-sample test statistics, p values, and Wald 95 percent confidence intervals. For Gaussian mixed models fit with lme4, p values are large-sample normal approximations rather than denominator-degrees-of-freedom tests. For generalized mixed models, p values and intervals are Wald approximations on the link scale. Treat these values as screening evidence unless a confirmatory inferential method is selected and documented.
Classical ICC tables are returned for Gaussian mixed models. For generalized mixed models, mlmr suppresses classical ICC output and asks users to choose a model-family-specific latent- or observation-scale ICC method before reporting ICC values.
mlm_latex_equations() writes two- and three-level nested models in
hierarchical (level-by-level) notation. Predictors are assigned to levels from
the fitted data: a predictor that is constant within every unit of a grouping
factor is treated as measured at that level. Level-1 predictors appear in the
Level-1 equation, higher-level predictors appear in the intercept equation, and
cross-level interactions appear in the equation for the lower-level slope they
moderate, so \(\gamma_{11}\) is the effect of the first Level-2 predictor on
the first Level-1 slope. Equations are built from the fitted coefficients, so
each dummy code of a categorical predictor has its own coefficient and the
indices of the random effects in the Tau matrices match the equations.
Three-level models use \(\pi\), \(\beta\), and \(\gamma\) coefficients.
Generalized models are written for the linear predictor \(\eta\) with the
link function shown and no Level-1 residual. Models with crossed grouping
factors, or more than three levels, are written as a single mixed-model
equation instead. These outputs are meant to support manuscript preparation
and teaching; users should review notation and substantive labels before
publication.
Examples
dat <- example_hsb(n_schools = 4, min_students = 5, max_students = 6)
spec <- mlm_spec(
outcome = "mathscore",
fixed = list(ses = list(center = "CWC")),
grouping = list(schoolid = "schoolid"),
random = list(schoolid = list(intercept = TRUE, slopes = character(),
correlation = TRUE)),
data = dat
)
result <- mlm_fit(spec)
mlm_apa_tables(result)
#> $fixed_effects
#> Predictor b SE Statistic p 95% CI
#> 1 (Intercept) 72.78 3.46 21.06 < .001 [66.01, 79.55]
#> 2 ses_CWC 3.22 3.77 0.85 0.393 [-4.17, 10.62]
#>
#> $dummy_coding
#> [1] variable reference contrasts
#> <0 rows> (or 0-length row.names)
#>
#> $variance_components
#> grp var1 var2 vcov sdcor
#> 1 schoolid (Intercept) <NA> 30.60700 5.532359
#> 2 Residual <NA> <NA> 93.78323 9.684174
#>
#> $icc
#> group variance icc
#> 1 schoolid 30.607 0.2461
#>
#> $software
#> Software Version Purpose
#> R R 4.6.2 Statistical computing environment
#> mlmr mlmr 0.1.0 Guided mixed-effects and multilevel modeling workflow
#> lme4 lme4 2.1.0 Mixed-effects model estimation
#> shiny shiny 1.14.0 Interactive web application framework
#> bslib bslib 0.12.0 User interface theming
#> ggplot2 ggplot2 4.0.3 Diagnostic and reporting graphics
#> Citation
#> R R Core Team
#> mlmr Harris
#> lme4 Bates et al.
#> shiny Chang et al.
#> bslib Sievert and Cheng
#> ggplot2 Wickham
#>
mlm_latex_equations(result)
#> $level
#> [1] "Level 1" "Level 2 (schoolid)"
#>
#> $equations
#> [1] "\\mathrm{mathscore}_{ij} = \\beta_{0j} + \\beta_{1j}\\mathrm{ses\\_CWC}_{ij} + r_{ij}"
#> [2] "\\beta_{0j} = \\gamma_{00} + u_{0j}\\\\ \\beta_{1j} = \\gamma_{10}"
#>
#> $combined
#> [1] "\\mathrm{mathscore}_{ij} = \\gamma_{00} + \\gamma_{10}\\mathrm{ses\\_CWC}_{ij} + u_{0j} + r_{ij}"
#>
#> $tau
#> [1] "\\begin{bmatrix}u_{0j}\\end{bmatrix}_{schoolid} \\sim MVN\\left(\\begin{bmatrix}0\\end{bmatrix},\\begin{bmatrix}\\tau_{00}\\end{bmatrix}\\right)\\quad \\text{schoolid: (Intercept)}"
#>
#> $key
#> Symbol Coefficient Estimate
#> 1 gamma_00 (Intercept) 72.780190
#> 2 gamma_10 ses_CWC 3.223606
#>
#> $notation
#> [1] "two-level hierarchical"
#>
#> $note
#> [1] "Predictors are assigned to levels from the fitted data: a predictor that is constant within every unit of a grouping factor is treated as measured at that level. Cross-level interactions appear in the equation for the lower-level coefficient they moderate."
#>