, Philippe Rast [aut]
| Title: | Fit Latent Multivariate Mixed Effects Location Scale Models |
|---|---|
| Description: | In addition to modeling the expectation (location) of an outcome, mixed effects location scale models (MELSMs) include submodels on the variance components (scales) directly. This allows models on the within-group variance with mixed effects, and between-group variances with fixed effects. The MELSM can be used to model volatility, intraindividual variance, uncertainty, measurement error variance, and more. Multivariate MELSMs (MMELSMs) extend the model to include multiple correlated outcomes, and therefore multiple locations and scales. The latent multivariate MELSM (LMMELSM) further includes multiple correlated latent variables as outcomes. This package implements two-level mixed effects location scale models on multiple observed or latent outcomes, and between-group variance modeling. Williams, Martin, Liu, and Rast (2020) <doi:10.1027/1015-5759/a000624>. Hedeker, Mermelstein, and Demirtas (2008) <doi:10.1111/j.1541-0420.2007.00924.x>. |
| Authors: | Stephen Martin [aut, cre]
, Philippe Rast [aut]
|
| Maintainer: | Stephen Martin <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.2.0 |
| Built: | 2024-06-30 07:24:16 UTC |
| Source: | CRAN |
Fits latent (or observed) multivariate (or univariate) mixed effects location scale models.
Stan Development Team (2020). RStan: the R interface to Stan. R package version 2.19.3. https://mc-stan.org
Coef method for lmmelsm objects.
## S3 method for class 'lmmelsm' coef(object, prob = 0.95, summarize = TRUE, ...)## S3 method for class 'lmmelsm' coef(object, prob = 0.95, summarize = TRUE, ...)
object |
lmmelsm object. |
prob |
Numeric (Default: .95). Amount of probability mass contained in the credible interval. |
summarize |
Logical (Default: TRUE). Whether to return posterior summaries (TRUE) or MCMC samples (FALSE). |
... |
Not used. |
Extracts all group-specific coefficients from lmmelsm object.
Note that this is different from ranef.
Whereas ranef extracts the zero-centered random effects, coef extracts the group-specific effects, defined as the sum of the fixed effect and random effect.
List of summaries (if summarize is TRUE), or list of MCMC samples.
Stephen R Martin
Extract model fitted variates.
## S3 method for class 'lmmelsm' fitted(object, prob = 0.95, summarize = TRUE, ...)## S3 method for class 'lmmelsm' fitted(object, prob = 0.95, summarize = TRUE, ...)
object |
lmmelsm object. |
prob |
Numeric (Default: .95). Amount of probability mass contained in the credible interval. |
summarize |
Logical (Default: TRUE). Whether to return posterior summaries (TRUE) or MCMC samples (FALSE). |
... |
Not used. |
Extracts model fitted variates. When a latent MMELSM, these are the latent score expectations and log standard deviations. When an observed MMELSM, these are the observed score expectations and log standard deviations.
List of eta and eta_logsd. If summarize is TRUE, then the list contains formatted summary tables. If FALSE, then the list contains MCMC samples for all variables.
Stephen Martin
Fits a mixed effects location scale model on one or more observed or latent variables. Currently supports multiple endogenous latent factors or observed outcomes, and exogenous observed variables. Data are assumed to be two-level data. I.e., multiple indicators, repeatedly measured within group. Currently assumes measurement invariance (i.e., the measurement model params are equivalent across groups) and a unit-variance identification for latent variables. Excludes rows with missing data (and warns the user).
lmmelsm(formula, group, data, ...)lmmelsm(formula, group, data, ...)
formula |
Formula or list of formulas. See section on model specification. |
group |
Raw grouping variable name (not character). |
data |
Data frame. |
... |
Options passed onto |
lmmelsm object.
The model is specified as a list of formulas. LMMELSM supports the specification of latent measurement models, location models, scale models, between-group scale models, and (if latent variables are undesired) observed outcome models. The covariates do not need to be the same across the location, scale, and between-group models. The specified covariates will be used to predict the location and scale of all latent factors via multivariate regression.
The latent factor model is specified as follows.
In the simplest case, only one formula is required, and a single-factor model is estimated.
The left-hand side (LHS) contains the user-specified latent variable name, and the right-hand side (RHS) contains the indicators.
Let "latent1" and "latent2" be user-chosen names of two latent variables with three indicators each.
Then the formula syntax would be:
list(latent1 ~ y1 + y2 + y3, latent2 ~ y4 + y5 + y6)
The location model is specified as either a one or two-part formula. The LHS must be "location" and the RHS contains the covariates. Random slopes are specified in the optional second part, separated by "|". Because LMMELSM fits MELSMs, random intercepts are always included. For example, if x1 and x2 are two location predictors, then:
location ~ x1 + x2
specifies a location model with a random intercept per factor, and no random slopes.
location ~ x1 + x2 | x1
specifies a location model with a random intercept per factor, a random x1 coefficient per factor, and no random x2 coefficient.
The within-group scale model is specified similarly. The LHS must be "scale" and the RHS contains the covariates. Random intercepts are always included, and random slopes are specified in the optional second part of the RHS. For example, if x2 and x3 are two scale predictors, then:
scale ~ x2 + x3
specifies a scale model with a random intercept per factor, and no random slopes.
scale ~ x2 + x3 | x3
specifies a scale model with a random intercept perfactor, a random x3 coefficient per factor, and no random x2 coefficient.
The between-group scale model is specified by a LHS of "between" and RHS containing covariates. There are no random coefficients permitted in the between-group scale model. The between-group scale model is responsible for modeling the random effect standard deviations. Note: The between-group model only models the SDs of the random location and scale intercepts.
between ~ x2
specifies a between-group scale model on the SDs of the location and scale intercepts for each factor.
If you want to fit a non-latent multivariate MELSM, use "observed" as the LHS:
For example, if y1, y2, and y3 are three observed outcome variables, then
observed ~ y1 + y2 + y3
would fit an M-MELSM. Location, scale, and between-group models can still be specified, but they will model the observed variables, rather than latent variables. You cannot currently have both observed and latent outcomes in the same model.
Note: Because location, scale, between, and observed represent special formulas, latent factors cannot be named location, scale, between, nor observed.
It is assumed that any formula with location, scale, or between on the left-hand side (LHS) is a predictive formula, not a latent variable specification.
Stephen R. Martin
data(sim_data) # Fit LMMELSM with two latent factors (A and B), # Location model with one random coefficient # Scale model with one random coefficient # Between-group scale model with one covariate fit <- lmmelsm(list(A ~ A_1 + A_2 + A_3 + A_4 + A_5 + A_6, B ~ N_1 + N_2 + N_3 + N_4 + N_5 + N_6, location ~ x1 + baseline | x1, scale ~ x2 + baseline | x2, between ~ baseline), subject, sim_data, cores = 2, iter = 500, chains = 2 ) # Summarize fit summary(fit) # Get random effects ranef(fit) # Get group-specific parameter values coef(fit) # Get approximate leave-one-out loo(fit)data(sim_data) # Fit LMMELSM with two latent factors (A and B), # Location model with one random coefficient # Scale model with one random coefficient # Between-group scale model with one covariate fit <- lmmelsm(list(A ~ A_1 + A_2 + A_3 + A_4 + A_5 + A_6, B ~ N_1 + N_2 + N_3 + N_4 + N_5 + N_6, location ~ x1 + baseline | x1, scale ~ x2 + baseline | x2, between ~ baseline), subject, sim_data, cores = 2, iter = 500, chains = 2 ) # Summarize fit summary(fit) # Get random effects ranef(fit) # Get group-specific parameter values coef(fit) # Get approximate leave-one-out loo(fit)
loo method for LMMELSM objects.
## S3 method for class 'lmmelsm' loo(x, type = c("observation", "group"), ...)## S3 method for class 'lmmelsm' loo(x, type = c("observation", "group"), ...)
x |
lmmelsm object. |
type |
String (Default: "observation"). If "observation", then loo is leave-row-out. If "group", then loo is leave-group-out. |
... |
Not used. |
loo object.
Stephen R. Martin
Generates posterior predictions from fitted LMMELSM object.
## S3 method for class 'lmmelsm' predict( object, newdata = NULL, prob = 0.95, summarize = TRUE, include_error = TRUE, ... )## S3 method for class 'lmmelsm' predict( object, newdata = NULL, prob = 0.95, summarize = TRUE, include_error = TRUE, ... )
object |
lmmelsm object. |
newdata |
Data.frame (Default: NULL). If NULL, uses original data.frame. |
prob |
Numeric (Default: .95). Amount of probability mass contained in the credible interval. |
summarize |
Logical (Default: TRUE). Whether to return posterior summaries (TRUE) or MCMC samples (FALSE). |
include_error |
Logical (Default: TRUE). If TRUE, then include stochastic realizations in outcome variables. |
... |
Not used. |
If the grouping variable is missing, or contains NAs, then new random effects are generated from the posterior random effect distribution. Where the grouping variables are not missing, the posterior standardized, orthogonalized random effects are obtained from the fitted model, and used as a basis for predicted random effects. Because the standardized, orthogonalized random effects are used, one can include different between-group variance values to predict new RE variances, and therefore a different random effect value. That is, the random effect, conditional on new between-group variance model covariates, is equal to:
, where is the predicted between-group random effect SD, U is the upper cholesky factorization of the random effect correlations, and is the standardized, orthogonalized random effect for group i.
List. If summarize is TRUE, then a list of outcome (eta, eta_logsd) and indicator (y) posterior predictive distribution summaries. If FALSE, an N-length list of lists of outcome and indicator MCMC samples.
Stephen Martin
Print method for lmmelsm objects.
## S3 method for class 'lmmelsm' print(x, ...)## S3 method for class 'lmmelsm' print(x, ...)
x |
lmmelsm object. |
... |
Not used. |
x (Invisibly).
Stephen R. Martin
Print method for summary.lmmelsm objects.
## S3 method for class 'summary.lmmelsm' print(x, ...)## S3 method for class 'summary.lmmelsm' print(x, ...)
x |
summary.lmmelsm object. |
... |
Not used. |
x (Invisibly).
Stephen R. Martin
Ranef method for lmmelsm objects.
## S3 method for class 'lmmelsm' ranef(object, prob = 0.95, summarize = TRUE, ...)## S3 method for class 'lmmelsm' ranef(object, prob = 0.95, summarize = TRUE, ...)
object |
lmmelsm object. |
prob |
Numeric (Default: .95). Amount of probability mass contained in the credible interval. |
summarize |
Logical (Default: TRUE). Whether to return posterior summaries (TRUE) or MCMC samples (FALSE). |
... |
Not used. |
Extracts the random effects from the lmmelsm object.
Note that this is different from the random coefficients.
E.g., if , then coef extracts and ranef extracts .
List of ranef summaries (random_mu_intercept, random_logsd_intercept, random_mu_coef, and random_logsd_coef), or samples (if summarize = FALSE).
Stephen R. Martin
Dataset containing 50 observations of 12 items for 100 persons. The data are generated from an LMMELSM.
sim_datasim_data
Data frame with 5000 rows and 16 variables.
The subject ID
A subject-level covariate
A time-varying covariate
A time-varying covariate
Six indicators for "Agreeableness"
Six indicators for "Neuroticism"
Summary method for lmmelsm objects.
## S3 method for class 'lmmelsm' summary(object, prob = 0.95, ...)## S3 method for class 'lmmelsm' summary(object, prob = 0.95, ...)
object |
lmmelsm object. |
prob |
Numeric (Default: .95). Amount of probability mass contained in the credible interval. |
... |
Not used. |
summary.lmmelsm object. A list containing meta (metadata) and summary (summary tables).
Stephen R. Martin