Mixed Model — gamlj_mixed • GAMLj3

Mixed Linear Model. Estimates models using lmer and lmer functions and provides options to facilitate estimation of interactions, simple slopes, simple effects, post-hoc tests, contrast analysis, effect size indexes and visualization of the results.

gamlj_mixed(
  formula = NULL,
  data,
  dep = NULL,
  factors = NULL,
  covs = NULL,
  cluster = NULL,
  model_terms = NULL,
  re = NULL,
  reml = TRUE,
  res_struct = "id",
  re_lrt = FALSE,
  re_ci = FALSE,
  re_corr = "block",
  fixed_intercept = TRUE,
  nested_terms = NULL,
  nested_intercept = NULL,
  nested_re = NULL,
  omnibus = "LRT",
  estimates_ci = TRUE,
  ci_method = "wald",
  boot_r = 1000,
  ci_width = 95,
  contrasts = NULL,
  contrast_custom_values = NULL,
  contrast_custom_focus = NULL,
  show_contrastnames = TRUE,
  show_contrastcodes = FALSE,
  plot_x = NULL,
  plot_z = NULL,
  plot_by = NULL,
  plot_raw = FALSE,
  plot_yscale = FALSE,
  plot_xoriginal = FALSE,
  plot_black = FALSE,
  plot_around = "none",
  plot_re = FALSE,
  plot_re_method = "average",
  emmeans = NULL,
  posthoc = NULL,
  simple_x = NULL,
  simple_mods = NULL,
  simple_interactions = FALSE,
  covs_conditioning = "mean_sd",
  ccm_value = 1,
  ccp_value = 25,
  covs_scale_labels = "labels",
  adjust = list("bonf"),
  covs_scale = NULL,
  dep_scale = "none",
  scale_missing = "complete",
  norm_test = FALSE,
  df_method = "Satterthwaite",
  norm_plot = FALSE,
  qq_plot = FALSE,
  resid_plot = FALSE,
  cluster_boxplot = FALSE,
  cluster_respred = FALSE,
  rand_hist = FALSE
)

Arguments

