*! version 1.0)

help dmmixedpower

Title

dmmixedpower -- dmmixedpower is a program for calculating power or sample size analytically
for a direct measures linear mixed-effects
model. This might be appropriate for the design of a randomised clinical trial that uses, for example, MRI imaging data
where the outcome is a set of directly measured differences between pairs of timepoints.

See also mixedpower, mvmixedpower, trialcounts

Syntax

dmmixedpower
,
trtspec(trtspec_type)
schedule(numlist)
[options]

* trtspec(trtspec_type) specification of treatment effect type, either slope
or intercept

* schedule(numlist) the time values for the visit schedule

alpha(#) significance level; default is 0.05

twosided request a properly two-sided test

power(#) power; default is 0.8, required to compute sample size

n(#) total sample size; required to compute power

difference(#) 1 or m treatment effect size(s) in model parameter terms - alternative to effectiveness.

effectiveness(#) 1 or m treatment effect size(s) for the slope, in
proportionate terms relative to the control group slope

contslope(#) 1 or m mean control group slope(s) that the effectiveness option is relative to.
Not required if difference used

covariance(matrix) user input of the random effect covariance matrix

errorvar(#) user input of the random error variance

auto alternative specification of covariance and error variance parameters that indicates automatic input of variance estimates from a
multivariate mixed model in memory

scale(#) the ratio of the timescale used for the variance components and the timescale in schedule;
default is 1

aratio(# #) allocation ratio between groups; default is equal allocation (1 1)

dropouts(numlist) the proportion who only reached visit k of schedule, and no further, due to dropout.
Must sum to 1

drop2(numlist) the dropout proportions in the treatment group, if different.
Must sum to 1

strecruitment(numlist) the proportion who only reached visit k of schedule, and no further, due to staggered recruitment. Need not sum to 1

noheader suppress display of dmmixedpower header banner

nosyntax suppress display of the mixed model syntax that dmmixedpower is calculating power/sample size for

notable suppress display of table count per visit given for incomplete follow-up

xmat(#) return the X matrix from 'cohort' number # in the return list

rmat(#) return the R matrix from 'cohort' number # in the return list

zmat(#) return the Z matrix from 'cohort' number # in the return list

gmat(#) return the G matrix from 'cohort' number # in the return list

bvarn(#) return the covariance matrix of fixed effects based on 'cohort' number # in the return list

*this option is required.

trtspec_type

Currently only slope and intercept terms allowed
slope proportionate slope effect i.e. constrained to equal control slope at baseline

intercept intercept effect i.e. parallel shift

Description

dmmixedpower performs analytic sample size or power calculations for a proposed RCT that employs a linear mixed effects
model for repeated 'direct measures'. Such a model is often applicable with medical imaging data; for example brain volume measures
in studies for Alzheimer's or multiple sclerosis. The standard repeated measures model would have a measure of volume for each time point and
the degree of brain atrophy would be 'indirectly' ascertained by a subtraction of brain volume at the respective time points.
However, it can be shown that greater precision of the slope estimate (and hence greater statistical power) can be obtained with 'direct'
measures of change from time point pairings. In the case of brain atrophy this means a scan with the brain boundary
outlined for one time point is overlaid with an equivalent scan from another time point, aligned with accurate positioning. Hence the
'direct' measure of brain atrophy is the area between the two delineated brain boundaries, and is prone to less measurement error than
subtraction using the two 'indirect' measures.

Details of the appropriate linear mixed model can be found in Frost et al (2004). As the outcome is a measure of difference, there is
no need for an intercept, just slope terms (parameterised as difference in time point pairings) for the control and treatment group, with
between-subject slope variability included as a random effect. For the model assumed here, all possible pairwise differences are included
as a direct measure, and for each time point a random deviation term (from linearity) is included, assumed to be identically distributed.
The error term is interpreted as measurement error in calculating the difference per pair.

Calculations for dmmixedpower follow the same general principle as for mixedpower using the asymptotic formula for the
fixed effects variance-covariance matrix of a linear mixed model: Var(B_hat)=(X'(Sigma^-1)X)^-1,
where Sigma=R+ZGZ'. The variance-covariance matrix is calculated for a nominal 2-person trial* and includes the
2-person variance* for the proposed treatment effect parameter which may then be used in a power/sample size calculation in the conventional
manner, suitably adjusting for the proposed or required sample size. Integration with trialcounts for dropout and partial follow-up
is feasible similarly to mixedpower.

* assuming allocation ratio is (1 1), otherwise covariance matrix is calculated for a N1+N2 person trial, where N1 and N2 are
the integers specified in aratio(N1 N2). If there is assumed incomplete follow-up then the covariance matrix is further
adjusted to reflect the proportions of predicted data patterns

Options

Required options

trtspec(trtspec_type) allows the user to specify different
parameterisations of the treatment effect - currently only a slope or intercept effect allowed.

slope
is for a proportionate slope effect implying that the control and treatment group slopes have a common origin, though note
the use of direct measures of difference means that intercept value is not directly modelled.

intercept is for
an intercept effect implying a constant parallel difference between control and treatment groups.

schedule(numlist) specifies the visit times for the proposed trial. A baseline
visit at time 0 is not assumed and must be given if required. The supplied number list must always be increasing and
not negative.

Basic options

alpha(#) significance level of the test; default is 0.05. Be aware that when you specify alpha(0.05)
you are in fact obtaining results for a 0.025 one-sided test, unless specifically
requesting twosided.

twosided request that sample size or power is calculated for a properly two-sided test, including power to detect a difference
in the 'opposite' direction to treatment 'improvement'. This will be denoted in the output with an asterisk next to 'alpha'.
The default is a one-sided test with type I error of alpha/2. Usually there will be no substantive difference between the two,
but that difference
will not be trace if alpha is high and/or the effect size is small.

power(#) power; default is 0.8, required to compute sample size. Sample size will be rounded up to nearest even
number and a similar principle is applied when aratio(# #) is used, see option aratio. Note, the exact
'fractional' sample size is also returned as a scalar.

n(#) total sample size; required to compute power. If the provided number is odd, the actual sample size used will be
rounded down to nearest even number. A similar principle is applied when aratio(# #) is used, see option aratio.
Note, the exact power corresponding to the rounded n, is printed as output with target power returned as a scalar as 'fractional' power
- corresponding to 'fractional' sample size.

Effect size and testing options

difference(#) the magnitude of the treatment effect, specified as the value of the relevant regression parameters.
Hence for trtspec(slope) the value supplied is the absolute change of the treatment group relative to control group per unit time.

effectiveness(#) for the trtspec(slope) selection only, instead of using difference
the user may alternatively specify
the treatment magnitudes in proportionate terms relative to the control group slope. The value(s) supplied should be a real
number >0 and <=1. For example, effectiveness(0.3)
for a 30% change towards a null slope for each outcome.
This option also requires use of contslope to represent the control group slope the
effect is relative to. If you wish to specify an effect that i) results in an effect in the opposite
direction (positive to negative slope or vice-versa) or ii) increase (decreases) further an already positive (negative)
slope then you will need to use difference.

contslope(#) this option is to be used in conjunction with effectiveness and represents the mean control group
slope that the effectiveness option is relative to, entered as a real number.
Not required if difference used.

Variance options

covariance(matrix) the covariance matrix of the random effects, entered as a 2x2 symmetrical matrix. Currently the
allowable covariance strucure is restrictive: the first variance on the diagonal is to apply to all visit-specific random deviations and the
second is for the random slope variance, with zeros in the off-diagonals. Hence, random deviations are identically distributed in addition to
independent, and are also independent of the random slope.

See option auto for a shortcut to using covariance and errorvar together.

errorvar(#) the error variance term, entered as a mxm matrix,
where m is the number of joint outcomes and error covariances across outcomes may be specified.

See option auto for a shortcut to using covariance and errorvar together.

auto use of this option will automatically transfer the random effect and error variance values from a suitable
mixed model in memory, and is an auto-input alternative to using covariance and errorvar. It is the user's
responsibility to ensure the model is 'suitable'.

With dmmixedpower the user must be careful how the mixed model in memory
has been fitted. Specifically the k visit-specific random deviation terms are all named after the first double piping with the
nocons and cov(unstructured) options, followed by the random slope after the second double piping, again followed
by the nocons option. Note also the use of the collinear option. For example, if there were 4 timepoints in schedule

. mixed depvar c.time_diff c.time_diff#1.trt, nocons || id_level2: itime_1 itime_2 itime_3 itime_4, covariance(identity) noconstant collinear || id_level2: time_diff, noconstant collinear

Adjustment options

scale(#) use this option if you wish to specify visit times in a different scale to that relating to the
inputted random effect (co-)variance parameters.
For example, if your variance parameter estimates came from a model where time was specified in years,
but you wished to calculate power for a trial that had a visit schedule specified in months you could use scale(`=1/12').
Scale-dependent effect sizes (slope-based) should be kept unchanged in difference - the fundamental aspects
(schedule and effect size) are specified in the scale you wish, but variance parameters from a source with a different scale
are rescaled by scale.

aratio(# #) specifies relative group sizes (allocation ratio). aratio requires two integers reflecting the control group
to treatment group allocation ratio. The default is aratio(1 1) i.e equal group size, though there is no limit to the
maximum value of either #.
When calculating required sample size,
the smallest n achieving target power is calculated that results in integer group sizes.
Hence actual power may be slightly more than if 'fractional'
subjects were allowed, which could meet target power exactly. When calculating power, the actual sample size used is the largest
n <= n(#) that gives integer group sizes. Hence, actual power may be slightly increased if any 'spare' samples were allocated
to one of the groups. Note, this rule is always followed, so if aratio(3 3) was chosen, then depending on n(#),
power could be slightly less than aratio(1 1) even though the allocation ratio itself is equivalent,
as actual n may need to be smaller to ensure integer group sizes.
Because you can enter any integer value, aratio(# #) can also be used to accurately calculate power after recruitment is finished,
knowing that in fact the allocation was not perfectly balanced. For example, enter aratio(152 147).
Note 'fractional' power and 'fractional' sample size
are also returned in the stored results.

dropouts(numlist) specifies the estimated proportion of dropouts out of the original sample you
expect following each study visit. It must correspond exactly to the length of the schedule list.
Each number in the list should be between 0 and 1 and is the proportion who only reached visit k, and no further,
due to dropout. To be clear, the proportion is not out of those remaining at visit k but of those eligible for full
follow-up. Therefore one does not to consider the impact of strecuitment when specifying the dropout list values.
Furthermore, the sum of all proportions should be equal to one, as it makes no sense to have subjects
withdraw before the trial begins. There is a built-in tolerance of 0.00001
to deal with numerical inaccuracies within Stata.

drop2(numlist) specifies a set of dropout proportions specifically for the treatment group, if it is believed they
will be different from the control. Rules are exactly as for dropouts.

strecruitment(numlist) specifies the proportion of the original sample who have only reached as far as visit k,
and no further,
due to the effect of staggered recruitment to the trial. Each number in the list should be between 0 and 1 and
the sum of all proportions should not exceed one. There is a built-in tolerance of 0.00001
to deal with numerical inaccuracies within Stata. Sums less than one are allowed however, and for staggered recruitment make sense, if one
wishes to calculate power for an interim stage of a trial with an established final sample size, but at this interim point not everyone
has yet been randomised. If both strecruitment and dropouts are specified then the integrated cohort proportions
(weights) are also returned in the stored results. Use of companion program trialcounts
is recommended as an accessible way to generate appropriate strecruitment proportions.

It is also worth mentioning that
strecruitment is more relevant for calculating power rather than sample size, as it reflects recruitment constraints. Used for
a sample size calculation, it implies that needing a bigger sample can be achieved by simply recruiting more in a given timeframe. If
that is not the case, then use trialcounts to work with dmmixedpower to find when a sufficient sample size can be achieved.

Reporting options

noheader prevents display of the dmmixedpower header banner.

nosyntax prevents the default display of the mixed model syntax for the requested model that dmmixedpower has calculated
power or sample size for. All terms in italics are placeholder names for variables
names that the user would supply when fitting that model. The syntax given may not be the only way to fit a particular model, but is
a recommended parameterisation when matching with dmmixedpower and, in particular, for utilising the auto-input methods.

notable prevents display of the table of counts by visit, otherwise produced when follow-up is incomplete.
If either dropouts or
strecuitment is supplied indicating that not all subjects have all been recorded for all outcome measures, then a table is
produced that lists the (rounded) number of subjects who have been observed for each visit by treatment arm (so different if drop2 or aratio meaningully supplied).

xmat(#) returns the X design matrix for a particular 'cohort' identified by visit number # from the schedule list. This is only
possible for cohorts with non-zero probability weightings. This means that if both dropouts and strecruitment are not used then
one can only request the X matrix appropriate for the last visit (number #) in schedule where all individuals have a full complement
of measures. Note r(xmat) is not automatically returned as there is potential for the matrix to be large. When displaying r(xmat) there
are rownames to help identify rows. The tags include 't' for (treatment) group (0 for control, 1 for treatment) and
'v' for visit pairing (the visit index numbers in the schedule list) that represent the difference measures.
The columns are not labelled but X1 is the control slope and X2 the treatment effect.
One may use xmat(#), rmat(#), zmat(#), gmat(#) and bvarn(#) together
and # can be different for all options, assuming the selections are individually permissible.

rmat(#) returns the R error matrix for a particular 'cohort' identified by visit number # from the schedule list. All information
given in xmat applies here, except for column identification, where instead column matches row.

zmat(#) returns the Z design matrix of random effects for a particular 'cohort' identified by visit number #
from the schedule list. All row information
given in xmat applies here, except for column identification, where the random deviation terms per visit come in order followed
by the random slope, firstly for the control and then treatment group.

gmat(#) returns the G covariance matrix of random effects for a particular 'cohort' identified by
visit number # from the schedule list. The matrix r(gmat) has no row- or column-name information other than G1, G2..
and a covariance-block
of random effects is given for the control then treatment group. The row and column ordering per group matches the column
identification information given in zmat(#).

bvarn(#) returns the covariance matrix of the estimated fixed parameters calculated for a particular 'cohort'
identified by visit number # from the schedule list. This is only possible for cohorts with non-zero probability weightings.
Note that the option bvarn returns not just matrix r(bvar_n), but also the working correlation matrix r(wcorr_n), and
the working
covariance matrix r(sigma_n). For r(bvar_n) there is
no row- or column-name information, but the order of variables is exactly as described in option xmat(#).

Examples

For an example of the direct measures model, we recreate a power calculation
taken from a real interim analysis plan for a trial in MS, that used a generous alpha criterion.
The difference measures themselves reflect % reduction in whole brain atrophy between scans from 2 different timepoints.
It may be worth looking at the X and Z matrices from the last 'cohort' to help understand how this model is parameterised.

`". dmmixedpower, trtspec(slope) sched(0 0.5 1.5 2) diff(0.132) alpha(0.7) n(230) cov(0.14, 0 \0 ,.15) error(0.087) strec(0 0 .43478261 .56521739) xmat(4) zmat(4)"'

`". mat li r(xmat)"'

`". mat li r(zmat)"'

Stored results

mvmixedpower stores the following in r():

Scalars

r(fractional_ss) 'fractional' sample size without rounding

r(samplesize) calculated or supplied sample size

r(fractional_power) power without rounding of supplied sample size

r(power) calculated or supplied power

r(effectsize) the treatment effect standardised by the variance=r(wgt_trteff)/r(var_trteff)

r(wgt_trteff) the overall (weighted) treatment effect, linearly combined from m outcome effects

r(var_trteff) the variance of r(wgt_trteff) for a (N1+N2)-person trial adjusted for incomplete follow-up

r(se_trial) the standard error of r(trt_eff) for the trial reflecting final sample size

r(scale) scale used

r(alpha) type I error rate (significance level)

Macros

r(cmdline) command line

r(cmd) command

r(schedule) schedule list

r(final_wgts) integrated probability weights of dropout and staggered recruitment

r(final_wgts2) integrated probability weights for treatment group, if different

r(fw_rescale) rescaled integrated weights to sum to 1

r(fw_rescale2) rescaled integrated weights for treatment group, if different

r(cont_spec) model parameterisation of control group

r(trt_spec) model parameterisation of treatment group

r(twosided) if calculation based on properly two-sided test or not

r(aratio) allocation ratio

r(trialcounts_cmd) trialcounts command line, if previous rclass command

r(fr_current) current frame at command

Matrices

r(sched_list) schedule list

r(cont_num) control numbers reaching each visit

r(trt_num) treatment numbers reaching each visit

r(contrd_num) rounded control numbers reaching each visit

r(trtrd_num) rounded treatment numbers reaching each visit

r(m_weights) weights used for linear combination of m treatment effects

r(trtbeta_true) true treatment group beta coefficients

r(beta_var) covariance matrix of fixed effects

r(wcorr_n) working correlation matrix if requested, for a given cohort

r(sigma_n) working covariance matrix if requested, for a given cohort

r(bvar_n) covariance matrix of fixed effects if requested, for a given cohort

r(xmat) X matrix if requested, for a given cohort

r(rmat) R matrix if requested, for a given cohort

r(zmat) Z matrix if requested, for a given cohort

r(gmat) G matrix if requested, for a given cohort

r(cohort_wgts) integrated probability weights of dropout and staggered recruitment

r(cohort_wgts2) integrated probability weights for treatment group, if different

r(st_rec) staggered recruitment probability weights

r(dropouts) dropout probability weights

r(dropouts2) dropout probability weights for treatment group, if different

References

Chris Frost, Michael G. Kenward, Nick C. Fox. Optimizing the design of clinical
trials where the outcome is a rate. Can estimating a baseline rate in a run-in
period increase efficiency? Statist. Med. 2008; 27:3717–3731 doi: 10.1002/sim.3280

Chris Frost, Michael G. Kenward, Nick C. Fox. The analysis of repeated 'direct' measures of change
illustrated with an application in longitudinal imaging. Statist. Med. 2004; 23:3275–3286

Author

Matthew Burnell
MRC Centre of Research Excellence in Clinical Trial Innovation
University College London
London, UK
m.burnell@ucl.ac.uk