{smcl} {* *! version 4.07 David Fisher 15sep2023}{...} {vieweralsosee "metan" "help metan"}{...} {vieweralsosee "forestplot" "help forestplot"}{...} {vieweralsosee "metani" "help metani"}{...} {vieweralsosee "" "--"}{...} {vieweralsosee "ipdmetan" "help ipdmetan"}{...} {vieweralsosee "ipdover" "help ipdover"}{...} {viewerjumpto "Syntax" "forestplot##syntax"}{...} {viewerjumpto "Description" "forestplot##description"}{...} {viewerjumpto "Options" "forestplot##options"}{...} {viewerjumpto "Saved results" "forestplot##saved_results"}{...} {viewerjumpto "Note: differences from previous version of metan" "forestplot##diffs_metan"}{...} {viewerjumpto "Examples" "forestplot##examples"}{...} {title:Title} {phang} {cmd:forestplot} {hline 2} Create forest plots from data currently in memory {marker syntax}{...} {title:Syntax} {p 8 18 2} {cmd:forestplot} [{it:ES lci uci}] {ifin} [{cmd:, }{it:options}] {synoptset 30 tabbed}{...} {synopthdr} {synoptline} {syntab: Main} {synopt :{it:{help eform_option}}}exponentiate effect sizes and confidence limits{p_end} {synopt :{opt eff:ect(string)}}title for "effect size" column in the output{p_end} {synopt :{cmdab:fav:ours(}{it:favours_option}{cmd:)}}{it:x}-axis labelling specific to forest plots{p_end} {synopt :{opt lab:els(varname)}}variable containing labels e.g. subgroup headings, heterogeneity info, study names{p_end} {synopt :{opt lcol:s(varlist)} {opt rcol:s(varlist)}}display columns of additional data{p_end} {synopt :{opt prefix(prefix)}}specify that a prefix was previously added to default variable names; see {bf:{help metan}}{p_end} {synopt :{opt nona:mes}}suppress display of study names in left-hand column{p_end} {synopt :{opt nonu:ll} {opt nu:ll(#)}}suppress, or override default {it:x}-intercept of, null hypothesis line{p_end} {synopt :{opt noov:erall} {opt nosu:bgroup} {opt nohet}}suppress display of observations containing overall, subgroup, or heterogeneity data (see {opt use(varname)}){p_end} {synopt :{opt nostat:s} {opt nowt}}suppress display of effect estimates and/or weights in right-hand columns{p_end} {synopt :{opt xla:bel(...)} {opt xt:ick(...)}}{it:x}-axis ticks and labels as described under {it:{help axis_label_options}}, but see {help forestplot##options:below}{p_end} {synopt :{it:{help twoway_options}}}other Stata twoway graph options, as appropriate{p_end} {syntab: Advanced} {synopt :{cmd:dataid(}{it:varname} [{cmd:, newwt}]{cmd:)}}define groups of observations making up a complete forestplot{p_end} {synopt :{opt double}}allow column text to run over two lines in the plot{p_end} {synopt :{opt dp(#)}}number of decimal places with which to format effect sizes, confidence intervals and predictive distributions{p_end} {synopt :{opt leftj:ustify}}left-justify all data columns{p_end} {synopt :{opt maxlines(#)} {opt maxwidth(#)}}override the defaults used by {cmd:forestplot} when spreading column title strings over multiple lines{p_end} {synopt :{opt nokeepv:ars}}suppress saving of formatted effect-size data in new variable {bf:_EFFECT}; see {help forestplot##saved_results:saved results}{p_end} {synopt :{cmd:plotid(}{it:varname} [{cmd:, {ul:l}ist {ul:nogr}aph}]{cmd:)}}define groups of observations in which to apply specific plot rendition options{p_end} {synopt :{cmd:rfdist(}{it:rflci rfuci}{cmd:)}}display confidence intervals for predictive distributions (typically generated by {bf:{help metan}} or {bf:{help ipdmetan}}){p_end} {synopt :{opt useopt:s}}use set of {cmd:forestplot} options previously supplied to {bf:{help metan}}, {bf:{help ipdmetan}} or {bf:{help ipdover}}{p_end} {synopt :{opt usestrict}}check that data is consistent with the interpretation of {opt use(use)} as defined in the {help forestplot##description:Description} section{p_end} {syntab: Fine-tuning} {synopt :{opt noadj:ust}}suppress "space-saving" adjustment to text/data placement{p_end} {synopt :{opt ast:ext(#)}}percentage of plot width to be taken up by columns of text{p_end} {synopt :{cmdab:ra:nge(}[{it:numlist}] [{opt min}] [{opt max}]{cmd:)}}x-axis limits of data plotting area{p_end} {synopt :{cmdab:cira:nge(}[{it:numlist}] [{opt min}] [{opt max}]{cmd:)}}x-axis limits of plotted confidence intervals{p_end} {synopt :{opt savedims(matname)}, {opt usedims(matname)}}save and load sets of dimensional parameters for forest plot{p_end} {synopt :{opt sp:acing(#)}}vertical gap between lines of text in the plot{p_end} {synopt :{opt texts:ize(#)}}fine-tune the text size{p_end} {syntab: Plot rendition} {synopt :{it:plot}{cmd:{ul:op}ts(}{it:plot_options}{cmd:)}}affect rendition of all observations{p_end} {synopt :{it:plot{ul:#}}{cmd:opts(}{it:plot_options}{cmd:)}}affect rendition of observations in {it:#}th {cmd:plotid} group{p_end} {synopt :{cmdab:hlineop:ts(}{it:plot_options}{cmd:)}}affect rendition of horizontal line above data and below column headings{p_end} {synopt :{cmdab:nlineop:ts(}{it:plot_options}{cmd:)}}affect rendition of null line{p_end} {synopt :{opt nobox}}suppress weighted boxes; markers for point estimates only are shown{p_end} {synopt :{opt box:scale(#)}}box size scaling{p_end} {synopt :{opt nodia:monds}}replaces pooled-effect diamonds with markers and horizontal lines, similar to individual studies{p_end} {synopt :{opt classic}}use "classic" set of plot options, as in {bf:{help metan9}}{p_end} {synopt :{opt interaction}}use "interaction" set of plot options{p_end} {synoptline} {pstd} where {it:plot} may be {cmd:{ul:box}}, {cmd:{ul:ci}}, {cmd:{ul:diam}}, {cmd:{ul:oline}}, {cmd:{ul:ociline}}, {cmd:{ul:point}}, {cmd:{ul:pci}}, {cmd:{ul:ppoint}}, {cmd:{ul:rf}} or {cmd:{ul:rfciline}} {pstd} and {it:plot_options} are {it:{help marker_options}}, {it:{help line_options}} or {it:{help area_options}} as appropriate, with some additional options as described {help forestplot##plot_rendition:below}. {p2colreset}{...} {p 4 6 2} {marker description}{...} {title:Description} {pstd} {cmd:forestplot} creates forest plots from variables containing point estimates and lower/upper confidence limits. The aggregate-data meta-analysis program {bf:{help metan}} calls {cmd:forestplot} by default, and passes on any relevant options. The individual participant data (IPD) meta-analysis programs {bf:{help ipdmetan}} and {bf:{help ipdover}} ({help forestplot##refs:Fisher 2015}) also make use of {cmd:forestplot}. All these programs can also save datasets with additional information that {cmd:forestplot} recognises (see {help metan##saved_datasets:saved datasets}). Alternatively, {cmd:forestplot} can simply be run on data currently in memory. {pstd} If variables {it:ES}, {it:lci} and {it:uci} are not supplied, {cmd:forestplot} will expect to find variables in memory named {bf:_ES}, {bf:_LCI} and {bf:_UCI}. In either case, these three variables should represent the effect size (point estimate) and lower/upper confidence limits on the interval scale (i.e. not exponentiated). {pstd} By default, {cmd:forestplot} will also check for variables named {bf:_USE}, {bf:_WT} and {bf:_LABELS}. If the dataset in memory was created by {bf:{help metan}}, {bf:{help ipdmetan}} or {bf:{help ipdover}}, these variables should already exist (see {help metan##saved_datasets:saved datasets}). Otherwise (or if the user wishes not to use these variables), any of options {opt use(use)}, {opt wgt(wgt)} or {opt labels(labels)} may be supplied, containing alternative {it:varname}s. {pstd} If the option {opt prefix(prefix)} is specified, {cmd:forestplot} will instead check for variables named {it:prefix}{bf:_ES}, {it:prefix}{bf:_USE} and so on; see {bf:{help metan}}. {pstd} The meaning of these variables is as follows: {p 8 40 2}{bf:_USE} or {it:use}{space 16}an indicator of the contents of each observation (study effects, titles, spacing, description of heterogeneity, etc); see below{p_end} {p 8 40 2}{bf:_WT} or {it:wgt}{space 17}observation weights; that is, the relative size of {help scatter:markers} in the forest plot{p_end} {p 8 40 2}{bf:_LABELS} or {it:labels}{space 10}labels for the left-most column of the forest plot, usually containing study names, subgroup titles and heterogeneity details{p_end} {pstd} If neither the default {it:varname} or an alternative is found, {it:use} and {it:wgt} will default to 1 throughout. {pstd} The values of {bf:_USE} or {it:use} are interpreted by {cmd:forestplot} in the following way: {p_end} {p 8 15 2}0 = subgroup labels (headings); general text{p_end} {p 8 15 2}1 = non-missing study estimates{p_end} {p 8 15 2}2 = missing study estimates{p_end} {p 8 15 2}3 = subgroup pooled effects{p_end} {p 8 15 2}4 = heterogeneity information; assumed to be present only in the first left-hand column{p_end} {p 8 15 2}5 = overall pooled effect{p_end} {p 8 15 2}6 = blank line{p_end} {p 8 15 2}7 = prediction interval data{p_end} {pstd} Note that {cmd:forestplot} creates a variable named {bf:_EFFECT} containing a string-valued concatenation of the (formatted) effect size and confidence limits, which by default is plotted in a column to the right of the plotted data. If a variable {bf:_EFFECT} was previously created by {cmd:metan} (see {help metan##saved_datasets:saved datasets}), then it will be overwritten by {cmd:forestplot}. Hence, to avoid losing information stored in the existing variable (such as user-inserted p-values), you can specify the option {cmd:rcols(_EFFECT)} in conjunction with {opt nostats} when running {cmd:forestplot}. This tells {cmd:forestplot} that instead of creating (and hence overwriting) {bf:_EFFECT}, it should instead use the existing variable as a standard column of data. (The weight variable {bf:_WT} will typically also need to be added to {opt rcols()}, along with the {opt nowt} option, to maintain the default ordering of data columns.) This technique is demonstrated in the penultimate {help forestplot##examples:example}. {marker options}{...} {title:Options} {dlgtab:Main} {phang} {it:{help eform_option}} specifies that the effect sizes and confidence limits should be exponentiated. The option also generates a heading for the effect size column in the output (table and forest plot). {pmore} Note that {cmd:forestplot} expects effect sizes to be beta coefficients (i.e. on the linear scale). {phang} {opt effect(string)} specifies a heading for the effect size column in the output. This overrides any heading generated by {it:{help eform_option}}. {phang} {opt favours(favours_option)} applies a label saying something about the treatment effect to either side of the graph, with the following syntax (carried over from {bf:{help metan9}}): {pmore2} {cmd:favours(}{it:left_text} {cmd:#} {it:right_text} [{cmd:,} {it:suboptions}]{cmd:)} {pmore} where {it:left_text} and {it:right_text} may consist of multiple lines of text delimited by quotes, as described in {it:{help title_options##remarks1:title_options}}; and {it:suboptions} are any {it:{help axis_label_options}} relevant to text rather than to label values. In addition, the following suboptions may be used: {pmore2} {opt nosym:metric} overrides the default symmetric placement of left and right labels about the null line. Instead, the labels are independently placed midway between the null line and the extremity of the plot region. {pmore2} {opt fp(#)} specifies an x-axis value for one or other of the labels; the other is then placed symmetrically about the null line. {phang} {opt lcols(varlist)} and {opt rcols(varlist)} define columns of additional data to the left or right of the graph. These options work in exactly the same way as in {bf:{help metan}} when specified directly to {cmd:forestplot}. {pmore} By default, the first column on the left will contain study names/identifiers, and the first two columns on the right will contain effect sizes and confidence intervals, and study weights (unless suppressed using the options {opt nonames}, {opt nostats} and {opt nowt} respectively). Columns specified in {opt lcols()} and {opt rcols()} will appear next to these in the order supplied. {phang2} Note: These options have a different syntax when specified to {bf:{help ipdmetan##forestplot_options:ipdmetan}}. {phang} {opt nonull} and {opt null(#)} affect the null hypothesis line. By default, this line appears at x=0, or x=1 if {it:{help eform_option}} is specified. {opt null(#)} overrides this, whilst {opt nonull} suppresses the display of the line. Note that both may be specified simultaneously; the placement of the line affects other characteristics of the plot even if the line itself does not appear. {phang} {opt xlabel(...)} and {opt xtick(...)} have the same syntax as described under {it:{help axis_label_options}}, except for the following points: {phang2} If {it:{help eform_option}} is specified, the {it:x}-axis is automatically shown on an expontiated scale, with a value of 1 indicating a null effect. Hence, values supplied to {opt xlabel()} and {opt xtick()} are interpreted on this scale; e.g. values of 0.5 and 2 would appear symmetrically either side of the null line. A similar interpretation also applies to {opt fp(#)} and {opt null(#)}. {phang2} An alternative to {opt range()} (see {help forestplot##fine_tuning:below}) is to allow {opt force} as an additional sub-option to {opt xlabel()}. The smallest and largest values supplied to {opt xlabel()} then become the plotted limits of study confidence intervals and effect sizes. (Note: the {opt force} option is carried over from {bf:{help metan9}}). {dlgtab:Advanced} {phang} {cmd:dataid(}{it:varname} [{cmd:, newwt}]{cmd:)} define groups of observations making up a complete forest plot. It may be that the data in memory comes from multiple separate meta-analyses, to be plotted within the same {it:plot region} (see {it:{help region_options}}) and with the same axes, labels, headings etc. Specifying {opt dataid()} tells {cmd:forestplot} about this structure, resulting in correct placement of overall and/or subgroup effect lines. Note that {opt dataid()} does not alter the placement or ordering of data within the plot. {pmore} The {opt newwt} suboption requests that weighted box scaling is normalised within levels of {it:varname}. {phang} {opt double} allows the text of variables specified in {opt lcols()} and {opt rcols()} to run over two lines in the plot. This may be of use if long strings are to be used. {phang} {opt dp(#)} specifies the number of decimal places to format the effect sizes. {phang2} See also options {opt savedims()} and {opt usedims()}. {phang} {opt leftjustify} left-justifies all data columns, rather than applying the {help format}ting of each variable as currently in memory. {pmore} Note that {bf:{help metan}} will left-justify string variables before creating "results sets", including the left-most "study name" column. However, individual variables in {opt lcols()}, {opt rcols()} or {opt labels()}, whether numeric or string, may be {help format}ted within the dataset before running {cmd:forestplot} or {bf:{help metan}}. (If using {cmd:ipdmetan} or {cmd:ipdover}, formatting may also be applied within the {help ipdmetan##cols_info:{it:cols_info}} syntax). {phang} {opt maxlines(#)} and {opt maxwidth(#)} may help in circumstances where {cmd:forestplot} gives suboptimal formatting for the titles of one or more data columns. They override some of the defaults used by {cmd:forestplot} when cutting up and spreading column title strings over multiple lines. {phang2} {opt maxlines(#)} increases the number of lines over which a column title can be spread, from the default of 3. This may be useful when the title is lengthy but consisting of mostly short words. {phang2} {opt maxwidth(#)} increases the maximum permitted width (i.e. length) of each line of a column title. This may be useful when the width of the column {ul:data} is small compared to that of the column {ul:title}. {phang} {cmd:plotid(}{it:varlist} [{cmd:,} {opt list} {opt nograph}]{cmd:)} specifies one or more categorical variables to form a series of groups of observations in which specific aspects of plot rendition may be affected using {cmd:box}{it:#}{cmd:opts}, {cmd:ci}{it:#}{cmd:opts} etc. The groups of observations will automatically be assigned ordinal labels (1, 2, ...) based on the ordering of {it:varlist}. Note that {opt plotid()} does not alter the placement or ordering of data within the plot. {pmore} The contents of each group may be inspected with the {cmd:list} option. In complex situations it may be helpful to view this list without creating the plot itself; this may be achieved using the {cmd:nograph} option. {phang} {opt rfdist(varlist)} specifies two variables containing the lower and upper limits of prediction intervals associated with pooled estimates. As such, observations containing prediction interval data should have {it:use} = 3 or 5. See the {bf:{help metan}} option {cmd:rfdist} for more information. {pmore} Rendering of prediction intervals may be controlled using the {cmd:rfopts()} and {cmd:rf}{it:#}{cmd:opts()} options. {phang} {opt useopts} applies a list of previously-saved options. {pmore} {opt useopts} is useful when a "results set" saved by {bf:{help metan}} is loaded and edited before running {cmd:forestplot} to create the final plot. Any options supplied to {bf:{help metan}} with relevance to the forest plot (mostly, but not exclusively, those supplied as {opt forestplot()} sub-options) are saved within the "results set" as {help char:data charateristics}, and may subsequently be applied by specifying {opt useopts}. If an option name found in {opt useopts} is also supplied as an option to {cmd:forestplot} in the standard way, then the option within {opt useopts} will be overridden. {pmore} Note that {opt useopts} typically also contains information on {it:varlist}, {opt use()}, {opt wgt()} and {opt labels()}. {phang} {opt usestrict} checks that the data is consistent with {it:use}. Since {cmd:forestplot} will otherwise go ahead and interpret the data on the basis of the observed values of {it:use}, this might be a useful way of investigating why a plot did not look as intended. Specifically, {opt usestrict} checks that: {pmore} {it:ES}, {it:lci} and {it:uci} are non-missing if {it:use}{bf: == 1} {pmore} {it:ES}, {it:lci}, {it:uci} and {it:wgt} are missing if {it:use}{bf: == 2} {pmore} {it:labels} and {it:wgt} are missing if {it:use}{bf: == 6} (unless {opt nonames} or {opt nowt} are supplied, respectively) {pmore} values of {it:use} are between 0 and 6 inclusive. {marker fine_tuning}{...} {dlgtab:Fine-tuning} {pstd} These options allow fine-tuning of the plot construction and text/data placement. Forest plots are non-standard twoway plots, and have features that Stata graphs were not designed to accommodate (e.g. columns of text, and a wide range of potential aspect ratios). Occasionally, therefore, {cmd:forestplot} will produce unsatisfactory results, which may be improved by use of one or more of these options. {phang} {opt noadjust} suppresses a calculation within {cmd:forestplot} which sometimes results in text overlapping the plotted data. {pmore} This calculation, carried over from {bf:{help metan9}}, attempts to take advantage of the fact that pooled-estimate diamonds have less width than individual study estimates, whilst their labelling text is often longer, to "compress" the plot and make it more aesthetic. {phang} {opt astext(#)} specifies the percentage of the width of the plot region to be taken up, in total, by columns of text. The default is 50 and the percentage must be in the range 10-90. {phang} {opt boxscale(#)} controls scaling of weighted boxes. 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). {phang} {opt range()}, {opt cirange()} give finer control over the range of the x-axis within which the graph is constructed, and within which the data is plotted. These options may be used, for instance, to create or reduce blank space between the data and either the left or right columns of text or data. (Note that blank space may also be created or reduced by appropriate {help format}ting of column variables.) {phang2} {cmd:range(}[{it:numlist}] [{opt min}] [{opt max}]{cmd:)} specifies the boundary between the part of the x-axis within which the graph will appear, and the parts containing columns of text or data (see {opt lcols()}, {opt rcols()}). {opt min} and {opt max} are shorthand for the smallest and largest values among the data to be plotted. If {opt min} is specified, then {opt range()} also implies {opt noadjust}. {phang2} {cmd:cirange(}[{it:numlist}] [{opt min}] [{opt max}]{cmd:)} specifies the plotted limits of study confidence intervals and effect sizes. Data outside this range will be represented by off-scale arrows. {opt min} and {opt max} are shorthand for the smallest and largest values among the data to be plotted. {phang2} Note: the documented option {opt range()} as a sub-option to {bf:{help axis_scale_options:xscale()}} should {ul:not} be used with {cmd:forestplot}, as it will almost certainly not give the desired effect. However, other {bf:{help axis_scale_options:xscale()}} sub-options such as {opt lcolor()} may be used. {phang} {opt savedims(matname)} saves certain values ("dimensions") associated with the current forest plot in a matrix, so that they may be applied via {opt usedims(matname)} to a subsequent forest plot. These values, which are also saved in {cmd:r()}, include the calculated optimum text size, aspect ratio, vertical spacing, and the display width of the different parts of the plot. {phang} {opt spacing(#)} alters the vertical gap between lines of text. Increasing it has the side-effect of making the text size smaller, and vice versa. Default values are 1.5 if the plot is "tall" (many studies) or 2 if the plot is "wide" (few studies). {phang} {opt textsize(#)} applies a correction factor to the default text size. {it:#} is a percentage of the default size, such that {cmd:textsize(100)} represents no change. Note that {cmd:forestplot} takes {opt spacing(#)} into account when determining optimum values for text size and plot layout; whereas {opt textsize(#)} is applied {it:post hoc}. {marker plot_rendition}{...} {dlgtab:Plot rendition} {pstd} These options specify sub-options for individual components making up the forest plot, each of which is drawn using a separate {help twoway} command. Any sub-options associated with a particular {help twoway} command may be used, unless they would conflict with the appearance of the graph as a whole. For example, confidence intervals are plotted using the {help twoway_rspike:twoway rspike} command, so {it:{help line_options}} may be used, but not {opt horizontal} or {opt vertical}. As with any Stata {help twoway} command, default plot options will be taken from the current graph {help schemes:scheme}. {phang2} {cmd:hlineopts(}{it:{help line_options}}{cmd:)} affects the rendition of the horizontal line above the data and below the column headings. {phang2} {cmd:boxopts(}{it:{help marker_options}}{cmd:)} and {cmd:box}{it:#}{cmd:opts(}{it:{help marker_options}}{cmd:)} affect the rendition of weighted boxes representing point estimates and use options for a weighted marker (e.g., shape, colour; but not size). {phang2} {cmd:ciopts(}[{it:{help line_options}}] [{cmd:nooverlay}] [{cmd:rcap}]{cmd:)} and {cmd:ci}{it:#}{cmd:opts(}[{it:{help line_options}}] [{cmd:rcap}]{cmd:)} affect the rendition of confidence intervals. The additional option {cmd:nooverlay} draws confidence interval lines {ul:behind} weighted boxes rather than overlaying them (note: cannot be specified with {cmd:ci}{it:#}{cmd:opts()}). The additional option {cmd:rcap} requests capped spikes. {phang2} {cmd:diamopts(}{it:{help area_options}}{cmd:)} and {cmd:diam}{it:#}{cmd:opts(}{it:{help area_options}}{cmd:)} affect the rendition of diamonds representing pooled estimates. {phang2} {cmd:nlineopts(}[{it:{help line_options}}] [{cmd:nooverlay}]{cmd:)} affects the rendition of the null hypothesis line. The additional option {cmd:nooverlay} draws this line first, and places data features (e.g. weighted boxes, confidence interval lines) on top. {phang2} {cmd:olineopts(}[{it:{help line_options}}] [{cmd:nooverlay}]{cmd:)} and {cmd:oline}{it:#}{cmd:opts(}{it:{help line_options}}{cmd:)} affect the rendition of overall effect lines. The additional option {cmd:nooverlay} draws these lines first, and places data features (e.g. weighted boxes, confidence interval lines) on top (note: cannot be specified with {cmd:oline}{it:#}{cmd:opts()}). {pmore2} Note: For {cmd:oline}{it:#}{cmd:opts()} to take effect, {it:#} must be the value taken by {opt plotid} at the observation corresponding to the relevant pooled effect. If the pooled effect itself is {ul:not} plotted, e.g. for an {opt influence} meta-analysis (see {opt ocilineopts()}), {it:#} must be the value taken by {opt plotid} at the observation where the overall effect line begins. {phang2} {cmd:ocilineopts(}[{it:{help line_options}}] [{it:{help area_options}}] [{cmd:hide}]{cmd:)} and {cmd:ociline}{it:#}{cmd:opts(}[{it:{help line_options}}] [{it:{help area_options}}] [{cmd:hide}]{cmd:)} affect the rendition of optional additional vertical lines representing the confidence limits of the pooled effect. By default, {opt cumulative} and {opt influence} meta-analyses (see {bf:{help metan}}) display these lines, along with the option {opt hide} which "hides" the pooled-effect observation itself. Otherwise, such lines may be obtained by specifying any {it:{help line_options}}. In addition, if any {it:{help area_options}} are supplied then the box-shaped region between the confidence limit lines will be rendered as an area plot (drawn underneath other plot features such as indivdual study estimates). {phang2} {cmd:pointopts(}{it:{help marker_options}}{cmd:)} and {cmd:point}{it:#}{cmd:opts(}{it:{help marker_options}}{cmd:)} affect the rendition of (unweighted) point estimate markers, e.g. to clarify the precise point within a larger weighted box (see {opt boxopts()}). {phang2} {cmd:rfopts(}[{it:{help line_options}}] [{cmd:overlay}] [{cmd:rcap}] [{cmd:sepline}]{cmd:)} and {cmd:rf}{it:#}{cmd:opts(}[{it:{help line_options}}] [{cmd:overlay}] [{cmd:rcap}] [{cmd:sepline}]{cmd:)} affect the rendition of prediction interval lines as defined by {opt rfdist(varlist)}. The additional option {cmd:overlay} results in the prediction interval being plotted as a single line, continuing through the confidence interval and point estimate. (The default is for separate lines to be plotted either side of the confidence interval.) The additional option {cmd:rcap} requests capped spikes. The additional option {cmd:sepline} plots the prediction interval line separately, below the confidence interval rather than straddling it. {phang2} {cmd:rfcilineopts(}[{it:{help line_options}}] [{it:{help area_options}}] [{cmd:hide}]{cmd:)} and {cmd:rfciline}{it:#}{cmd:opts(}[{it:{help line_options}}] [{it:{help area_options}}] [{cmd:hide}]{cmd:)} affect the rendition of optional additional vertical lines representing the limits of the prediction interval. These options function in the same way as {cmd:ocilineopts()}. {pstd} If pooled estimates are not to be represented by diamonds, but rather by point estimates plus confidence intervals as for the individual estimates (albeit with different {it:plot_options}), this may be achieved by specifying the following options as replacements for {cmd:diamopts()} or {cmd:diam}{it:#}{cmd:opts()}: {pmore} {opt nodiamonds} simply replaces all diamonds with point estimates and confidence intervals, with default {it:{help line_options}} {pmore} {cmd:pciopts(}{it:{help line_options}}{cmd:)} and {cmd:pci}{it:#}{cmd:opts(}{it:{help line_options}}{cmd:)} affect the rendition of confidence intervals for pooled estimates {pmore} {cmd:ppointopts(}{it:{help marker_options}}{cmd:)} and {cmd:ppoint}{it:#}{cmd:opts(}{it:{help marker_options}}{cmd:)} affect the rendition of (unweighted) pooled estimate markers. {pmore} Note that, if pooled estimates are not represented by diamonds, then the default prediction interval line may become indistinguishable from the confidence interval line. In this case, the lines may be distinguished via appropriate {help twoway} options (e.g. colours); or the option {cmd:sepline} could be used. {marker saved_results}{...} {title:Saved results} {pstd} {cmd:forestplot} saves the following in {cmd:r()} to assist with fine-tuning: {synoptset 25 tabbed}{...} {p2col 5 25 29 2: Scalars}{p_end} {synopt:{cmd:r(aspect)}}aspect ratio of plot region (see {it:{help aspect_option}}){p_end} {synopt:{cmd:r(astext)}}proportion of plot width taken up by columns of text{p_end} {synopt:{cmd:r(ldw)}}display width of left-hand columns of text{p_end} {synopt:{cmd:r(rdw)}}display width of right-hand columns of text{p_end} {synopt:{cmd:r(cdw)}}display width of the central part, where the data is plotted{p_end} {synopt:{cmd:r(height)}}approximate total number of lines of text, including titles, footnotes etc.{p_end} {synopt:{cmd:r(spacing)}}spacing of lines of text (see {cmd:spacing()} option){p_end} {synopt:{cmd:r(ysize)}}relative height of graph region (see {it:{help region_options}}){p_end} {synopt:{cmd:r(xsize)}}relative width of graph region (see {it:{help region_options}}){p_end} {synopt:{cmd:r(textsize)}}calculated optimum text size ({ul:before} applying user-specified scaling with {opt textsize(#)}){p_end} {synopt:{cmd:r(range)}}{it:numlist} containing the {it:x}-axis limits of the plotted data{p_end} {synopt:{cmd:r(obs)}}number of observations in the final plot (i.e. after generating column titles etc.){p_end} {pstd} In addition, by default {cmd:forestplot} leaves behind a variable named {bf:_EFFECT} containing the string-valued concatenation of the (formatted) effect size and confidence limits appearing on the forest plot to the right of the plotted data. Access to this variable allows, for example, pooled-effect {it:p}-values to be manually added to the forest plot; see the penultimate example. {marker diffs_metan}{...} {title:Note: Differences from previous versions of {cmd:metan}} {pstd} This version of {cmd:forestplot} has been designed to be backwards-compatible with {bf:{help metan9}} as far as possible. However, there are some minor differences in syntax and behaviour. In particular: {phang2} The procedure for creating the plot has been improved, so that the use of options such as {opt xsize(#)}, {opt ysize(#)} and {opt textsize(#)} should be needed less often. Similarly, automated {it:x}-axis labelling is improved, so that {opt xlabel()} may not be needed. {phang2} Options {opt xlabel()} and {opt xtick()} now expect a standard Stata {help numlist}, with {opt force} as a sub-option. The older syntax using comma-separated lists, with {opt force} as a stand-alone option, continues to be supported; but a message will be printed to the Results Window as a reminder that the documented syntax has changed. {phang2} If the {cmd:metan} option {opt counts} is used, the resulting columns will appear on the left-hand side of the plot, between the study label and the plotted data, instead of on the right-hand side as in {cmd:metan9}. This matches with the layout used by other popular meta-analysis packages such as {help forestplot##refs:Cochrane's Review Manager}. {phang2} Variable {help format}s are honoured by {cmd:forestplot} wherever possible. Therefore, the contents of {opt lcols()} and {opt rcols()} will appear right-justified by default, which may cause some differences in display when compared to {bf:{help metan9}}. To control this, individual variables, whether numeric or string, may be {help format}ted within the dataset before running {cmd:forestplot}. Alternatively, {opt leftjustify} will left-justify all data columns. {phang3} (Note that {bf:{help metan}} automatically left-justifies "core" variables, such as the left-most "study name" column and the effect sizes.) {marker examples}{...} {title:Examples} {pstd} We will use the same example dataset as for {bf:{help metan}}. The dataset contains variables containing the odds ratio and 95% confidence limits, but {cmd:forestplot} is designed to work on the interval (e.g. log OR) scale. So we take need to take logs of these variables before proceeding further: {cmd}{...} {* example_start - forestplot_ex1}{...} {phang2} . use http://fmwww.bc.edu/repec/bocode/m/metan_example_data, clear{p_end} {phang2} . gen logOR = log(OR){p_end} {phang2} . gen logORlci = log(ORlci){p_end} {phang2} . gen logORuci = log(ORuci){p_end} {* example_end}{...} {txt}{...} {pmore} {it:({stata metan_hlp_run forestplot_ex1 using forestplot.sthlp, restnot:click to run})}{p_end} {pstd} First, see what happens when {cmd:forestplot} is run with no options at all: {cmd}{...} {* example_start - forestplot_ex2}{...} {phang2} . forestplot logOR logORlci logORuci{p_end} {* example_end}{...} {txt}{...} {pmore} {it:({stata metan_hlp_run forestplot_ex2 using forestplot.sthlp, restpres:click to run})}{p_end} {pstd} With a little more work, we can recreate the result of running {cmd:metan} with the {opt nooverall} option: {cmd}{...} {* example_start - forestplot_ex3a}{...} {phang2} . gen wgt = (2*1.96/(logORuci - logORlci))^2{p_end} {phang2} . summ wgt, meanonly{p_end} {phang2} . replace wgt = 100 * wgt / r(sum){p_end} {phang2} . label variable wgt "% Weight"{p_end} {phang2} . format wgt %6.2f{p_end} {phang2} . format id %-14s{p_end} {phang2} . forestplot logOR logORlci logORuci, eform effect(Odds ratio) labels(id) wgt(wgt){p_end} {* example_end}{...} {txt}{...} {pmore} {it:({stata metan_hlp_run forestplot_ex3a using forestplot.sthlp, restpresnot:click to run})}{p_end} {pstd} Compare with using {cmd:metan} directly: the result is exactly the same. The extra work needed demonstrates how few assumptions {cmd:forestplot} makes about the data, and therefore how flexible it is. {cmd}{...} {* example_start - forestplot_ex3b}{...} {phang2} . metan logOR logORlci logORuci, eform effect(Odds ratio) lcols(id) rcols(wgt) nooverall{p_end} {* example_end}{...} {txt}{...} {pmore} {it:({stata metan_hlp_run forestplot_ex3b using forestplot.sthlp, restpresnot:click to run})}{p_end} {pstd} Use of {opt plotid()} and {it:plot#}{cmd:opts()}, and also {opt favours()}: {cmd}{...} {* example_start - forestplot_ex4}{...} {phang2} . forestplot, eform effect(Odds ratio) labels(id) plotid(type_study){* ///}{p_end} {p 16 20 2} favours(Favours treatment # Favours control){* ///}{p_end} {p 16 20 2} box1opts(mcolor(red)) ci1opts(lcolor(red) rcap) box2opts(mcolor(blue)) ci2opts(lcolor(blue)){p_end} {* example_end}{...} {txt}{...} {pmore} {it:({stata metan_hlp_run forestplot_ex4 using forestplot.sthlp, restpres:click to run})}{p_end} {pstd} Next, we will run a slightly different {bf:{help metan}} command, and use the option {opt clear} to replace the data in memory with a "forestplot results set". We then insert the p-value for the test of overall effect. Finally, we run {cmd:forestplot} with the {opt useopts} option, to recover the {opt counts} option previously specified to {cmd:metan}. We also request a "filled" diamond, and demonstrate the use of the {opt cirange()} and {opt range()} options. {pstd} (Note that we need to include {bf:_EFFECT} within {opt rcols()} to prevent {cmd:forestplot} over-writing our p-value; and that {bf:_WT} also needs to be included to maintain the default ordering of columns; see {help forestplot##description:Description}.) {cmd}{...} {* example_start - forestplot_ex5}{...} {phang2} . use http://fmwww.bc.edu/repec/bocode/m/metan_example_data, clear{p_end} {phang2} . metan tdeath tnodeath cdeath cnodeath, rd random rfdist lcols(id) counts nograph clear{p_end} {phang2} . replace _EFFECT = "p=0.261" if _USE==4{p_end} {phang2} . forestplot, useopts nostats nowt rcols(_EFFECT _WT) diamopt(fcolor("0 0 100")){* ///}{p_end} {p 16 20 2} xlabel(-.25 0 .25) cirange(-.35 .35) range(-.5 .5){p_end} {* example_end}{...} {txt}{...} {pmore} {it:({stata metan_hlp_run forestplot_ex5 using forestplot.sthlp, restnot:click to run})}{p_end} {pstd} We may also use line or area options to demonstrate the width of confidence and/or predictive intervals compared to the individual study data. The option {opt hide} is used to suppress the pooled-effect diamond, as it is now redundant: {cmd}{...} {* example_start - forestplot_ex5a}{...} {phang2} . forestplot, useopts ocilineopts(color(gs8) hide) rfcilineopts(color(gs12)) classic{p_end} {* example_end}{...} {txt}{...} {pmore} {it:({stata metan_hlp_run forestplot_ex5a using forestplot.sthlp, restpresnot:click to run})}{p_end} {pstd} Finally, as a more advanced example, we will recreate Figure 2 of {help metan##refs:Fisher et al (2017)}, which demonstrates a novel form of forest plot designed to facilitate the presentation of treatment-covariate interactions. It involves creating two related but different plots, and presenting them side-by-side such that their pertinent features align. The original data were presented in Analysis 8.2 of a Cochran review by {help metan##refs:Fearon et al (2012)}. {cmd}{...} {* example_start - forestplot_ex6a}{...} {phang2} . use http://fmwww.bc.edu/repec/bocode/f/forestplot_fisher2017, clear{p_end} {phang2} {phang2} // Create the "results set" for the left-hand sub-plot{p_end} {phang2} . metan n1 mean1 sd1 n0 mean0 sd0, wmd by(trial) lcols(carer){* ///}{p_end} {p 16 20 2} nooverall nosubgroup nograph saving(fig2a){p_end} {phang2} {phang2} // Create the "results set" for the right-hand sub-plot{p_end} {phang2} // (using built-in {help statsby:{bf:statsby}}, but note that {help ipdmetan:{bf:ipdmetan}} could also be used{p_end} {phang2} // and would pool the coefficients at the same time (see later)){p_end} {phang2} . statsby _b[carer] _se[carer], by(trial) saving(fig2b) : vwls _ES carer, sd(_seES){p_end} {* example_end}{...} {txt}{...} {pmore} {it:({stata metan_hlp_run forestplot_ex6a using forestplot.sthlp:click to run})}{p_end} {pmore} Left-hand sub-plot: {cmd}{...} {* example_start - forestplot_ex6b}{...} {phang2} // Create an extra observation for the missing category of the Montreal trial{p_end} {phang2} . use fig2a, clear{p_end} {phang2} . expand 2 if _BY=="Montreal 2000":_BY & _USE==1{p_end} {phang2} . replace _LABELS = "No carer" in L{p_end} {phang2} . replace _USE = 2 in L{p_end} {phang2} . sort _BY _USE _STUDY{p_end} {phang2} {phang2} // Create three more dummy obs at the end, to line up with the "overall" part of the right-hand side{p_end} {phang2} . local oldN = _N{p_end} {phang2} . local oldN_3 = `oldN' + 3{p_end} {phang2} . set obs `oldN_3'{p_end} {phang2} . replace _USE = 6 if _n > `oldN'{p_end} {phang2} . forestplot, wmd keepall nostats nowt{* ///}{p_end} {p 16 20 2} favours("Favours" "ESD" " " # "Favours" "no ESD" " "){* ///}{p_end} {p 16 20 2} xlabel(-50 0 50, force) astext(35) savedims(A) name(fig2a){p_end} {* example_end}{...} {txt}{...} {pmore} {it:({stata metan_hlp_run forestplot_ex6b using forestplot.sthlp, restpres:click to run})}{p_end} {pmore} Right-hand sub-plot: {cmd}{...} {* example_start - forestplot_ex6c}{...} {phang2} // Load the "results set" into memory, and pool the interaction coefficients{p_end} {phang2} . use fig2b, clear{p_end} {phang2} . metan _stat_1 _stat_2, lcols(trial) effect(Diff. in mean diffs.){* ///}{p_end} {p 16 20 2} keepall keeporder nograph clear{p_end} {phang2} {phang2} // To make the two subplots line up, need to generate 2 new observations per trial, plus 1 for overall{p_end} {phang2} // before creating, and saving, the right-hand sub-plot{p_end} {phang2} . gen toexpand = 1 + 3*inlist(_USE, 1, 2) + 2*(_USE==5){p_end} {phang2} . local oldN = _N{p_end} {phang2} . expand toexpand, gen(expand){p_end} {phang2} . replace _USE = 6 * (1 - (_n > `oldN' & !mod(_n, 3))) if expand{p_end} {phang2} . replace _WT = . if _USE==0{p_end} {phang2} . sort _STUDY _USE{p_end} {phang2} . forestplot, useopts interaction usedims(A) nonames{* ///}{p_end} {p 16 20 2} favours("Favours greater effect" "of ESD with" "carer present"{* ///}{p_end} {p 16 20 2} # "Favours greater effect" "of ESD with" "no carer present", fp(40)){* ///}{p_end} {p 16 20 2} xlabel(-50 0 50, force) name(fig2b){p_end} {* example_end}{...} {txt}{...} {pmore} {it:({stata metan_hlp_run forestplot_ex6c using forestplot.sthlp, restpres:click to run})}{p_end} {pmore} Finally, show both sub-plots side-by-side: {cmd}{...} {* example_start - forestplot_ex6d}{...} {phang2} . graph combine fig2a fig2b, imargin(zero) xsize(4){p_end} {* example_end}{...} {txt}{...} {pmore} {it:({stata metan_hlp_run forestplot_ex6d using forestplot.sthlp, restpres:click to run})}{p_end} {title:Author} {p} David Fisher, MRC Clinical Trials Unit at UCL, London, UK. Email {browse "mailto:d.fisher@ucl.ac.uk":d.fisher@ucl.ac.uk} {title:Acknowledgments} {pstd} Thanks to the authors of {bf:{help metan9}}, upon which this code is based; particularly Ross Harris for his comments and good wishes. Also thanks to Vince Wiggins at Statacorp for advice, and to Daniel Klein (Universit{c a:}t Kassel, Germany) for assistance with testing under older Stata versions. {pstd} The "click to run" element of the examples in this document is handled using an idea originally developed by Robert Picard. {marker refs}{...} {title:References} {phang} Fisher DJ. 2015. Two-stage individual participant data meta-analysis and generalized forest plots. Stata Journal 15: 369-396 {phang} Fisher DJ, Carpenter JR, Morris TP, Freeman SC, Tierney JF. 2017. Meta-analytical methods to identify who benefits most from treatments: daft, deluded, or deft approach? BMJ 356: j573. doi: 10.1136/bmj.j573 {phang} Fearon P, Langhorne P. Early Supported Discharge Trialists. 2012. Services for reducing duration of hospital care for acute stroke patients. Cochrane Database Syst Rev 9: CD000443 {phang} Review Manager (RevMan) [Computer program]. Version 5.4, The Cochrane Collaboration, 2020.