meta (version 9.0-0)

meta-formatting: 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")

if (FALSE) {
# 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")
}