Create Publication and Reproducibility Materials
mlm_publication_bundle.RdCreates publication-oriented reproducibility materials for a fitted mlmr model.
Usage
mlm_reproducibility_check(result, REML = NULL, optimizer = NULL,
maxfun = NULL)
mlm_methods_text(result, REML = NULL, optimizer = NULL, maxfun = NULL)
mlm_publication_bundle(result, REML = NULL, optimizer = NULL,
maxfun = NULL)Arguments
- result
A fitted result returned by
mlm_fit.- REML, optimizer, maxfun
Estimation settings to report. These are normally left as
NULL: the estimator is read from the fitted model and the optimizer settings from the values recorded bymlm_fit, so the reported settings cannot contradict the model. The arguments are used only for results that do not carry recorded settings.
Details
mlm_reproducibility_check() returns a checklist covering the formula,
data footprint, estimator settings, centering decisions, random-effects
structure, convergence, singularity, reporting outputs, and software versions.
The reproducible R code in the bundle is a complete script: given the original
data frame as dat, it selects the analysis sample, recreates the
centered predictors, and refits the same model.
mlm_methods_text() returns copy-ready prose that should be reviewed and
adapted before publication. mlm_publication_bundle() combines the
methods text, reproducibility checklist, software statement, formula, APA
tables, equations, and reproducible R code into a named list.
Value
mlm_reproducibility_check() returns a data frame.
mlm_methods_text() returns a character string.
mlm_publication_bundle() returns a named list of publication materials.
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_reproducibility_check(result)
#> Status Item
#> 1 OK Model formula captured
#> 2 OK Data footprint captured
#> 3 OK Estimator settings captured
#> 4 OK Centering decisions captured
#> 5 OK Random-effects structure captured
#> 6 OK Singular-fit check
#> 7 OK Convergence messages
#> 8 Review Inference labels reviewed
#> 9 OK ICC reporting reviewed
#> 10 OK Tables and equations generated
#> 11 OK Software versions captured
#> Evidence
#> 1 mathscore ~ ses_CWC + (1 | schoolid)
#> 2 22 rows in fitted data; 22 complete rows on selected model variables.
#> 3 Distribution: gaussian; link: identity; REML: TRUE; optimizer: bobyqa; maxfun: 20000.
#> 4 ses = CWC
#> 5 Groups: schoolid; random slopes: none.
#> 6 FALSE
#> 7 None reported
#> 8 For Gaussian mixed models fit with lme4, p values use large-sample normal approximations; use them as screening evidence unless a denominator-df method is added.
#> 9 ICCs represent the proportion of model-implied variance attributable to each grouping level for this Gaussian mixed model.
#> 10 APA tables, variance components, equations, LaTeX, and Quarto/R exports are available. ICCs are produced for Gaussian mixed models only.
#> 11 R 4.6.2; mlmr 0.1.0; lme4 2.1.0; shiny 1.14.0; bslib 0.12.0; ggplot2 4.0.3
#> Suggested Review
#> 1 Confirm the formula matches the research question before publication.
#> 2 Archive the raw data source and any cleaning script outside the app export.
#> 3 Use ML rather than REML for nested fixed-effect comparisons.
#> 4 Confirm centering choices match within-, between-, or contextual-effect claims.
#> 5 Report simplification decisions if convergence or singularity occurs.
#> 6 If TRUE, consider a simpler random-effects structure or explain why the boundary estimate is acceptable.
#> 7 Resolve convergence warnings before treating the model as final.
#> 8 Use denominator-df, bootstrap, profile-likelihood, or journal-preferred methods when confirmatory inference requires them.
#> 9 For GLMMs, report a family-specific ICC only after selecting and documenting an appropriate scale.
#> 10 Check labels, reference categories, notation, and journal formatting manually.
#> 11 Include the software table or APA software statement in supplementary materials.
mlm_methods_text(result)
#> [1] "We estimated a Gaussian linear mixed-effects model for mathscore using restricted maximum likelihood in lme4. The fitted formula was mathscore ~ ses_CWC + (1 | schoolid).\n\nThe model included fixed effects for ses and random-effect blocks for schoolid. Random slopes were estimated for no predictors.\n\nCentering choices were recorded as follows: ses was CWC centered.\n\nFor Gaussian mixed models fit with lme4, p values use large-sample normal approximations; use them as screening evidence unless a denominator-df method is added.\n\nICCs represent the proportion of model-implied variance attributable to each grouping level for this Gaussian mixed model.\n\nThe analysis used optimizer bobyqa with a maximum of 20000 function evaluations. Reproducible R code, model diagnostics, APA-style tables, equations, LaTeX output, and software version information were exported from mlmr.\n\nAnalyses were conducted in R version 4.6.2. Model estimation, reporting, and reproducible exports used mlmr version 0.1.0, lme4 version 2.1.0, shiny version 1.14.0, bslib version 0.12.0, ggplot2 version 4.0.3. Package versions are reported to support computational reproducibility."
names(mlm_publication_bundle(result))
#> [1] "methods_text" "reproducibility_check" "software_statement"
#> [4] "formula" "apa_tables" "equations"
#> [7] "reproducible_code"