Title:	Measurement Invariance Assessment Using Random Effects Models and Shrinkage
Version:	0.1.1
Description:	Estimates random effect latent measurement models, wherein the loadings, residual variances, intercepts, latent means, and latent variances all vary across groups. The random effect variances of the measurement parameters are then modeled using a hierarchical inclusion model, wherein the inclusion of the variances (i.e., whether it is effectively zero or non-zero) is informed by similar parameters (of the same type, or of the same item). This additional hierarchical structure allows the evidence in favor of partial invariance to accumulate more quickly, and yields more certain decisions about measurement invariance. Martin, Williams, and Rast (2020) <doi:10.31234/osf.io/qbdjt>.
License:	MIT + file LICENSE
Encoding:	UTF-8
LazyData:	true
Biarch:	true
Depends:	R (≥ 4.0.0)
Imports:	methods, Rcpp (≥ 0.12.0), rstan (≥ 2.26.0), rstantools (≥ 2.0.0), Formula (≥ 1.2-1), stats (≥ 3.4.0), parallel (≥ 3.4.0), mvtnorm (≥ 1.0), dirichletprocess (≥ 0.4.0), truncnorm (≥ 1.0), pracma (≥ 2.2.9), cubature (≥ 2.0.0), logspline (≥ 2.1.0), nlme (≥ 3.1), HDInterval (≥ 0.2.2)
LinkingTo:	BH (≥ 1.66.0), Rcpp (≥ 0.12.0), RcppEigen (≥ 0.3.3.3.0), rstan (≥ 2.26.0), StanHeaders (≥ 2.26.0)
SystemRequirements:	GNU make
RoxygenNote:	7.3.2
BugReports:	https://github.com/stephenSRMMartin/MIRES/issues
Suggests:	testthat
Config/testthat/edition:	3
NeedsCompilation:	yes
Packaged:	2025-05-04 20:21:24 UTC; hwkiller
Author:	Stephen Martin [aut, cre], Philippe Rast [aut]
Maintainer:	Stephen Martin <stephenSRMMartin@gmail.com>
Repository:	CRAN
Date/Publication:	2025-05-04 20:50:02 UTC

The 'MIRES' package.

Description

Estimates random effect latent measurement models, wherein the loadings, residual variances, intercepts, latent means, and latent variances all vary across groups. The random effect variances of the measurement parameters are then modeled using a hierarchical inclusion model, wherein the inclusion of the variances (i.e., whether it is effectively zero or non-zero) is informed by similar parameters (of the same type, or of the same item). This additional hierarchical structure allows the evidence in favor of partial invariance to accumulate more quickly, and yields more certain decisions about measurement invariance.

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.21.1. https://mc-stan.org

Martin, S. R., Williams, D. R., & Rast, P. (2019, June 18). Measurement Invariance Assessment with Bayesian Hierarchical Inclusion Modeling. <doi:10.31234/osf.io/qbdjt>

See Also

Useful links:

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

Combine all unique RHS entries into one RHS formula.

Description

Combine all unique RHS entries into one RHS formula.

Usage

.combine_RHS(formList)

Arguments

Value

Formula. RHS only.

Author(s)

Stephen R. Martin

Get the one-length LHS of formula as string.

Description

Get the one-length LHS of formula as string.

Usage

.formula_lhs(formula)

Arguments

Value

String. LHS variable of formula. Formula must have only one name on LHS.

Author(s)

Stephen R. Martin

Get terms from formula list

Description

Get terms from formula list

Usage

.formula_names(formList, terms = TRUE)

Arguments

Value

List containing factor (factor names) and indicator (indicator names) as lists.

Author(s)

Stephen R. Martin

Get RHS of formula as character vector.

Description

Get RHS of formula as character vector.

Usage

.formula_rhs(formula, terms = TRUE)

Arguments

Value

Character vector.

Author(s)

Stephen R. Martin

Compute Highest Posterior Density intervals.

Description

Compute Highest Posterior Density intervals.

Usage

.hdi(samps, prob, add_zero = FALSE)

