meta-formatting: Formatting arguments for printouts and forest plots

meta-formattingR Documentation

Formatting arguments for printouts and forest plots

Description

Formatting arguments for printouts and forest plots.

Details

Formatting arguments for printouts can be provided in the following named lists, with availability shown below:

print, digits.

Furthermore, formatting arguments for forest plots can be provided in the following named lists:

test, label, rob, fs, ff, just, fill, col, print, type, pooled, text, lty, lwd, digits, calcwidth, colgap, cid, addrow.

List elements available in these named lists are described in the following subsections.

The corresponding individual arguments are also supported. Their names are formed by combining the list name and element name, such as fs.main or col.diamond. Supplying the same setting both as a list element and as an individual argument is an error, even if the values agree.

In forest.meta, the primary value can also be supplied directly without wrapping it in a named list for addrow, cid, colgap, digits, fill, just, and lwd. The rob argument also accepts a risk-of-bias assessment directly.

In forest.metacum or forest.metainf, the primary value can also be supplied directly without wrapping it in a named list for col and digits. A scalar digits in print methods sets digits$digits, except in print.cidprop, where it sets digits$cid.

Most individual arguments can also be set globally through settings.meta. The corresponding defaults are then used by the named lists.

Function keys in the tables:

M

forest.meta.

B

forest.metabind.

C

forest.metacum and forest.metainf.

P

print.metabind.

N

print.meta and print.summary.meta.

S

print.summary.meta only.

R

print.metacum and print.metainf.

D

print.cidprop.

L

print.blup.meta; also print.estimates.blup.meta for digits.

A star, as in B* or C*, denotes forwarding through ... to forest.meta. Unmarked keys indicate direct processing; C uses the same implementation for both methods.

Availability does not imply that every setting affects every plot: forwarded arguments remain subject to the wrapper's documented restrictions and the results displayed. In particular, C supplies study symbols and disables overall-effect tests; B does not provide tests between input meta-analyses and fixes pooled.totals = FALSE.

Each subsection first describes elements and availability, then gives one table of general defaults. For elements supported by M, native forest.meta defines the baseline; other elements have the general defaults shown. Individual function documentation describes exceptions. Named-list and individual arguments use the same defaults.

gs("name") denotes the current setting from settings.meta, x the object supplied, and other names the corresponding function arguments. Defaults depending on the object, layout, or displayed results are indicated as such; NULL can request automatic selection rather than suppress output. In default tables, * stands for the element name in a setting or object field. CI denotes a confidence interval; CID denotes a clinically important difference.

Tests (test.*)

Logical values control whether the corresponding tests are printed.

Element Description Functions
overall Overall effects M, B
overall.common Common effect model M, B
overall.random Random effects model M, B
subgroup Subgroup differences M, B, C*, N
subgroup.common Common-effect differences M, B, C*, N
subgroup.random Random-effects differences M, B, C*, N
effect.subgroup Effects within subgroups M, B, C*
effect.subgroup.common Common subgroup effects M, B, C*
effect.subgroup.random Random subgroup effects M, B, C*
Element General default
overall Automatic (see below)
overall.common Automatic (see below)
overall.random Automatic (see below)
subgroup Automatic (see below)
subgroup.common Automatic (see below)
subgroup.random Automatic (see below)
effect.subgroup gs("test.effect.subgroup")
effect.subgroup.common NULL (automatic)
effect.subgroup.random NULL (automatic)

The overall-test default is gs("test.overall"); if NULL, it is TRUE for BMJ, RevMan5, JAMA, and meta (default) layouts, and FALSE otherwise. Model-specific defaults also depend on common, random, and overall. Subgroup tests default to x$test.subgroup, or TRUE if NULL; model-specific defaults also depend on common and random. C fixes overall-effect tests to FALSE; do not supply these elements. In print.meta, test supports only subgroup, subgroup.common, and subgroup.random. These settings can also be passed through print.summary.meta.

Labels (label.*)

Labels identify groups, attached study-data columns, graph regions, column headings, and test results.