formula: (optional) the formula of the linear mixed model as defined in lmer.
data: the data as a data frame.
dep: a string naming the dependent variable from data; the variable must be numeric. Not needed if formula is used.
factors: a vector of strings naming the fixed factors from data. Not needed if formula is used.
covs: a vector of strings naming the covariates from data. Not needed if formula is used.
cluster: a vector of strings naming the clustering variables from data. Not necessary if formula is defined.
model_terms: a list of character vectors describing fixed effects terms. Not needed if formula is used.
re: a list of lists specifying the models random effects.
reml: TRUE (default) or FALSE, should the Restricted ML be re_corrused rather than ML
res_struct: Residual variance-covariance matrix structure. It can be 'id' (default) for identity (no correlation), 'cs' for compound symmetry (constant correlation), 'ar1' for autoregressive of order 1. and 'un' for unstructured.
re_lrt: TRUE or FALSE (default), LRT for the random effects
re_ci: TRUE or FALSE (default), confidence intervals for the random effects
re_corr: 'all', 'none' (default), or 'block'. When random effects are passed as list of length 1, it decides whether the effects should be correlated, non correlated. If 're' is a list of lists of length > 1, the option is automatically set to 'block'. The option is ignored if the model is passed using formula.
fixed_intercept: TRUE (default) or FALSE, estimates fixed intercept. Overridden if formula is used and contains ~1 or ~0.
nested_terms: a list of character vectors describing effects terms for nestet. It can be passed as right-hand formula.
nested_intercept: TRUE (default) or FALSE, estimates fixed intercept. Not needed if nested_terms is used.
nested_re: a list of lists specifying the models random effects.
omnibus: TRUE (default) or FALSE, estimates fixed intercept. Not needed if formula is used.
estimates_ci: TRUE (default) or FALSE , parameters CI in table
ci_method: .
boot_r: a number bootstrap repetitions.
ci_width: a number between 50 and 99.9 (default: 95) specifying the confidence interval width for the plots.
contrasts: a named vector of the form c(var1="type", var2="type2") specifying the type of contrast to use, one of 'deviation', 'simple', 'dummy', 'difference', 'helmert', 'repeated', 'polynomial' 'custom'. If NULL, simple is used. Can also be passed as a list of list of the form list(list(var="var1",type="type1")). If any factor contrast is defined as 'custom', a named list of the form list(factorname=numeric vector), for instance list(factorname=c(1,1,-2)) should be passed to the option contrast_custom_values.
contrast_custom_values: a named list with the custom contrast weights, of the form list(factorname=numeric vector), for instance list(factorname=c(1,1,-2)). only one constrast per variable is allowed.
contrast_custom_focus: if any factor is coded with 'custom', when TRUE or NULL (default) the coefficients, simple effects and simple interactions are focused on the custom contrast. If FALSE , variables are coded accordingly to the passed contrast, but no special table or test is devoted to the contrast.
show_contrastnames: TRUE or FALSE (default), shows raw names of the contrasts variables in tables
show_contrastcodes: TRUE or FALSE (default), shows contrast coefficients tables
plot_x: a string naming the variable placed on the horizontal axis of the plot
plot_z: a string naming the variable represented as separate lines in the plot
plot_by: a list of string naming the variables defining the levels for multiple plots
plot_raw: TRUE or FALSE (default), plot raw data along the predicted values
plot_yscale: TRUE or FALSE (default), set the Y-axis range equal to the range of the observed values.
plot_xoriginal: TRUE or FALSE (default), use original scale for covariates.
plot_black: TRUE or FALSE (default), use different line type per levels.
plot_around: 'none' (default), 'ci', or 'se'. Use no error bars, use confidence intervals, or use standard errors on the plots, respectively.
plot_re: TRUE or FALSE (default), add predicted values based on random effect in plot
plot_re_method: Method to plot the random effects. average plots the random effect of the selected variable averaging across all other predictors in the model. full plots the predicted values based on the whole model.
emmeans: a rhs formula with the terms specifying the marginal means to estimate (of the form '~x+x:z')
posthoc: a rhs formula with the terms specifying the table to apply the comparisons (of the form '~x+x:z'). The formula is not expanded, so 'x*z' becomes 'x+z' and not 'x+z+x:z'. It can be passed also as a list of the form 'list("x","z",c("x","z")`'
simple_x: The variable for which the simple effects (slopes) are computed
simple_mods: the variable that provides the levels at which the simple effects are computed
simple_interactions: should simple Interactions be computed
covs_conditioning: 'mean_sd' (default), 'custom' , or 'percent'. Use to condition the covariates (if any)
ccm_value: Covariates conditioning mean offset value: how many st.deviations around the means used to condition simple effects and plots. Used if covs_conditioning='mean_sd'
ccp_value: Covariates conditioning percentile offset value: number of percentiles around the median used to condition simple effects and plots. Used if covs_conditioning='percent'
covs_scale_labels: how the levels of a continuous moderator should appear in tables and plots: labels, values and values_labels, ovalues, `ovalues_labels. The latter two refer to the variable orginal levels, before scaling.
adjust: one or more of 'none', 'bonf','tukey' 'holm','scheffe', 'tukey'; provide no, Bonferroni, Tukey and Holm Post Hoc corrections respectively.
covs_scale: a list of lists specifying the covariates scaling, one of 'centered to the mean', 'standardized', or 'none'. 'none' leaves the variable as it is
dep_scale: Re-scale the dependent variable.
scale_missing: .
norm_test: TRUE or FALSE (default), provide a test for normality of residuals
df_method: The method for computing the denominator degrees of freedom and F-statistics. "Satterthwaite" (default) uses Satterthwaite’s method; "Kenward-Roger" uses Kenward-Roger’s method, "lme4" returns the lme4-anova table, i.e., using the anova method for lmerMod objects as defined in the lme4-package
norm_plot: TRUE or FALSE (default), provide a histogram of residuals superimposed by a normal distribution
qq_plot: TRUE or FALSE (default), provide a Q-Q plot of residuals
resid_plot: TRUE or FALSE (default), provide a scatterplot of the residuals against predicted
cluster_boxplot: TRUE or FALSE (default), provide a boxplot of random effects by the first defined clustering variable
cluster_respred: TRUE or FALSE (default), residuals vs predicted by the first defined clustering variable
rand_hist: TRUE or FALSE (default), provide histogram of random Coefficients

Value

A results object containing:

`results$model`					a property
`results$info`					a table
`results$main$r2`					a table of R
`results$main$anova`					a table of ANOVA results
`results$main$coefficients`					a table
`results$main$contrastCodeTables`					an array of contrast coefficients tables
`results$main$random`					a table
`results$main$randomcov`					a table
`results$main$ranova`					a table
`results$posthoc`					an array of post-hoc tables
`results$simpleEffects$anova`					a table of ANOVA for simple effects
`results$simpleEffects$coefficients`					a table
`results$simpleInteractions`					an array of simple interactions tables
`results$emmeans`					an array of predicted means tables
`results$mainPlots`					an array of results plots
`results$plotnotes`					a html
`results$assumptions$normtest`					a table of normality tests
`results$assumptions$qqplot`					a q-q plot
`results$assumptions$normplot`					Residual histogram
`results$assumptions$residPlot`					Residual Predicted plot
`results$assumptions$clusterBoxplot`					Residuals boxplot by cluster
`results$assumptions$clusterResPred`					an array of random coefficients histograms
`results$assumptions$randHist`					an array of random coefficients histograms
`results$predicted`					an output
`results$residuals`					an output

Tables can be converted to data frames with asDF or as.data.frame. For example:

results$info$asDF

as.data.frame(results$info)

Examples

data(clustermanymodels)
GAMLj3::gamlj_mixed(formula = ycont ~ 1 + x+( 1|cluster ),
                     data = clustermanymodels
                     )
#> 
#>  MIXED MODEL
#> 
#>  Model Info                                                               
#>  ──────────────────────────────────────────────────────────────────────── 
#>    Info                                                                   
#>  ──────────────────────────────────────────────────────────────────────── 
#>    Model Type      Mixed Model      Linear Mixed model for continuous y   
#>    Model           lmer             ycont ~ 1 + x + ( 1 | cluster )       
#>    Distribution    Gaussian         Normal distribution of residuals      
#>    Direction       y                Dependend variable scores             
#>    Optimizer       bobyqa                                                 
#>    DF method       Satterthwaite                                          
#>    Sample size              1800                                          
#>    Converged       yes                                                    
#>    Y transform     none                                                   
#>    C.I. method     Wald                                                   
#>  ──────────────────────────────────────────────────────────────────────── 
#>    Note. All covariates are centered to the mean
#> 
#> 
#>  MODEL RESULTS
#> 
#>  Model Fit                                                      
#>  ────────────────────────────────────────────────────────────── 
#>    Type           R²           df    LRT X²        p            
#>  ────────────────────────────────────────────────────────────── 
#>    Conditional    0.0462640     2    54.8903441    < .0000001   
#>    Marginal       0.0181812     1    33.8457863    < .0000001   
#>  ────────────────────────────────────────────────────────────── 
#> 
#> 
#>  Fixed Effects Omnibus Tests                       
#>  ───────────────────────────────────────────────── 
#>         F           df    df (res)    p            
#>  ───────────────────────────────────────────────── 
#>    x    34.11344     1    1778.688    < .0000001   
#>  ───────────────────────────────────────────────── 
#> 
#> 
#>  Parameter Estimates (Fixed coefficients)                                                                                        
#>  ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── 
#>    Names          Effect         Estimate      SE            Lower         Upper         df            t            p            
#>  ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── 
#>    (Intercept)    (Intercept)    43.2121306    0.46765270    42.2949301    44.1293312      28.98377    92.402184    < .0000001   
#>    x              x               0.3306732    0.05661562     0.2196338     0.4417126    1778.68769     5.840671    < .0000001   
#>  ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── 
#> 
#> 
#>  Random Components                                                    
#>  ──────────────────────────────────────────────────────────────────── 
#>    Groups      Name           Variance      SD           ICC          
#>  ──────────────────────────────────────────────────────────────────── 
#>    cluster     (Intercept)      4.189568     2.046843    0.02860285   
#>    Residual                   142.284203    11.928294                 
#>  ──────────────────────────────────────────────────────────────────── 
#>    Note. Number of Obs: 1800 , Number of groups: cluster 30
#>