Title:	Fit Latent Multivariate Mixed Effects Location Scale Models
Version:	0.2.1
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>.
License:	MIT + file LICENSE
Encoding:	UTF-8
LazyData:	true
RoxygenNote:	7.3.2
Biarch:	true
BugReports:	https://github.com/stephenSRMMartin/LMMELSM/issues
Depends:	R (≥ 3.4.0)
Imports:	Formula (≥ 1.2), loo (≥ 2.3.0), MASS (≥ 7.0), methods, nlme (≥ 3.0), parallel (≥ 3.6.0), Rcpp (≥ 0.12.0), RcppParallel (≥ 5.0.1), rstan (≥ 2.26.0), rstantools (≥ 2.2.0)
LinkingTo:	BH (≥ 1.66.0), Rcpp (≥ 0.12.0), RcppEigen (≥ 0.3.3.3.0), RcppParallel (≥ 5.0.1), rstan (≥ 2.26.0), StanHeaders (≥ 2.26.0)
SystemRequirements:	GNU make
Suggests:	testthat
NeedsCompilation:	yes
Packaged:	2025-05-04 19:22:34 UTC; hwkiller
Author:	Stephen Martin [aut, cre], Philippe Rast [aut]
Maintainer:	Stephen Martin <stephenSRMMartin@gmail.com>
Repository:	CRAN
Date/Publication:	2025-05-04 19:50:02 UTC

The 'LMMELSM' package.

Description

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

Author(s)

Maintainer: Stephen Martin stephenSRMMartin@gmail.com (ORCID)

Authors:

• Philippe Rast rast.ph@gmail.com (ORCID)

References

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

See Also

Useful links:

• Report bugs at https://github.com/stephenSRMMartin/LMMELSM/issues

Operator for testing NULL and returning expr if NULL

Description

Operator for testing NULL and returning expr if NULL

Usage

object %IfNull% expr

Arguments

Value

object if object is non-NULL, expression output if object is NULL.

Author(s)

Stephen R. Martin

Adds group codings for predictive df.

Description

Adds group codings for predictive df.

Usage

.add_group_codings(gs, newdata)

Arguments

Value

data frame, with numerics where group matches, and NAs otherwise.

Author(s)

Stephen Martin

Combines multiple formulas' RHS into one.

Description

Combines multiple formulas' RHS into one.

Usage

.combine_RHS(flist)

Arguments

Value

RHS formula.

Author(s)

Stephen R. Martin

Detect whether the predictors are L2-only

Description

Detects whether the predictors are level-2 only. E.g., whether location and scale are covariates are the same across all n_k observations of each K. This is important for efficiency reasons. If the covariates are invariant across repeated observations of the given group k, for all K, then we can compute predicted values once, and broadcast the prediction, rather than compute the prediction for every single row. Specifically, it detects if all x == x[1], where x is a group's data, for each column in mf.

Usage

.detect_L2_only(mf, group)

Arguments

Value

Logical. TRUE if the covariates appear to be level-2 only.

Author(s)

Stephen R. Martin

Get indices for subsetting lower-tri summaries of square matrices.

Description

Helper for correlation-matrix summarize output.

Usage

.full_to_lower_tri(x, string = FALSE)

Arguments

Details

The .summarize function returns every redundant and constant element from a correlation matrix. This function returns the stan-strings (when string = TRUE, e.g., [2,1], [3,1]), or the row-index assuming column-major order.

Value

Charactor vector (if string is TRUE) or integer vector.

Author(s)

Stephen R. Martin

Get LHS variable as string.

Description

Get LHS variable as string.

Usage

.get_LHS(formula)

Arguments

Value

String.

Author(s)

Stephen R. Martin

Get RHS terms or variables.

Description

Get RHS terms or variables.

Usage

.get_RHS(formula, terms = TRUE)

Arguments

Value

Character vector.

Author(s)

Stephen R. Martin

Gets elapsed time.

Description

Gets elapsed time.

Usage

.get_elapsed_time(sOut)

Arguments

Value

Numeric.

Author(s)

Stephen R. Martin

Get names in formula.

Description

Get names in formula.

Usage

.get_formula_names(flist, formula = TRUE)

Arguments

Value

List of lists.

Author(s)

Stephen R. Martin

Get indicator spec for stan model.

Description

Get indicator spec for stan model.

Usage

.get_indicator_spec(mm.inds, flist)

Arguments

Value

List with J_f (vector; Number of Indicators for each factor) and F_ind (matrix; each row contains the columns in mm.inds for the row-th factor).

Author(s)

Stephen R. Martin

Zip two lists together with function.

Description

Zip two lists together with function.

Usage

.list_zip(..., f = cbind)

Arguments

Value

List.

Author(s)

Stephen Martin

Convert char vector to columns.

Description

Converts a character vector int columns.

Usage

.magicsep(charvec, labs, types = NULL, sep = "MAGICSEP")

