*! version 1.0.0

Title

merlin -- Mixed effects regression for linear, non-linear and user-defined models

See merlin - a unified framework for data analysis and methods development in Stata,
for an introduction.

Syntax

merlin models [if] [in]
[, options]

where
models are the model specifications; see merlin models.

options

model_description_options fully
define, along with models, the model to be fit

estimation_options method
used to obtain estimation results, including specifying initial values

reporting_options reporting
of estimation results

Also see merlin postestimation for features
available after estimation.

Description

merlin fits an extremely broad class of mixed effects regression models for linear,
non-linear and user-defined outcomes (Crowther, 2020).

merlin can fit multivariate outcome models of any type, each of which could be repeatedly measured
(longitudinal), with any number of levels, and with any number of random effects at each level.
Standard distributions/models available include the Bernoulli, beta, gamma, Gaussian, linear quantile,
negative binomial, ordinal, Poisson, and time-to-event/survival models include the exponential, Gompertz,
log-logistic, log normal, piecewise-exponential, generalised gamma, Weibull, Royston-Parmar, general log
hazard and general log cumulative hazard models. Interval censoring and left truncation are supported for
all survival models. merlin provides a flexible predictor syntax, allowing the user to define variables,
random effects, spline and fractional polynomial functions, functions of other outcome models, and any
interaction between each of them. Non-linear and time-dependent effects are seamlessly incorporated into the
predictor. merlin allows level-specific random effect distributions, either multivariate normal or t,
which are integrated out using either Gaussian quadrature or Monte-Carlo integration.

Family members

There are a number of associated commands, which utilise or build on the power of merlin, including:

stmerlin for standard survival analysis. This is a wrapper function to fit a range of parametric survival
models and the Cox model, but with the standard syntax of any [ST] st regression model command.
stmerlin is currently included as part of the merlin package.

stmixed for multilevel mixed effects survival analysis. This is a wrapper function to fit a
range of parametric survival models with random effects, but with a much more accessible (simpler!)
syntax than merlin, and is consistent with mestreg. stmixed is currently available as a separate
package on SSC.

predictms for predictions from a general multi-state model. Given a defined transition matrix, each
transition model can be fitted as a merlin model, and then the model objects can be passed to
predictms to calculate a huge range of useful predictions. predictms is currently part of the
multistate package, available on SSC.

survsim allows you to simulate survival times from a fitted merlin survival model. survsim
is currently available from the SSC archive.

exptorcs turns an expected incidence or mortality rate, recorded in age- and calendar-time specific event
counts and exposure time, into a restricted cubic spline-based survival model, i.e. a smooth parametric model for
the rate, dependent on multiple timescales (Weibull et al. (2021)). exptorcs is currently bundled with the
merlin package.

There are many more on the way.

Tutorials

For full details and many tutorials, take a look at
merlin's homepage.

Options

model_description_options
describe the model to be fit. The model to be fit is fully specified by
models -- which appear immediately after merlin -- and the option
covariance(). See merlin model description options and
merlin model notation.

estimation_options
control how the estimation results are obtained. These options control how
the standard errors (VCE) are obtained and control technical issues
such as choice of estimation method. See
merlin estimation options.

reporting_options
control how the results of estimation are displayed. See
merlin reporting options.

Examples

These examples are intended for quick reference. For detailed examples, see the
merlin homepage.

Example 1: Linear regression

Setup

. sysuse auto

Use regress command

. regress mpg weight foreign

Replicate model with merlin

. merlin (mpg weight foreign, family(gaussian))

Example 2: Logistic regression

Setup

. webuse gsem_lbw

Use logit command

. logit low age lwt smoke ptl ht ui

Replicate model with merlin

. merlin (low age lwt smoke ptl ht ui, family(bernoulli))

Example 3: Linear model with random intercept and slope

Setup

. use http://fmwww.bc.edu/repec/bocode/s/stjm_pbc_example_data, clear

Use mixed command

. mixed logb time age trt || id: time

Replicate model with merlin

. merlin (logb time age trt time#M1[id]@1 M2[id]@1, family(gaussian))

Author

Michael J. Crowther

Red Door Analytics

Stockholm, Sweden

michael@reddooranalytics.se

References

Crowther MJ. Extended multivariate generalised linear and non-linear mixed effects models.
https://arxiv.org/abs/1710.02223

Crowther MJ. merlin - a unified framework for data analysis and methods development in Stata. Stata Journal 2020;20(4):763-784.

Crowther MJ. Multilevel mixed effects parametric survival analysis: Estimation, simulation and application. Stata Journal 2019;19(4):931-949.

Crowther MJ, Lambert PC. Parametric multi-state survival models: flexible modelling allowing transition-specific distributions with
application to estimating clinically useful measures of effect differences. Statistics in Medicine 2017;36(29):4719-4742.

Weibull CE, Lambert PC, Eloranta S, Andersson TM-L, Dickman PW, Crowther MJ. A multi-state model incorporating
estimation of excess hazards and multiple time scales. Statistics in Medicine 2021;40(9):2139-2154.