Element Description Functions
e Experimental group M, B, C*
c Control group M, B, C*
e.attach Attached experimental column M, B, C*
c.attach Attached control column M, B, C*
left, right Either side of null effect M, B, C*
n, events Sample sizes / events M, B, C*
mean, sd Mean / standard deviation M, B, C*
cor Correlation M, B, C*
time, pval Time / p-value M, B, C*
tau2, tau, I2 Heterogeneity M, B, C*
cluster Cluster variable M, B, C*
cycles Cycle count M, B, C*
test.overall.common Overall common-effect test M, B, C*
test.overall.random Overall random-effects test M, B, C*
test.subgroup.common Common subgroup test M, B, C*
test.subgroup.random Random subgroup test M, B, C*
test.effect.subgroup.common Common subgroup-effect test M, B, C*
test.effect.subgroup.random Random subgroup-effect test M, B, C*
Element General default
e, c Corresponding x$label.* value
left, right Corresponding x$label.* value
e.attach, c.attach Corresponding gs("label.*") setting
n, events Corresponding gs("label.*") setting
mean, sd Corresponding gs("label.*") setting
cor, time Corresponding gs("label.*") setting
pval, tau2 Corresponding gs("label.*") setting
tau, I2 Corresponding gs("label.*") setting
cluster, cycles Corresponding gs("label.*") setting
All test.* elements NULL (test-specific labels)

Risk-of-bias settings (rob.*)

In forest.meta, settings for risk-of-bias assessments can be supplied in the named list rob.

Element Description Functions
rob Risk-of-bias assessment M, B*, C*
text Table heading M, B*, C*
legend Domain legend M, B*, C*
only Risk of bias alone on right M, B*, C*
Element General default
rob x$rob
text "Risk of Bias"
legend TRUE
only FALSE

Font sizes (fs.*) and font faces (ff.*)

Numeric font sizes, in points. The corresponding elements can be supplied in the named list fs. Font faces accepted by gpar, such as "plain", "bold", and "italic". The corresponding elements can be supplied in the named list ff.

Both lists can contain the following elements:

Element Description Functions
main, heading Title / column headings M, B*, C*
common, random Pooled results M, B*, C*
predict Prediction intervals M, B*, C*
common.labels Common-effect labels M, B*, C*
random.labels Random-effects labels M, B*, C*
predict.labels Prediction-interval labels M, B*, C*
study Study results M, B*, C*
study.labels Study labels M, B*, C*
hetstat Heterogeneity statistics M, B*, C*
test.overall Overall-effect tests M, B*, C*
test.subgroup Subgroup-difference tests M, B*, C*
test.effect.subgroup Subgroup-effect tests M, B*, C*
addline Additional lines M, B*, C*
axis Axis text M, B*, C*
smlab Summary measure M, B*, C*
xlab x-axis label M, B*, C*
lr Left / right labels M, B*, C*
rob Risk-of-bias text M, B*, C*
rob.symbols Risk-of-bias symbols M, B*, C*
details Method details M, B*, C*
Element Size default (fs) Face default (ff)
heading fontsize "bold"
study, study.labels fontsize "plain"
smlab, xlab fontsize Corresponding gs("ff.*") setting
lr fontsize gs("ff.lr")
axis fontsize - 1 gs("ff.axis")
details fontsize - 1 "plain"
rob gs("fs.rob") "plain"
rob.symbols gs("fs.rob.symbols") "bold"
Remaining elements gs("fs.*") gs("ff.*")

Justifications (just.*)

Possible values are "left", "right", and "center".

Element Description Functions
just Ordinary columns M, B*, C*
main Main title M, B*, C*
studlab Study labels M, B*, C*
addcols Additional columns M, B*
addcols.left Left additional columns M, B*, C*
addcols.right Right additional columns M, B*, C*
label.e, label.c Group headings M, B*, C*
rob Risk-of-bias columns M, B*, C*
Element General default
just "left" for JAMA, otherwise "right"
label.e, label.c "left" for JAMA, otherwise "right"
main, studlab Corresponding gs("just.*") setting
addcols gs("just.addcols")
addcols.left, addcols.right gs("just.addcols")
rob "left"

C fixes just.addcols = "right"; do not supply just$addcols.

Fill settings (fill.*)

Colours used to fill plot regions and symbols.

Element Description Functions
fill General fill M, B*, C*
cid CID regions M, B*, C*
cid.below.null CID below null effect M, B*, C*
cid.above.null CID above null effect M, B*, C*
equi Between equivalence limits M, B*, C*
lower.equi Lower limit to null effect M, B*, C*
upper.equi Null effect to upper limit M, B*, C*
Element General default
fill gs("fill")
cid, cid.below.null gs("fill.cid")
cid.above.null rev(gs("fill.cid"))
equi, lower.equi gs("fill.equi")
upper.equi rev(gs("fill.equi"))

Colours (col.*)

