help for ipdforest

Title

ipdforest -- Forest plot for individual patient data IPD meta-analysis (one stage)

Syntax

ipdforest
varname
[, options]

where

varname the exposure variable (continuous or binary, e.g. intervention/control).

Options
re(varlist) Random effects covariate(s)

fe(varlist) Fixed effect(s) covariate(s)

fets(namelist) Fixed study-specific effect(s) covariate(s)

ia(varname) Interaction covariate

auto Automatically detect model specification

label(varlist) Study label variable(s)

or Report Odds Ratios

firstmi For multiple imputation only, use first imputed dataset for study-specific estimates

gsavedir(string) Directory to save forest-plot(s)

gsavename(string) Name prefix for forest-plot(s)

eps Save forest-plot(s) in eps format

gph Save forest-plot(s) in gph format (default)

export(string) Export results to Stata file

The forest plot has been edited to use the popular _DISPGBY display program from metan which offers numerous formatting options (see below)

Description

ipdforest is a post-estimation command which uses the saved estimates of an xtmixed/mixed or xtmelogit/meqrlogit command for multi-level linear or
logistic regression respectively. It will only work following one of these estimation commands (as stand-alone or as part of a bootstrap or mi estimate
command) and will automatically identify the model and the outcome and cluster variables (both numerical). Only two-level data structures are allowed
(patients nested within studies). The command requires one variable name as input, the exposure grouping variable, and executes a
regression analysis for each study to obtain the study effects. Binary or continuous exposure variables are allowed and if exposure is categorical
users should create dummy variables and focus on the comparison of interest through one of those, under ipdforest. Users need to follow the model
specified in the multi-level regression command and include all independent variables for which the meta-analysis regression was controlled,
using the re(), fe(), fets() or ia() options. This ensures that covariates are modelled in the individual study regressions as
they were modelled in the multi-level regression (i.e. as random,fixed, or study-specific fixed factors). Alternatively, users can use use the
auto option and allow ipdforest to automatically detect the exact specification of the preceding regression model and this will work in
most situations (see below).
A table with the study and overall effects is provided along with heterogeneity measures (some can only be calculated for xtmixed/mixed since an
estimate of within-study variance is not returned with xtmelogit/meqrlogit).

Options

re(varlist) Covariates to be included as random factors. For each covariate specified, a different regression coefficient is estimated for
each study.

fe(varlist) Covariates to be included as fixed factors. For each covariate specified, the respective coefficient in the study-specific
regressions is fixed to the value returned by the multi-level regression.

fets(namelist) Covariates to be included as study-specific fixed factors (i.e. using the estimated study fixed effects from the main regression
in all individual study regressions). Only baseline scores and/or study identifiers can be included. For each covariate specified, the respective
coefficient in the study-specific regressions is fixed to the value returned by the multi-level regression, for the specific study. For study-specific
intercepts the study identifier, not in factor variable format (e.g. studyid), or the stub of the dummy variables whould be included (e.g. studyid_ when
dummy study identifiers are studyid_1 studyid_3 etc). For study-specific baseline scores only the stub of the dummy variables is accepted (e.g.
dept0s_ when dummy study baseline scores are dept0s_1 dept0s_3 etc)

ia(varname) Covariate for which the interaction with the exposure variable will be calculated and displayed. The covariate should
also be specified as a fixed, random or study-specific fixed effect. If binary, the command will provide two sets of results, one for each group.
If categorical, it will provide as many sets of results as there are categories. If continuous, it will provide one set of results for the main effect
and one for the interaction.
Although the command will accept a variable to be interacted with the exposure variable as a fixed or study-specific fixed effect, the variable
necessarily will be included as a random effect in the individual regressions (will not run a regression with the interaction term only, the main effects
must be included as well). Therefore, although the overall effect will differ between a model with a fixed effect interacted variable and a random effect
one, the individual study effects will be identical across the two approaches.

