Skip to contents

Create a Multilevel Model Specification

mlm_spec.Rd

Creates a structured model specification used by mlm_formula, mlm_fit, the Shiny app, and reporting helpers.

Usage

mlm_spec(outcome, distribution = "gaussian", link = "identity",
  fixed = list(), grouping = list(), nesting = NULL, structure = "nested",
  random = list(), interactions = list(), predictor_levels = list(),
  data = NULL)

# S3 method for class 'mlm_spec'
print(x, ...)

Arguments

outcome

Character string giving the name of the outcome variable in data.

distribution

Outcome distribution. The primary production workflow uses "gaussian". Advanced workflows may use "binomial", "poisson", "negative binomial", or "Gamma".

Link function for generalized mixed models. For Gaussian models the default "identity" link is used.

fixed

Named list of fixed predictors. Each entry may include a center value: "none", "GMC" for grand-mean centering, or "CWC" for cluster-mean centering. Only numeric predictors can be centered. Cluster-mean centering uses the first grouping factor unless the entry names another one with group, for example list(center = "CWC", group = "districtid").

grouping

Named list mapping conceptual grouping names to data columns. For example, list(schoolid = "schoolid") or list(schoolid = "schoolid", districtid = "districtid").

nesting

Optional text description of the nesting or design structure.

structure

Model structure label, such as "nested" or "crossed". This label is used for documentation and guidance; the fitted model is determined by the grouping and random-effect terms.

random

Named list describing random intercepts, slopes, and correlation structure for each grouping factor. Each entry may contain intercept = TRUE, slopes = c(...), and correlation = TRUE or FALSE.

interactions

List of character vectors describing interaction terms, for example list(c("ses", "sector")).

predictor_levels

Optional named list declaring conceptual predictor levels, such as list(level1 = c("ses"), level2 = c("meanses")). This is used for app display and reporting.

data

Data frame used to fit the model.

x

An "mlm_spec" object.

...

Ignored.

Value

An object of class "mlm_spec", represented as a structured list. It can be passed to mlm_formula or mlm_fit.

Details

mlm_spec() records the modeling choices made in the app or in code. It does not fit the model by itself. Centered variables are created during mlm_fit and are reflected in the generated lme4 formula.

Variable names that are not syntactic R names (for example names containing spaces) are quoted automatically in the generated formula.

mlm_spec() checks that the selected variables exist in data. Problems that only matter at fitting time, such as centering a categorical predictor, requesting a random slope for a variable that is not a fixed predictor, or specifying no random effects, are reported by mlm_fit with a message describing how to fix them.

Users are responsible for confirming that grouping IDs, predictor levels, centering decisions, interactions, and random effects match the research design.

Examples

dat <- example_hsb(n_schools = 4, min_students = 5, max_students = 6)
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")),
  predictor_levels = list(level1 = "ses", level2 = c("meanses", "sector")),
  data = dat
)
mlm_formula(spec)
#> mathscore ~ ses_CWC + meanses_GMC + sector + ses_CWC:sector + 
#>     (1 + ses_CWC | schoolid)