*! version 2 09Feb2023

Title

runmixregmls -- Run the MIXREGMLS mixed-effects location scale software from within Stata

Syntax

runmixregmls depvar [varlist] [if] [in] [, options]

where varlist specifies variables in the mean function.

Model
noconstant suppress constant term in the mean function

between(varlist[, noconstant]) specify variables in the mean function with random coefficients

within(varlist[, noconstant]) specify variables in within-group variance function

Random effects/Residuals
meanxb(newvar) mean function linear prediction for the fixed portion only

meanfitted(newvar) mean function fitted values based on the fixed portion linear prediction plus contributions based on the predicted random location effects

bgvariancefitted(newvar) between-group variance function variance implied by the random effects

wgvariancexb(newvar) within-group variance function linear prediction for the fixed portion only

wgvarianceeta(newvar) within-group variance function linear prediction for the fixed portion plus predicted random scale effect

wgvariancefitted(newvar) within-group variance function exponentiated linear prediction for the fixed portion plus predicted random scale effect

reffects(stub*) standardized random-location and random-scale effects

reunstandard(stub*) unstandardized random-location and random-scale effects

residuals(newvar) standardized residual errors

runstandard(newvar) unstandardized residual errors

Integration
noadapt do not perform adaptive Gaussian quadrature

intpoints(#) set the number of integration (quadrature) points; default is intpoints(11)

Maximization
iterate(#) maximum number of iterations; default is iterate(200)

tolerance(#) tolerance; default is tolerance(0.0005)

standardize standardize all covariates

ridgein(#) initial value for ridge; default is ridgein(0)

Reporting
level(#) set confidence level; default is level(95)

display_options control column formats, row spacing, line width,
and display of omitted variables and base and empty cells

noheader suppress table header

notable suppress coefficient table

coeflegend display legend instead of statistics

A panel variable must be specified. Use xtset.

Description

runmixregmls runs the
MIXREGMLS
mixed-effects location scale software from within Stata.

The software can fit two-level random-intercept and random-coefficient mixed-effects location scale models for continuous responses.

The mixed-effects location scale model extends the conventional
mixed-effects model (xtreg, mle and mixed) in three ways.

(1) The (log of the) within-group variance is further modeled as functions of the covariates.

(2) A new random effect, referred to as the random-scale effect,
is then entered into the within-group variance function to account for any unexplained group differences in the residual variance.
The existing random-intercept and any random-coefficient effects are now referred to as random-intercept and random-coefficient location effects.

(3) The covariances between the location and the scale random effects are freely estimated.

The distributions of the random-location and random-scale effects are assumed to be Gaussian.

runmixregmls is the sister command to the original runmixregls command which runs the MIXREGLS mixed-effects location scale software (Hedeker and Nordgren 2013) from within Stata.
The difference between the two commands is that runmixregls can only fit two-level random-intercept versions of the mixed-effects location scale model for continuous responses,
but in contrast to runmixregmls can allow the log of the between-group variance to optionally be modelled as a function of the variables.
The two commands also differ in their parameterisation of the model.

Both runmixregls and runmixregmls can therefore fit two-level random-intercept models with a constant between-group variance and a log within-group variance further modeled as
functions of the covariates and a new scale random-scale effect, but both commands allow different extensions to this model and that will dictate which command is used.
Where only this simplest model is desired, the two commands implement different parameterisations of this model and so while the model fit statistics will be identical, the model estimates will differ correspondingly.

Options

Model

noconstant; see
[R] estimation options.

between(varlist[, noconstant])
specifies the variables with random coefficients.

within(varlist[, noconstant])
specifies the variables in the within-group variance function.

Postestimation prediction tools

meanxb(newvar) calculates the mean function linear prediction for the fixed portion only. This is equivalent to fixing the random location effects in the model to their theoretical (prior) mean value of 0.

meanfitted(newvar) calculates the mean function fitted values based on the fixed portion linear prediction plus contributions based on the predicted random location effects.

bgvariancefitted(newvar) calculates the between-group variance function variance implied by the random location effects.

wgvariancexb(newvar) calculates the within-group variance function linear prediction for the fixed portion only. This is equivalent to fixing the random scale effect in the function to its theoretical (prior) mean value of 0.

wgvarianceeta(newvar) calculates the within-group variance function linear prediction for the fixed portion plus the predicted random scale effect.

wgvariancefitted(newvar) calculates the within-group variance function exponentiated linear prediction for the fixed portion plus the predicted random scale effect.

reffects(stub*)
retrieves the best linear unbiased predictions (BLUPs) of the standardized random effects from MIXREGMLS.
BLUPs are also known as empirical Bayes estimates. The sampling variances, covariances and SEs are also returned.

reunstandard(stub*)
retrieve unstandardized random-location and random-scale effects.
The sampling variances, covariances and SEs are also returned.

runstandard(newvar) retrieves the residual errors from MIXREGMLS.

residuals(newvar) retrieves the standardized residual errors from MIXREGMLS.

Integration

noadapt prevents MIXREGMLS from using adaptive Gaussian quadrature.
MIXREGMLS will use ordinary Gaussian quadrature instead.

intpoints(#) sets the number of integration points for (adaptive) Gaussian quadrature.
The default is intpoints(11).
The more points, the more accurate the approximation to the log likelihood.
However, computation time increases with the number of quadrature points.
When models do not converge properly, increasing the number of quadrature points can sometimes lead to convergence.

Maximization

iterate(#) specifies the maximum number of iterations.
The default is iterate(200).
You should seldom have to use this option.

tolerance(#) specifies the convergence tolerance.
The default is tolerance(0.0005).
You should seldom have to use this option.

standardize standardizes all covariates in all functions during optimization.
This ensures all covariates are on the same numerical scale with mean 0 and variance 1.
This can be helpful if the model "blows up" or does not converge to the solution.

ridgein(#) specifies the initial value for the ridge parameter.
The default is ridgein(200).
This is a numeric value that adds to the diagonal of the second derivative matrix, which can aid in convergence of the solution; usually set to 0 or some small fractional value.

Reporting

level(#); see [R] estimation options.

display_options:
noomitted,
vsquish,
noemptycells,
baselevels,
allbaselevels,
cformat(%fmt),
pformat(%fmt),
sformat(%fmt), and
nolstretch;
see [R] estimation options.

noheader suppresses the display of the summary statistics at the top of
the output; only the coefficient table is displayed.

notable suppresses display of the coefficient table.

coeflegend; see
[R] estimation options.

Remarks

Remarks are presented under the following headings:

Remarks on the random-intercept mixed-effects location scale model
Remarks on the random-coefficient mixed-effects location scale model
Remarks on getting runmixregmls working for the first time
Remarks on MIXREGMLS estimation
Remarks on runmixregmls output

Remarks on the random-intercept mixed-effects location scale model

The random-intercept mixed-effects location scale model fitted by MIXREGMLS consists of two functions

(1) the mean function,

(2) the within-group variance function.

For simplicity, consider a model with a single covariate x_ij.

These two functions can then be written as

y_ij = b0 + b1*x_ij + u_j + e_ij, i=1,...,n_j; j=1,...,J,

log(sigma2_e_ij) = a0 + a1*x_ij + v_j,

where

u_j ~ N(0, sigma2_u),

v_j ~ N(0, sigma2_v),

e_ij ~ N(0, sigma2_e_ij),

sigma_uv = cov(u_j, v_j)

and

y_ij is the continuous response variable,

x_ij is the covariate,

b0, b1, a0, a1, are regression coefficients to be estimated,

u_j is the unobserved random-intercept location effect,

v_j is the unobserved random-scale effect,

e_ij are the observation-specific errors.

The u_j and v_j are modeled as correlated.

For computational reasons, MIXREGLS estimates a reparameterised version of the above model where a Cholesky decomposition is applied to the 2x2 random effects covariance matrix S leading to S = L*L’ where L is a lower triangular matrix.
The associated random effects are then standardized independent standard normal variates theta_u_j and theta_v_j.
While the random effects variances and covariance returned by MIXREGLS are on the metric of the original parameterisation, the predicted random effects are on the reparametrized metric and so are predicted standardized random effects.
The predicted unstandardized random effects are calculated by applying L to the predicted standardize random effects.

u_j = sigma_u * theta_u_j

v_j = (sigma_uv / sigma_v) * theta_u_j + sqrt(sigma_v^2 – sigma_vw^2 / sigma_u^2) * theta_v_j

Remarks on the random-coefficient mixed-effects location scale model

The random-coefficient mixed-effects location scale model fitted by MIXREGMLS consists of two functions

(1) the mean function,

(2) the within-group variance function.

For simplicity, consider a model with a single covariate x_ij.

These two functions can then be written as

y_ij = b0 + b1*x_ij + u0_j + u1_j*x_ij + e_ij, i=1,...,n_j; j=1,...,J,

log(sigma2_e_ij) = a0 + a1*x_ij + v_j,

where

u0_j ~ N(0, sigma2_u0),

u1_j ~ N(0, sigma2_u1),

v_j ~ N(0, sigma2_v),

e_ij ~ N(0,sigma2_e_ij),

sigma_u0u1 = cov(u0_j, u1_j)

sigma_u0v = cov(u0_j, v_j)

sigma_u1v = cov(u1_j, v_j)

and

y_ij is the continuous response variable,

x_ij is the covariate,

b0, b1, a0, a1 are regression coefficients to be estimated,

u0_j is the unobserved random-intercept location effect,

u1_j is the unobserved random-coefficient location effect,

v_j is the unobserved random-scale effect,

e_ij are the observation-specific errors.

The u0_j, u1_j and v_j are modeled as correlated

When the predicted random effects are requested, these will be predicted standardized random effects theta_u0_j, theta_u1_j and theta_v_j.
The predicted unstandardized random effects are calculated by applying L from the Cholesky decomposition of the 3*3 random effect covariance matrix to the predicted standardized random effects.

Remarks on getting runmixregmls working for the first time

runmixregmls can be installed from the Statistical Software Components (SSC) archive by typing the following
from a net-aware version of Stata

. ssc install runmixregls

If you have already installed runmixregls from the SSC, you can check that you are using the latest version
by typing the following command:

. adoupdate runmixregls

Remarks on MIXREGMLS estimation

MIXREGMLS uses maximum likelihood estimation, utilizing both the EM algorithm and a Newton-Raphson solution.
Because the log likelihood for this model has no closed form, it is approximated by adaptive Gaussian quadrature.
Estimation of the random effects is accomplished using empirical Bayes methods.
The full model is estimated in three sequential stages. For simplicity we focus here on the random-intercept version of the model:

(1) Standard mixed-effects model

(2) Stage 1 model + within-group variance function regression coefficients

(3) Stage 2 model + random-scale effect + covariances between location and scale random effects

Prior to Stage 1, 20 iterations are performed of the EM algorithm
to estimate the parameters of a standard random-intercept model
(regression coefficients, between-group variance, within-group variance, and random-location effects).
These estimates are then used as starting values for Stage 1
estimates at each stage are used as starting values for the next stage,
which improves the convergence of the final model.
This also provides a way of assessing the statistical significance of the additional parameters in each stage via likelihood-ratio tests.
The results of each stage as well as these likelihood-ratio tests are provided in the saved results.

See Hedeker and Nordgren 2013 for further details on the MIXREGMLS estimation which is the same as the MIXREGLS estimation.

Remarks on runmixregmls output

The runmixregmls output displays five different sets of parameters

Mean:
Mean function regression coefficients

Between:
Between-group variance-covariance parameters

Within:
Within-group variance function regression coefficients (log scale)

Association:
Covariances between the location and scale random effects

Scale:
Random-scale variance

Example:

Load the data

. use http://www.bristol.ac.uk/cmm/media/runmixregmls/tutorial, clear

Declare panel variable to be school

. xtset school

Fit the two-level random-intercept mixed-effects location scale model with no covariates

. runmixregmls normexam

Refit the model adding covariates to the mean model

. runmixregmls normexam standlrt girl

Refit the model adding covariates to the within-group variance function

. runmixregmls normexam standlrt girl, within(standlrt girl)

Refit the model and calculate the unstandardized random effects and residual errors

. runmixregmls normexam standlrt girl, within(standlrt girl) reunstandard(u) runstandard(e)

Refit the model adding a random coefficient

. runmixregmls normexam standlrt girl, between(standlrt)

Refit the model adding a random coefficient and covariates to the within-group variance function

. runmixregmls normexam standlrt girl, between(standlrt) within(standlrt girl)

Saved results

runmixregmls saves the following in e():

Scalars

e(N) number of observations

e(N_g) number of groups

e(g_min) smallest group size

e(g_avg) average group size

e(g_max) largest group size

e(k) number of parameters

e(k_1) number of parameters, stage 1 model

e(k_2) number of parameters, stage 2 model

e(k_3) number of parameters, stage 3 model

e(ll) log likelihood

e(ll_1) log likelihood, stage 1 model

e(ll_2) log likelihood, stage 2 model

e(ll_3) log likelihood, stage 3 model

e(deviance_1) deviance, stage 1 model

e(deviance_2) deviance, stage 2 model

e(deviance_3) deviance, stage 3 model

e(iterations) number of iterations

e(iterations_1) number of iterations, stage 1 model

e(iterations_2) number of iterations, stage 2 model

e(iterations_3) number of iterations, stage 3 model

e(time) estimation time (seconds)

e(chi2_1vs2) chi-squared, stage 1 model vs. stage 2 model

e(chi2_1vs3) chi-squared, stage 1 model vs. stage 3 model

e(chi2_2vs3) chi-squared, stage 2 model vs. stage 3 model

e(p_1vs2) p-value, stage 1 model vs. stage 2 model

e(p_1vs3) p-value, stage 1 model vs. stage 3 model

e(p_2vs3) p-value, stage 2 model vs. stage 3 model

Macros

e(cmd) runmixregmls

e(cmdline) command as typed

e(depvar) name of dependent variable

e(ivar) variable denoting groups

e(adapt) adaptive Gaussian quadrature

e(n_quad) number of integration points

e(iterate) maximum number of iterations

e(tolerance) tolerance

e(ridgein) initial ridge

e(standardize) standardized variables

e(properties) b V

Matrices

e(b) coefficient vector

e(V) variance-covariance matrix of the estimators

e(b_1) coefficient vector, stage 1 model

e(b_2) coefficient vector, stage 2 model

e(b_3) coefficient vector, stage 3 model

e(V_1) variance-covariance matrix of the estimators, stage 1 model

e(V_2) variance-covariance matrix of the estimators, stage 2 model

e(V_3) variance-covariance matrix of the estimators, stage 3 model

Functions

e(sample) marks estimation sample

Authors

George Leckie

Centre for Multilevel Modelling

University of Bristol

g.leckie@bristol.ac.uk

http://www.bristol.ac.uk/cmm/team/leckie.html

Chris Charlton

Centre for Multilevel Modelling

University of Bristol

Disclaimer

runmixregmls comes with no warranty.

References

Hedeker, D. R. and Nordgren. 2013.
MIXREGLS: A Program for Mixed-effects Location Scale Analysis.
Journal of Statistical Software, 52, 12, 1-38.
URL: http://www.jstatsoft.org/v52/i12.

Also see

Manual: [XT] xtreg [ME] mixed [ME] menl

Online: [XT] xtreg, [ME] mixed, [ME] menl, runmixregls, runmlwin, gllamm