auto Allows ipdforest to automatically detect the specification of the preceding model. This option cannot be issued along with options
re(), fe(), fets() or ia(). The auto option will work in most situations but it comes with certain limitations. It uses
the returned command string of the preceding command which is effectively constrained to 244 characters and therefore the auto option will return an
error if ipdforest follows a very wide regression model - in such a situation only the manual specification can be used. In addition, the variable
names used in the preceding model must follow certain rules: i) fixed-effect covariates (manually with option fe()) must not contain underscores,
ii) for study-specific intercepts (manually with option fets()) factor variable format is allowed or a varlist (e.g. cons_2-cons_16) but
each variable must contain a single underscore followed by the study number (not necessarily continuous) and iii) for study-specific baseline scores
(manually with option fets()) each variable must contain a single underscore followed by the study number (again, not necessarily continuous).
Note that there are no restrictions for random-effects covariates (manually with option re()). For interactions (manually with option ia())
the factor variable notation should be preferred (e.g. i.group#c.age) and alternatively the older xi notation. Interactions expanded to dummy
variables cannot be identified with the auto option and only the manual specification should be used in this case. Variables whose names start
with an '_I' and contain a capital 'X' will be assumed to be expanded interaction terms and, if detected in last model, ipdforest will
terminate with a syntax error.

label(varname) Selects labels for the studies. Up to two variables can be selected and converted to strings. If two variables are selected they
will be separated by a comma. Usually, the author names and the year of study are selected as labels. If this option is not selected the command
automatically uses the value labels of the numeric cluster variable, if any, to label the forest plot. Either way, the final string is truncated to 30
characters.

or Reporting odds ratios instead of coefficients. Can only be used following execution of xtmelogit.

firstmi For multiple imputation only, use only the first imputed dataset to obtain the study-specific estimates for the graphs. This is not an ideal
approach but it is much less computationally expensive than obtaining multiple imputation based estimates for each study-specific analysis. In some cases the
differences may be negligible, but users are urged to use with caution. Note that this only relates to the study-specific estimates, not the overall estimates
(which are always obtained from the previously executed multi-level model).

gsavedir(string) The directory where to save the graph(s), if different from the active directory.

gsavename(string) Optional name prefix for the graph(s). Graphs are saved as `gsavename'_`graphname'.gph or `gsavename'_`graphname'.eps
where `graphname' includes a description of the summary effect (e.g. "main_group" for the main effect, if group is the intervention variable)

eps Save the graph(s) in eps format, instead of the default gph.

gph Save the graph(s) in gph format - the default. Use to save in both formats, since inlcluding only
the eps option will save the graph(s) in eps format only.

export(string) Export the study identifiers, weights, effects and standard errors in a Stata dataset (named after string). Provided for users
wishing to use other commands or software to draw the forest plots.

Graph formatting options

dp(#) Decimal points for the reported effects. The default value is 2.

effect(string) This allows the graph to name the summary statistic used (e.g. OR, RR, SMD).

favours(string # string) Applies a label saying something about the treatment effect to either
side of the graph (strings are separated by the # symbol).

null(#) Displays the null line at a user-defined value rather than 0 or 1.

nulloff Removes the null hypothesis line from the graph.

nooverall Prevents display of overall effect size on graph (automatically enforces the nowt option).

nowt Prevents display of study weight on the graph.

nostats Prevents display of study statistics on graph.

nowarning Switches off the default display of a note warning that studies are
weighted from random-effects anaylses.

nohet Prevents display of heterogeneity statistics in the graph.

nobox Prevents a weighted boc being drawn for each study and markers for point estimates are only shown.

boxsca(#) Controls box scaling. The default is 100 (as in a percentage) and may be increased or decreased
as such (e.g., 80 or 120 for 20% smaller or larger respectively)

xlabel(numlist) Defines x-axis labels. Any number of points may defined and the range can be enforced
with the use of the force option. Points must be comma separated.

xtick(numlist) Adds tick marks to the x-axis. Points must be comma separated.

force Forces the x-axis scale to be in the range specified by xlabel().

texts(#) Specifies font size for text display on graph. The default is 100 (as in a
percentage) and may be increased or decreased as such (e.g., 80 or 120 for 20% smaller or larger respectively)

astext(#) Specifies the percentage of the graph to be taken up by text. The default is 50
and the percentage must be in the range 10-90.

summaryonly Shows only summary estimates in the graph.

classic Specifies that solid black boxes without point estimate markers are used as in previous versions.

lcols(varlist), rcols(varlist) Define columns of additional data to the left or right of the graph.
The first two columns on the right are automatically set to effect size and weight, unless suppressed using
the options nostats and nowt. textsize() can be used to fine-tune the size of the text
in order to acheive a satisfactory appearance. The columns are labelled with the variable label, or the variable name
if this is not defined. The first variable specified in lcols() is assumed to be the study identifier and this
is used in the table output.

double Allows variables specified in lcols and rcols to run over two lines in the plot.
This may be of use if long strings are to be used.

boxopt(), diamopt(), pointopt(), ciopt(), olineopt()
Specify options for the graph routines within the program, allowing theuser to alter the appearance of the graph.
Any options associated with a particular graph command may be used, except some that would cause incorrect graph appearance.

boxopt() controls the boxes and uses options for a weighted marker
(e.g., shape, colour; but not size). See marker options.

diamopt() controls the diamonds and uses options for pcspike (not horizontal/vertical).
See line options.

pointopt() controls the point estimate using marker options.
See marker options and marker label options.

ciopt() controls the confidence intervals for studies using options
for pcspike (not horizontal/vertical). See line options.

olineopt() controls the overall effect line with options for an additional
line (not position). See line options.

Various graph_options can be used to specify overall graph options that would appear at the end of a twoway
graph command. This allows the addition of titles, subtitles, captions etc., control of margins, plot regions, graph size,
aspect ratio and the use of schemes. See graph options.

Remarks

Each study estimate is calculated using a simple linear (regress) or logistic (logit) regression, limited to each study sample. The overall
effect is retrieved from the preceding mixed-effects regression command. Categorical variables can be specified with the 'i.' prefix, since the command
accepts factor variables.
If the multi-level regression was executed with the 'xi:' prefix, the dummy variables included in the model need to be specified individually. However,
we do not recommend this approach since full compatibility with interactions has not been ensured. Users should generate the interactions manually,
using the xi command before executing the regression command OR use the latest factor variable notation, available in v11 or later (fvvarlist).
Although the command does not accept if or in options, it makes use of e(sample) in the preceding
regression command to automatically use the selected sample.
The forest plot(s) will be saved to disc if the user provides any of the four optional graph options.
The command is compatible with multiple imputation and bootstrap commands.
In the regression models please make sure you include both main effects and interactions, if you wish to investigate interactions; otherwise the command
will fail to execute.
A description of IPD meta-analysis methods and details in the use of ipdforest have been provided in a Stata Journal paper (http://www.stata-journal.com/article.html?article=st0309).

Examples

Assuming a dataset with six studies where deptC is a continuous outcome, deptB a binary outcome , group the intervention/control grouping
variable, studyid the numeric study cluster variable, deptC_* the baseline study dummy variables for the continuous outcome and deptB_*
the baseline study dummy variables for the binary outcome (e.g. if deptC_ is the outcome baseline variable, deptC_1=deptC_ if studyid==1).

Fixed common intercept; random treatment effect; fixed study-specific effect for baseline; fixed effects for age and sex:

. xtmixed deptC group age sex deptC_1 deptC_2 deptC_3 deptC_4 deptC_5 deptC_6 || studyid:group, nocons

. ipdforest group, fe(sex age) fets(deptC_)

Fixed study-specific intercept; random treatment effect; fixed study-specific effect for baseline; random effect sex, fixed for age:

. xtmelogit deptB group i.studyid age sex deptB_* || studyid:group sex, nocons

. ipdforest group, re(sex) fe(age) fets(studyid deptB_) label(author year) or

Random intercept; random treatment effect; fixed study-specific effect for baseline; random effects for age and sex, fixed effect for measure type:

. xtmelogit deptB group age sex i.measure i.group#i.measure deptB_* || studyid:group sex age, cov(uns)

. ipdforest group, re(sex age) fe(i.measure) fets(deptB_) ia(i.measure) label(author year) or

More examples provided in the Stata Journal paper. The data file used for the examples can be obtained from within Stata:

. net from http://www.stata-journal.com/software/sj13-3/

. net describe st0309

Saved results

ipdforest saves the following in r():

Scalars

r(Isq) Heterogeneity measure I^2

r(Isqlo) Heterogeneity measure I^2, lower 95% CI

r(Isqup) Heterogeneity measure I^2, upper 95% CI

r(Hsq) Heterogeneity measure H^2

r(Hsqlo) Heterogeneity measure H^2, lower 95% CI

r(Hsqup) Heterogeneity measure H^2, upper 95% CI

r(tausq) Between study variance estimate tau^2

r(tausqlo) Between study variance estimate tau^2, lower 95% CI

r(tausqup) Between study variance estimate tau^2, upper 95% CI

r(eff1pe_overall) Overall effect estimate

r(eff1se_overall) Standard error of the overall effect

r(eff1pe_st'i') Effect estimate for study 'i'

r(eff1se_st'i') Standard error of the effect for study 'i'

If an interaction with a continuous variable is included in the model the command also returns:

r(eff2pe_overall) Overall interaction effect estimate for

r(eff2se_overall) Standard error of the overall interaction effect

r(eff2pe_st'i') Interaction effect estimate for study 'i'

r(eff2se_st'i') Interaction effect standard error for study 'i'

If the variable interacted with the intervention is binary the command returns all the resuls described above, but the first set of effect results
corresponds to the effects for the first category of the binary (e.g. sex=0) and the second set for the second category (e.g. sex=1). If the variable
is categorical the command returns as many sets of effect results as there are categories (with each set corresponding to one category).

Authors

Evangelos Kontopantelis, Centre for Primary Care, Institute of Population Health

University of Manchester, e.kontopantelis@manchester.ac.uk

David Reeves, Centre for Primary Care, Institute of Population Health, University of Manchester

Please cite as

Kontopantelis E and Reeves D. A short guide and a forest plot command (ipdforest) for one-stage meta-analysis. The Stata Journal, 2013 Oct; 13(3): 574-587.
http://www.stata-journal.com/article.html?article=st0309

Also see

help for xtmixed, xtmelogit, mixed, meqrlogit