*! version 0.1.0 ?????2017

Title

merlin estimation options -- Options affecting estimation

Syntax

merlin models
... , ... estimation_options

estimation_options

from(matname) specify starting values

restartvalues(sv_list) specify starting values for specific random effect variances

apstartvalues(#) specify the starting value for all ancilary parameters; see details

zeros specify all initial values set to 0; see details

random specify all initial values set to draws from U(0,1); see details

chintpoints(#) set the number of integration points to calculate the cumulative hazard function

intmethod(intmethod) integration method used to integrate the random effects

intpoints(#) set the number of integration points to integrate the random effects

adaptopts(adaptopts) options for adaptive quadrature

maximize_options control the maximization process for specified model; seldom used

intmethod

mvaghermite mean-variance adaptive Gauss-Hermite quadrature;
the default

ghermite nonadaptive Gauss-Hermite quadrature

mcarlo Monte-Carlo integration using Halton sequences or anti-thetic sampling; see details

adaptopts

[no]log whether to display the iteration log
for each numerical integral calculation

iterate(#) number of iterations to update integration points; default 1001

Description

These options control how results are obtained,
from starting values, to numerical integration (also known as quadrature),
to how variance estimates are obtained.

Options

from(matname) allows you to specify starting values. Use ml display following estimation of a model to see
the equation names to help with specifying starting values.

restartvalues(sv_list) allows you to specify starting values for specific random effect variances. For example,
if you fitted a model such as,

merlin (logb time time#M2[id] M1[id], family(gaussian))

then you can override the default starting values (of 1) for the variances of the random effects M1 and M2, by
specifying something like

merlin (logb time time#M2[id] M1[id], family(gaussian)), restartvalues(M1 0.5 M2 0.1)

The default of 1 for all random effect variances can often be poor in complex models. This can solve the problem. Note, merlin
estimates on the scale of the log standard deviation for the random effects, but values should be passed to restartvalues() as variances.

apstartvalues(#) allows you to specify a starting value for all ancillary parameters, i.e those defined by
using the nap() option.

zeros tells merlin to use 0 for all parameters starting values, rather than fit the fixed effect model. Both restartvalues()
and apstartvalues() can be used with zeros.

random tells merlin to use draws from a Uniform distribution U(0,1) for all parameter
starting values, rather than fit the fixed effect model. Both restartvalues()
and apstartvalues() can be used with random.

chintpoints(#) defines the number of Gauss-Legendre integration (quadrature) points used to calculate analytically intractable
cumulative hazard functions. Default is chintpoints(30)

intmethod(intmethod),
intpoints(#), and
adaptopts(adaptopts)
affect how integration for the latent variables is numerically
calculated.

intmethod(intmethod) specifies the method and defaults
to intmethod(mvaghermite). The current implementation uses mean-variance adaptive quadrature
at the highest level, and non-adaptive at lower levels. Sometimes it is useful to fall back
on the less computationally intensive and less accurate
intmethod(ghermite) and then perhaps use one of the other more accurate
methods.

intmethod(mcarlo) tells merlin to use Monte-Carlo integration, which either uses Halton
sequences with normally-distributed random effects, or anti-thetic random draws with t-distributed
random effects.

intpoints(#) specifies the number of integration points
to use and defaults to intpoints(7) with intmethod(mvaghermite) or intmethod(ghermite),
and intpoints(150) with intmethod(mcarlo). Increasing the number
increases accuracy but also increases computational time.
Computational time is roughly proportional to the number specified.

adaptopts(adaptopts) affects the adaptive part of
adaptive quadrature (another term for numerical integration) and
thus is relevant only for intmethod(mvaghermite).

adaptopts() defaults to
adaptopts(nolog iterate(1001)).

[no]log
specifies whether iteration logs are shown each
time a numerical integral is calculated.

iterate(#) specifies the number of iterations to update the
integration points, which will include updating prior to iteration 0 in
the maximisation process.

maximize_options
specify the standard and rarely specified options for controlling the
maximization process; see [R] maximize. The relevant options for
merlin are
difficult,
technique(maximize##algorithm_spec:algorithm_spec),
iterate(#), [no]log, trace,
gradient, showstep,
hessian,
tolerance(#),
ltolerance(#),
nrtolerance(#), and
nonrtolerance.

Examples

For detailed examples, see reddooranalytics.se/products/merlin.

Setup

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

Linear mixed effects model with random intercept and slope using Monte Carlo integration

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

Author

Michael J. Crowther

Red Door Analytics

Stockholm, Sweden

michael@reddooranalytics.se