Arguments

Value

Matrix of HDIs.

Author(s)

Stephen Martin

Generates indicator spec list.

Description

Generates the "indicator spec" used by Stan

Usage

.indicator_spec(formList, mm)

Arguments

Details

The indicator spec consists of two parts. The first part is J_f, or the number of indicators under each factor. The second part is an [F, J] array, wherein each row defines the 1:J_f[f] columns of the indicator matrix belonging to the factor. Example: [1, 3, 5, 0, 0, 0]: J_f[1] = 3 [2, 4, 6, 0, 0, 0]: J_f[2] = 3 [1, 2, 3, 4, 0, 0]: J_f[3] = 4; J = 6; F = 3

Value

List containing J_f (Indicators per factor; numeric vector) and F_ind (FxJ Numeric Matrix, where F_ind[f,1:J_f] gives the column indices of the model matrix corresponding to factor f.)

Author(s)

Stephen R. Martin

Outer subtraction for given params across MCMC samples.

Description

Computes p_j - p_i not j, for each j.

Usage

.pairwise_diff_single(mcmc)

Arguments

Details

Assumes that mcmc contains params from ONE parameter across the indices whose differences are of interest (e.g, resid_random[1:K, 1]).

Value

MCMC Matrix of all differences. Posterior samples of all possible differences, minus duplicates.

Author(s)

Stephen R Martin

Parse formula (list).

Description

Parse formula (list).

Usage

.parse_formula(formula, group, data)

Arguments

Value

List containing meta-data and stan data.

Author(s)

Stephen R. Martin

Compute all differences of vector.

Description

Compute all differences of vector.

Usage

.sample_diff(x)

Arguments

Value

Numeric Vector of lower-triangular outer difference matrix.

Author(s)

Stephen R Martin

Generate labels for all differences of vector.

Description

Generate labels for all differences of vector.

Usage

.sample_diff_labels(mcmcNames)

Arguments

Value

Character Vector of lower-triangular outer difference matrix. I.e., labels for .sample_diff.

Author(s)

Stephen R Martin

Compute BF(Less than)

Description

Computes the BF12, where 1 is less than and 2 is greater than.

Usage

bflt(mcmc, less_than, prior_cumul_fun, ...)

Arguments

Details

The BF12 here is BF for a parameter being less than a threshold, t, vs the parameter being greater than t. This borrows from the encompassing approach, where u is the unconstrained prior: BF1u = p(D|H = 1) / p(D|H = u) BF2u = p(D|H = 2) / p(D|H = u) BF12 = BF1u / BF2u.

BF1u = int p(D|H = 1, theta_1)p(theta_1 | H = 1) / p(D|H = u, theta_u)p(theta_u | H=u)

Value

BF12 value.

Author(s)

Stephen Martin

Unidimensional data generation.

Description

Generates unidimensional data for testing the HMRE/MIRES approach.

Usage

datagen_uni(J, K, n, fixed, mipattern, etadist = NULL)

Arguments

Details

mipattern is a list specifying a pattern of MI. The first entry should be a string specifying one of: constant, random, none, items, params, or custom. The other entries depend on the specification desired, as described below.

constant

(2) Numeric: All RE SDs are set to this value.

random

(2) Numeric: All RE SDs are generated between 0 and this value.

none

All RE SDs set to zero (full invariance).

items

(2) Numeric: Value of RE SDs for (3) items. E.g., "items", .4, 4 would set all parameters for items 1 to 4 to have an RE SD of .4.

params

(2) Numeric: Value of RE SD for parameter type (3), where (3) is an integer (0: Loadings, 1: Residual SDs, 2: Intercepts). E.g., "params", .4, 2 would set all RE-SDs of intercepts to be .4.

custom

(2) Numeric: Specify all 3J RE-SDs manually in order of loadings, residual log SDs, and intercepts.

Note that this is not the generative model specified by MIRES, but a convenience function for meeting the bare assumptions while generating MI or non-MI data.

Value

List of meta(data), params, data, and a data frame.

Author(s)