Arguments

Details

A wrapper around strcapture. Given "a_MAGICSEP_b", returns a vector of "a_" and "_b". Useful for converting a multiple-parameter string into columns of parameters. User can give column names in labs, and types of each extracted component as a list in types. User can customize sep, but by default assumes MAGICSEP.

Value

data.frame

Author(s)

Stephen R. Martin

Print newline.

Description

Print newline.

Usage

.newline(n = 1)

Arguments

Value

NULL.

Author(s)

Stephen R. Martin

Convert stan par-string to numeric columns.

Description

Convert stan par-string to numeric columns.

Usage

.pars_to_indices(x, labs = NULL)

Arguments

Value

Numeric matrix.

Author(s)

Stephen R. Martin

Convert spec to stan data.

Description

Convert spec to stan data.

Usage

.parse_formula(formulaList, group, data)

Arguments

Value

List.

Author(s)

Stephen R. Martin

Compute indicator data.

Description

Compute indicator data.

Usage

.parse_formula.indicators(mlist, mf)

Arguments

Value

Named List.

Author(s)

Stephen R. Martin

Compute predictor data.

Description

Compute predictor data.

Usage

.parse_formula.predictor(plist, mf, group)

Arguments

Value

Named list.

Author(s)

Stephen R. Martin

Print separator.

Description

Print separator.

Usage

.sep(sep = "\n-----", n = 1)

Arguments

Value

NULL.

Author(s)

Stephen R. Martin

Simulate covariates without correlation.

Description

Simulate covariates without correlation.

Usage

.simulate.X(n, K, P, L2_pred_only)

Arguments

Value

Matrix.

Author(s)

Stephen R. Martin

Compute posterior summaries.

Description

Computes posterior summaries.

Usage

.summarize(lmmelsm, pars, prob = 0.95)

Arguments

Value

Matrix.

Author(s)

Stephen R. Martin

Rearrange summary output.

Description

Rearrange summary output.

Usage

.summary_rearrange(x, cols, arrange = FALSE)

Arguments

Value

Data.frame.

Author(s)

Stephen R. Martin

Takes stan summary, returns summary with indices-as-columns.

Description

Creates "tidy" summaries in lieu of the stan rownames.

Usage

.tidy_summary(x, labs = NULL, ...)

Arguments

Details

.summarize creates an rstan-like summary with rownames, mat[1:R, 1:C]. .tidy_summary(mat, c("rows", "cols")) would then create two new columns, "rows" and "cols" with the indices in them. If arguments are provided in ..., then these indicate the mappings between the indices and labeled values. E.g., .tidy_summary(mat, c("rows", "cols"), c("A", "B"), c("C", "D")) would create two new columns, "rows" and "cols", and replace rows = 1 with rows = A; cols=2 with cols = D, and so on. Useful for going from stan rownames, to labeled columns.

Value

Data frame.

Author(s)

Stephen R. Martin

Check for location-scale formulas

Description

Check for location-scale formulas

Usage

.which_location_scale(flist, reduce = TRUE)

Arguments

Value

Numeric vector (length 2); which formulas in flist correspond to location, scale.

Author(s)

Stephen R. Martin

Extract group-specific coefficients.

Description

Coef method for lmmelsm objects.

Usage

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

Arguments

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

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

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

Value

loo object.

Author(s)

Stephen R. Martin

Creates named list.

Description

Creates named list.

Usage

nlist(...)

Arguments

Value

Named List.

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

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:

u_i = z_i U D_i

, where D_i is the predicted between-group random effect SD, U is the upper cholesky factorization of the random effect correlations, and z_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

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

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

Details

Extracts the random effects from the lmmelsm object. Note that this is different from the random coefficients. E.g., if \beta_{0i} = \beta_0 + u_{0i}, then coef extracts \beta_{0i} and ranef extracts u_{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

Multiply a row by a list of matrices

Description

Multiply a row by a list of matrices

Usage

row_multiply_list_mats(r, mats)

Arguments

Value

List of row by matrix products.

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"

Simulate data from latent uni/multidimensional MELSM

Description

Simulate data from latent uni/multidimensional MELSM

Usage

simulate_lmmelsm(
  n,
  K,
  lambda,
  resid,
  nu,
  mu_beta = NULL,
  logsd_beta = NULL,
  P_random_ind = NULL,
  Q_random_ind = NULL,
  mu_logsd_betas_cor,
  mu_logsd_betas_sigma,
  epsilon_cor,
  zeta = NULL,
  X_loc = NULL,
  X_sca = NULL,
  X_bet = NULL,
  L2_pred_only = FALSE
)

Arguments

Value

List of params (list), data (list), and df (data.frame).

Author(s)

Stephen R. Martin

Summary method for lmmelsm objects.

Description

Summary method for lmmelsm objects.

Usage

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

Arguments

Value

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

Author(s)

Stephen R. Martin