Colour values used for plot elements. Vectors can be supplied when colours differ between subgroups or rows.

Element Description Functions
main Main title M, B*
common Common effect M, B*
random Random effects M, B*
cid Decision lines M, B*
label Axis labels M, B*
label.left, label.right Left / right labels M, B*
study, study.text Study text M, B*
square, square.lines Square fill / border M, B
circle, circle.lines Circle fill / border M, B
inside Inside study symbols M, B*
inside.common Inside common symbols M, B*
inside.random Inside random symbols M, B*
diamond Diamond fill M, B
diamond.common Common diamond fill M, B
diamond.random Random diamond fill M, B
diamond.common.subgroup Common subgroup fill M, B*
diamond.random.subgroup Random subgroup fill M, B*
diamond.lines Diamond border M, B
diamond.lines.common Common diamond border M, B
diamond.lines.random Random diamond border M, B
diamond.lines.common.subgroup Common subgroup border M, B*
diamond.lines.random.subgroup Random subgroup border M, B*
predict Prediction-interval fill M, B
predict.lines Prediction-interval border M, B
predict.subgroup Subgroup prediction fill M, B*
predict.lines.subgroup Subgroup prediction border M, B*
subgroup Subgroup text M, B*
lines, header.line Plot / header lines M, B*
jama.line JAMA lines M, B*
col Square results C
bg Symbol fill C
border Symbol border C
bg.predict Prediction-interval fill C
border.predict Prediction-interval border C
Element General default
main, common Corresponding gs("col.*") setting
random, cid Corresponding gs("col.*") setting
label, study Corresponding gs("col.*") setting
study.text, square Corresponding gs("col.*") setting
square.lines, circle Corresponding gs("col.*") setting
circle.lines gs("col.circle")
inside gs("col.inside")
inside.common, inside.random gs("col.inside")
diamond, diamond.common gs("col.diamond")
diamond.random gs("col.diamond")
diamond.common.subgroup gs("col.diamond")
diamond.random.subgroup gs("col.diamond")
diamond.lines gs("col.diamond.lines")
diamond.lines.common gs("col.diamond.lines")
diamond.lines.random gs("col.diamond.lines")
diamond.lines.common.subgroup gs("col.diamond.lines")
diamond.lines.random.subgroup gs("col.diamond.lines")
predict, predict.subgroup gs("col.predict")
predict.lines, predict.lines.subgroup gs("col.predict.lines")
subgroup, jama.line gs("col.subgroup")
lines, header.line gs("col.lines")
label.left x$col.label.left
label.right x$col.label.right
col, bg NULL
border NULL
bg.predict, border.predict NULL

B processes its own colour elements and forwards other native elements; C uses only its alternative elements.

Printing results (print.*)

Logical settings controlling displayed results, columns, and labels.

Element Description Functions
I2, I2.ci I-squared / CI M, B, C, P, N, R
tau2 Tau-squared M, B, C, P, N, R, L
tau2.ci Tau-squared CI M, B, C, P, N, R
tau Tau M, B, C, P, N, R, L
tau.ci Tau CI M, B, C, P, N, R
Q Heterogeneity statistic Q M, B, C, P, N
pval.Q Heterogeneity p-value M, B, C, P
Rb Rb statistic M, N
Rb.ci Rb CI M
stat Effect z- or t-statistic M, B, C, P, R
pval Effect p-value B, C, P
Q.subgroup Subgroup-difference Q M
tau2.ci.subgroup Subgroup tau-squared CI M
tau.ci.subgroup Subgroup tau CI M
subgroup.labels Subgroup labels M
subgroup.name Subgroup variable name M, B, P, N
CMH Cochran-Mantel-Haenszel test N
prob CID benefit / harm probability C, R
studlab Meta-analysis labels B
type Result type B
func Analysis function B, P
method Pooling method B, P
method.interval Interval method B, P
method.tau Tau-squared method B
backtransf Back-transformation function B, P
args.backtransf Back-transformation arguments B, P
k Number of studies B, P
sm Summary measure B, P
se Standard error B, P
level.ma Pooled-effect CI level B, P
level.predict Prediction level B, P
level.hetstat Heterogeneity CI level B, P
null.effect Null effect B, P
H H statistic B, P, N
H.ci H CI B, P
Q.b Subgroup-test statistic B, P
pval.Q.b Subgroup-test p-value B, P
Element General default
I2, I2.ci Corresponding gs("forest.*") setting
tau2, tau2.ci Corresponding gs("forest.*") setting
tau, tau.ci Corresponding gs("forest.*") setting
Q, pval.Q Corresponding gs("forest.*") setting
Rb, Rb.ci Corresponding gs("forest.*") setting
stat, Q.subgroup Corresponding gs("forest.*") setting
tau2.ci.subgroup gs("print.tau2.ci.subgroup")
tau.ci.subgroup gs("print.tau.ci.subgroup")
subgroup.labels TRUE
subgroup.name x$print.subgroup.name
CMH x$print.CMH
studlab, k TRUE
pval TRUE
se, null.effect FALSE
H, H.ci FALSE
prob FALSE
type, func NULL (automatic)
method, method.interval NULL (automatic)
method.tau, backtransf NULL (automatic)
args.backtransf, sm NULL (automatic)
level.ma, level.predict NULL (automatic)
level.hetstat NULL (automatic)
Q.b, pval.Q.b NULL (automatic)