Stephen Martin

Create dirichletprocess (exponential) based density function.

Description

Create dirichletprocess (exponential) based density function.

Usage

ddirichletprocess(mcmc, iter = 500, mode = c("posterior", "est"), ...)

Arguments

Value

Function returning a matrix (if posterior) or vector (if est).

Author(s)

Stephen R. Martin

Create Stan-based spike-mixture DP based density estimation function.

Description

Create Stan-based spike-mixture DP based density estimation function.

Usage

ddirichletprocess_spike(mcmc, mode = "est", K = 200, spike_scale = 1e-05, ...)

Arguments

Value

Function.

Author(s)

Stephen R Martin

Create Stan-based density function.

Description

Create Stan-based density function.

Usage

ddirichletprocess_stan(mcmc, mode = "est", K = 200, model = "dpHNormal", ...)

Arguments

Value

Function returning vector (if est) or matrix (if posterior)

Author(s)

Stephen Martin

Density for hmre prior on RE SDs.

Description

Density for hmre prior on RE SDs.

Usage

dhmre(x, mu = 0, sigma = 1)

Arguments

Value

Density.

Author(s)

Stephen R. Martin

Implied density for pairwise differences given HMRE prior.

Description

Computes the implied densities of random effect differences given HMRE prior.

Usage

dhmre_pairwise(x, mu = 0, sigma = 1)

Arguments

Details

The HMRE prior for the RE-SD is \int N^+(\sigma_p | exp(h_p))LN(h_p | 4\mu, \sqrt{4}\sigma)dh_p. The random effects are distributed as u_{k,p} \sim N(0, \sigma_p). The implied prior is therefore u_{k,p} - u_{\lnot k, p} \sim N(0, \sqrt{2}\sigma). Note that there is a singularity at 0, because the integrand at sigma = 0 is an infinite spike. We currently integrate (using a change of variables) starting at machine precision-zero. Consider this the approximation of the limit as we approach 0 positively. This is therefore divergent when assessed at a difference of zero, due to the RESD taking on a zero value (and an infinite function value). This is expected, as the limit of a Gaussian as sigma -> 0 is the Dirac delta function.

Value

Numeric vector.

Author(s)

Stephen R. Martin

Create logspline-based density function.

Description

Create logspline-based density function.

Usage

dlogspline(mcmc, lbound = 0, ...)

Arguments

Value

Density Function.

Author(s)

Stephen Martin

Stick-breaking function.

Description

Stick-breaking function.

Usage

genStickBreakPi(K, alpha)

Arguments

Value

Vector of DP weights.

Author(s)

Stephen Martin

Paper simulation function (For historical purposes)

Description

Paper simulation function (For historical purposes)

Usage

generateData(J, K, n, paramSDPattern)

Arguments

Value

List.

Author(s)

Stephen Martin

Fit mixed effects measurement model for invariance assessment.

Description

Fits mixed effects measurement models for measurement invariance assessment.

Usage

mires(
  formula,
  group,
  data,
  inclusion_model = c("dependent", "independent"),
  identification = c("sum_to_zero", "hierarchical"),
  save_scores = FALSE,
  prior_only = FALSE,
  prior = c(0, 0.25),
  ...
)

Arguments

Details

MIRES stands for Measurement Invariance assessment with Random Effects and Shrinkage. Unlike other measurement invariance approaches, the MIRES model assumes all measurement model parameters (loadings, residual SDs, and intercepts) can randomly vary across groups — It is a mixed effects model on all parameters. Unlike most mixed effects models, the random effect variances are themselves also hierarchically modeled from a half-normal distribution with location zero, and a scaling parameter. This scaling parameter allows for rapid shrinkage of variance toward zero (invariance), while allowing variance if deemed necessary (non-invariance).

