Package 'LMMELSM'

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-10-27 06:05:47 UTC
Source: https://github.com/stephensrmmartin/lmmelsm

Help Index

The 'LMMELSM' package.

Description

Fits latent (or observed) multivariate (or univariate) mixed effects location scale models.

References

Stan Development Team (2020). RStan: the R interface to Stan. R package version 2.19.3. https://mc-stan.org

Extract group-specific coefficients.

Description

Coef method for lmmelsm objects.

Usage

## S3 method for class 'lmmelsm'
coef(object, prob = 0.95, summarize = TRUE, ...)

Arguments

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.

Details

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.

Value

List of summaries (if summarize is TRUE), or list of MCMC samples.

Author(s)

Stephen R Martin

Extracted model fitted variates.

Description

Extract model fitted variates.

Usage

## S3 method for class 'lmmelsm'
fitted(object, prob = 0.95, summarize = TRUE, ...)

Arguments

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.

Details

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.

Value

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.

Author(s)

Stephen Martin

Specify and fit the (latent) (multivariate) melsm.

Description

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).

Usage

lmmelsm(formula, group, data, ...)

Arguments

formula

Formula or list of formulas. See section on model specification.
group

Raw grouping variable name (not character).
data

Data frame.
...

Options passed onto sampling

Value

lmmelsm object.

Model specification

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.

Author(s)

Stephen R. Martin

Examples

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.

Description

loo method for LMMELSM objects.

Usage

## S3 method for class 'lmmelsm'
loo(x, type = c("observation", "group"), ...)

Arguments

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.

Value

loo object.

Author(s)

Stephen R. Martin

Predict method for lmmelsm objects.

Description

Generates posterior predictions from fitted LMMELSM object.

Usage

## S3 method for class 'lmmelsm'
predict(
  object,
  newdata = NULL,
  prob = 0.95,
  summarize = TRUE,
  include_error = TRUE,
  ...
)

Arguments

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.

Details

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:

ui=ziUDiu_i = z_i U D_i

, where DiD_i is the predicted between-group random effect SD, U is the upper cholesky factorization of the random effect correlations, and ziz_i is the standardized, orthogonalized random effect for group i.

Value

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.

Author(s)

Stephen Martin

Print method for lmmelsm objects.

Description

Print method for lmmelsm objects.

Usage

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

Arguments

x

lmmelsm object.
...

Not used.

Value

x (Invisibly).

Author(s)

Stephen R. Martin

Print method for summary.lmmelsm objects.

Description

Print method for summary.lmmelsm objects.

Usage

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

Arguments

x

summary.lmmelsm object.
...

Not used.

Value

x (Invisibly).

Author(s)

Stephen R. Martin

Extract random effects.

Description

Ranef method for lmmelsm objects.

Usage

## S3 method for class 'lmmelsm'
ranef(object, prob = 0.95, summarize = TRUE, ...)

Arguments

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.

Details

Extracts the random effects from the lmmelsm object. Note that this is different from the random coefficients. E.g., if β0i=β0+u0i\beta_{0i} = \beta_0 + u_{0i}, then coef extracts β0i\beta_{0i} and ranef extracts u0iu_{0i}.

Value

List of ranef summaries (random_mu_intercept, random_logsd_intercept, random_mu_coef, and random_logsd_coef), or samples (if summarize = FALSE).

Author(s)

Stephen R. Martin

Simulated data for fitting the LMMELSM

Description

Dataset containing 50 observations of 12 items for 100 persons. The data are generated from an LMMELSM.

Usage

sim_data

Format

Data frame with 5000 rows and 16 variables.

subject

The subject ID

baseline

A subject-level covariate

x1

A time-varying covariate

x2

A time-varying covariate

A_1 - A_6

Six indicators for "Agreeableness"

N_1 - N_6

Six indicators for "Neuroticism"

Summary method for lmmelsm objects.

Description

Summary method for lmmelsm objects.

Usage

## S3 method for class 'lmmelsm'
summary(object, prob = 0.95, ...)

Arguments

object

lmmelsm object.
prob

Numeric (Default: .95). Amount of probability mass contained in the credible interval.
...

Not used.

Value

summary.lmmelsm object. A list containing meta (metadata) and summary (summary tables).

Author(s)

Stephen R. Martin