Confidence-interval switches require the corresponding statistic. B and C use their own print lists; native-only elements are not a shared wrapper interface. Q.b and pval.Q.b refer to subgroup differences within each meta-analysis. In P, pval.Q.b controls the whole subgroup-test block, including the statistic and degrees of freedom; Q.b has no separate effect.

Graphical-type (type.*)

Character strings specifying how treatment effects and confidence intervals are plotted, such as "square", "diamond", or "circle".

Element Description Functions
study Individual study results M
common Overall common-effect results M, B
random Overall random-effects results M, B
type General result symbol B
predict Prediction-interval symbol B
subgroup Subgroup results M
subgroup.common Common-effect subgroup results M
subgroup.random Random-effects subgroup results M
Element General default
study gs("type.study")
common, random gs("type.common") for both
subgroup Automatic (see below)
subgroup.common Automatic (see below)
subgroup.random Automatic (see below)
type, predict NULL (automatic)

Subgroup symbols default to "diamond" if study.results is TRUE, and "square" otherwise. C uses an ordinary character argument type, not a named list.

Pooled-results (pooled.*)

Element Description Functions
totals Sample sizes / totals M, C*
events Event counts M, B*, C*
times Person-time totals M, B*, C*
Element General default
totals common | random
events gs("pooled.events")
times gs("pooled.times")

B fixes pooled.totals = FALSE; do not supply pooled$totals.

Text settings (text.*)

Character strings used for labels and explanatory text.

Element Description Functions
common Common-effect label M, B, C*
random Random-effects label M, B, C*
w.common Common weight label M, B, C*
w.random Random weight label M, B, C*
predict Prediction-interval label M, B, C*
subgroup Subgroup label M, B, C*
common.w Common subgroup label M, B, C*
random.w Random subgroup label M, B, C*
predict.w Subgroup prediction label M, B, C*
subgroup.nohet No-heterogeneity text M, B, C*
addline1, addline2 Additional lines M, B, C*
Element General default
common, random Corresponding x$text.* value
w.common, w.random Corresponding x$text.* value
predict x$text.predict
common.w, random.w x$text.common, x$text.random
predict.w x$text.predict
subgroup NULL
addline1, addline2 NULL
subgroup.nohet gs("text.subgroup.nohet")

Line-type settings (lty.*)

Element Description Functions
common Common-effect lines M, B*, C*
random Random-effects lines M, B*, C*
cid CID lines M, B*, C*
Element General default
common, random Corresponding gs("lty.*") setting
cid gs("lty.cid")

Line-width settings (lwd.*)

Element Description Functions
lwd General line width M, B*, C*
square Square borders M, B*, C*
diamond Diamond borders M, B*, C*
Element General default
lwd gs("lwd")
square, diamond gs("lwd.square"), gs("lwd.diamond")

Digits (digits.*)

The values specify the minimum number of significant digits.