The scaling parameter (an estimated quantity) controls whether the RE variance is effectively zero (invariant) or not (non-invariant). Therefore, the random effect variances are regularized. When inclusion_model is dependent (Default), the scaling parameters are hierarchically modeled. By doing so, the invariance or non-invariance of a parameter is informed by other parameters with shared characteristics. Currently, we assume that each parameter informs the invariance of other similar parameters (presence of variance in some loadings increases the probability of variance in other loadings), and of similar items (non-invariance of item j parameters informs other parameters for item j). This approach increases the information available about presence or absence of invariance, allowing for more certain decisions.

The "Hierarchical inclusion model" on the random effect variance manifests as a hierarchical prior. When a dependent inclusion model is specified, then the hierarchical prior on random effect SDs is:

p(\sigma_p | \exp(\tau)) = \mathcal{N}^+(\sigma_p | 0, \exp(\tau))

\tau = \tau_c + \tau_{param} + \tau_{item} + \tau_p

\tau_* \sim \mathcal{N}(\mu_h, \sigma_h)

Therefore, the regularization of each RE-SD is shared between all RE-SDs (tau_c), all RE-SDs of the same parameter type (tau_param), and all RE-SDs of the same item (tau_item).

When an independent inclusion model is specified (inclusion_model is "independent"), only the independent regularization term \tau_p is included. The prior is then scaled so that the marginal prior on each p(\sigma_p) remains the same. In this case, RE-SDs cannot share regularization intensities between one another.

The inclusion model hyper parameters (mu_h, sigma_h) can be specified, but we recommend the default as a relatively sane, but weakly informative prior.

Value

mires object.

Author(s)

Stephen R. Martin

References

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

Martin, S. R., Williams, D. R., & Rast, P. (2019, June 18). Measurement Invariance Assessment with Bayesian Hierarchical Inclusion Modeling. <doi:10.31234/osf.io/qbdjt>

Examples

data(sim_loadings) # Load simulated data set
head(sim_loadings) # 8 indicators, grouping variable is called "group"

# Fit MIRES to simulated data example.
# Assume factor name is, e.g., agreeableness.
fit <- mires(agreeableness ~ x_1 + x_2 + x_3 + x_4 + x_5 + x_6 + x_7 + x_8,
             group = group,
             data = sim_loadings, chains = 2, cores = 2)

# Summarize fit
summary(fit)

# Compare all groups' loadings:
pairwise(fit, param = "lambda")
# Compare groups "2" and "3" only:
pairwise(fit, param = "lambda", groups = c("2", "3"))

# Get random effects:
fit_ranefs <- ranef(fit)
# Look at random effects of loadings:
fit_ranefs$lambda

Pairwise comparisons of random parameters.

Description

Compute pairwise differences in group-specific measurement parameters.

Usage

pairwise(
  mires,
  param = c("lambda", "resid", "nu"),
  prob = 0.95,
  less_than = 0.1,
  groups = NULL,
  ...
)

Arguments

Details

For a specified set of parameters, this computes all pairwise differences in the random effects across the posterior. Specifically, this computes the posterior differences of groups' parameters, for all parameters. This is useful for comparing groups' estimates under non-invariance.

Value

Data frame.

Author(s)

Stephen Martin

Create marginal posterior density function approximations for random effect SDs

Description

For each RE-SD, approximates the marginal posterior density from MCMC samples for use in BF calculations.

Usage

posterior_density_funs_sigmas(mires, add_zero = TRUE, ...)

Arguments

Details

Starts by computing (lower-bounded) logspline approximations. If these fail, it uses the Dirichlet process with positive-normal kernels as an approximation.

Value

List of approximate density functions.

Author(s)

Stephen Martin

Prediction for DP density estimation models.

Description

Prediction for DP density estimation models.

Usage

predict_DP(x, fit, K, pi = "pi", dens, params, R_params, samps = FALSE)

Arguments

Value

Matrix of posterior mean, sd, .025, and .975 intervals.

Author(s)

Stephen R. Martin

Print function for mires objects.

Description

Print function for mires objects.

Usage

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

Arguments

Value

x (Invisibly)

Author(s)

Stephen R. Martin

Print method for MIRES summary objects.

Description

Print method for MIRES summary objects.

Usage

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

Arguments

Value

x (Invisibly)