Element Description Functions
digits Treatment effects M, B, C, P, N, R, L
se Standard errors M, B, P, S, L
stat z- or t-statistics M, B, C, P, N, R
pval Effect p-values M, B, C, P, N, R
pval.Q Heterogeneity p-values M, B, P, N
Q Heterogeneity statistic Q M, B, P, N
df Degrees of freedom N
H H statistic N
tau2 Between-study variance M, B, C, P, N, R, L
tau Between-study SD M, B, C, P, N, R, L
I2 I-squared statistic M, B, C, P, N, R
weight Study weights M, B*, S
prop Proportions S
mean, sd Means / standard deviations M, B*
cor, time Correlations / follow-up M, B*
n, event Sample sizes / events M, B*
TE Additional treatment estimates M, B*
addcols Additional columns M, B*
addcols.left Left additional columns M, B*
addcols.right Right additional columns M, B*
cid CID limits C, R, D
percent Percentages C, R, D
Element General default
digits, cor gs("digits.forest")
time, addcols gs("digits.forest")
addcols.left, addcols.right gs("digits.forest")
se, stat Corresponding gs("digits.*") setting
pval, pval.Q Corresponding gs("digits.*") setting
Q, tau2 Corresponding gs("digits.*") setting
df, H Corresponding gs("digits.*") setting
tau, I2 Corresponding gs("digits.*") setting
weight, mean Corresponding gs("digits.*") setting
sd gs("digits.sd")
prop gs("digits.prop")
n, event 0
TE gs("digits.TE.forest")
cid gs("digits.cid")
percent 1

Width calculation (calcwidth.*)

Logical arguments controlling whether generated text is included when calculating column widths.

Element Description Functions
pooled Pooled results M, B*, C*
common Common-effect text M, B*, C*
random Random-effects text M, B*, C*
predict Prediction-interval text M, B*, C*
hetstat Heterogeneity statistics M, B*, C*
tests Overall / subgroup tests M, B*, C*
subgroup Subgroup labels M, B*, C*
addline Additional lines M, B*, C*
details Method details M, B*, C*
Element General default
pooled Automatic (see below)
common, random Automatic (see below)
predict, hetstat Corresponding gs("calcwidth.*") setting
tests, subgroup Corresponding gs("calcwidth.*") setting
addline, details Corresponding gs("calcwidth.*") setting

Width calculation for pooled, common, and random text is enabled when either common or random is TRUE and either overall is TRUE or subgroup is non-NULL.

Column-gaps (colgap.*)

Gaps can be specified as character strings or grid::unit objects.

Element Description Functions
colgap Between columns M, B*, C*
left, right Between left / right columns M, B*, C*
studlab After study labels M, B*, C*
forest Beside forest plot M, B*, C*
forest.left Before forest plot M, B*, C*
forest.right After forest plot M, B*, C*
rob Between risk-of-bias columns M, B*, C*
rob.overall Before overall risk of bias M, B*, C*
Element General default
colgap, left gs("colgap")
right, studlab gs("colgap")
forest gs("colgap.forest")
forest.left, forest.right gs("colgap.forest")
rob "1mm"
rob.overall "2mm"

Clinically important difference settings (cid.*)

Element Description Functions
cid CID / decision thresholds M, B*, C*
below.null Limits below null effect M, B*, C*
above.null Limits above null effect M, B*, C*
pooled.only Pooled estimates only M, B*, C*
Element General default
cid gs("cid")
below.null, above.null Corresponding gs("cid.*") setting
pooled.only gs("cid.pooled.only")

Additional-row settings (addrow.*)

Element Description Functions
addrow Empty row above studies M, B*, C*
overall Empty row above overall results M, B*, C*
subgroup Empty row between subgroups M, B*, C*
Element General default
addrow gs("addrow")
overall gs("addrow.overall")
subgroup gs("addrow.subgroups")

See Also

forest.meta, settings.meta, gpar

Examples

data(Olkin1995)
ma1 <- metabin(ev.exp, n.exp, ev.cont, n.cont,
  data = Olkin1995, subset = c(41, 47, 51, 59),
  sm = "RR", method = "I",
  studlab = paste(author, year))

# Use individual arguments label.left to col.label.right
#
forest(ma1, layout = "RevMan5", common = FALSE, prediction = TRUE,
  label.left = "Favours experimental", label.right = "Favours control",
  col.label.left = "green", col.label.right = "red",
  main = "Use individual arguments")

## Not run: 
# Same forest plot using named lists label and col
#
forest(ma1, layout = "RevMan5", common = FALSE, prediction = TRUE,
  label = list(left = "Favours experimental", right = "Favours control"),
  col = list(label.left = "green", label.right = "red"),
  main = "Use named lists 'label' and 'col'")

# Same forest plot with a mixture
#
forest(ma1, layout = "RevMan5", common = FALSE, prediction = TRUE,
  label.left = "Favours experimental",
  col = list(label.left = "green"),
  label = list(right = "Favours control"),
  col.label.right = "red",
  main = "Use mixture of individual arguments and named lists")

## End(Not run)

meta documentation built on Nov. 14, 2026, 5:09 p.m.