Author(s)

Stephen Martin

Extract random effects of each group from MIRES model.

Description

Extract random effects of each group from MIRES model.

Usage

## S3 method for class 'mires'
ranef(object, prob = 0.95, ...)

Arguments

Value

List containing summaries of lambda, (log) residual SDs, nu, latent mean, and (log) latent SD random effects.

Author(s)

Stephen R Martin

Random sampling from hmre prior on RE SDs.

Description

Random sampling from hmre prior on RE SDs.

Usage

rhmre(n, mu = 0, sigma = 1)

Arguments

Value

Vector.

Author(s)

Stephen R. Martin

Simulated data: All parameters vary (Full non-invariance)

Description

Simulated data: All parameters vary (Full non-invariance)

Usage

sim_all

Format

A simulated dataset containing eight indicators for one factor, and one grouping variable.

Simulated data: Intercepts vary

Description

Simulated data: Intercepts vary

Usage

sim_intercepts

Format

A simulated dataset containing eight indicators for one factor, and one grouping variable.

Simulated data: Half the items are non-invariant.

Description

Simulated data: Half the items are non-invariant.

Usage

sim_items

Format

A simulated dataset containing eight indicators for one factor, and one grouping variable.

Simulated data: Loadings vary

Description

Simulated data: Loadings vary

Usage

sim_loadings

Format

A simulated dataset containing eight indicators for one factor, and one grouping variable.

Simulated data: No variance (Full invariance)

Description

Simulated data: No variance (Full invariance)

Usage

sim_none

Format

A simulated dataset containing eight indicators for one factor, and one grouping variable.

Simulated data: Residual variances vary

Description

Simulated data: Residual variances vary

Usage

sim_resid

Format

A simulated dataset containing eight indicators for one factor, and one grouping variable.

Generate Truncated Dirichlet Process Mixture.

Description

Generate Truncated Dirichlet Process Mixture.

Usage

simulate_DP(N, K, param, alpha, f)

Arguments

Value

List of data (y), weights (pi), params (param), and the true density function (d).

Author(s)

Stephen Martin

Split stan names into a list of parameter names (char vec) and (col-named) matrix of numeric indices.

Description

Split stan names into a list of parameter names (char vec) and (col-named) matrix of numeric indices.

Usage

split_stannames(stannames, labs = NULL)

Arguments

Value

List of param names and a matrix of indices.

Author(s)

Stephen R Martin

Summary method for mires object.

Description

Computes summaries for MIRES objects.

Usage

## S3 method for class 'mires'
summary(object, prob = 0.95, less_than = 0.1, ...)

Arguments

Details

Computes summary tables for fixed measurement parameters (loadings, residual SDs, and intercepts) and random effect standard deviations (resd). The printed output includes the posterior mean, median, SD, and .95 (Default) highest density intervals. HDIs were chosen instead of quantile intervals because the random effect SDs can be on the boundary of zero if invariance is plausible. Additionally, other columns exist to help aid decisions about invariance:

BF01

Bayes factor of invariance (Variance = 0) to non-invariance (Variance > 0)

BF10

Bayes factor of non-invariance (Variance > 0) to invariance (Variance = 0). The inverse of BF01 for convenience

Pr(SD <= less_than)

The posterior probability that the random effect SD is less than less_than (Default: .1). Set less_than to a value below which you would consider the variance to be effectively ignorable.

BF(SD <= less_than)

The Bayes Factor comparing effectively-invariant (SD < less_than) to non-invariant (SD > less_than). Set less_than to a value below which you would consider variance to be effectively ignorable. This uses the encompassing prior approach.

Value

summary.mires object. List of meta data and summary. Summary is list of summary tables for all fixed effects parameters.

Author(s)

Stephen R. Martin

Tidy up a vector of stan names into a data frame.

Description

Tidy up a vector of stan names into a data frame.

Usage

tidy_stanpars(stannames, labs = NULL, ...)

Arguments

Value

Data frame containing parameters and the (optionally named) indices.

Author(s)

Stephen R Martin