funnelinf: Visual funnel plot inference for meta-analysis
In metaviz: Forest Plots, Funnel Plots, and Visual Funnel Plot Inference for Meta-Analysis

Description Usage Arguments Details Value Author(s) References Examples

Creates a lineup of funnel plots to conduct visual funnel plot inference (Kossmeier, Tran, & Voracek, 2019). The funnel plot showing the actually supplied data is presented alongside null plots showing simulated data under the null hypothesis.

funnelinf(
  x,
  group = NULL,
  group_permut = FALSE,
  n = 20,
  null_model = "REM",
  y_axis = "se",
  contours = TRUE,
  sig_contours = TRUE,
  contours_col = "Blues",
  trim_and_fill = FALSE,
  trim_and_fill_side = "left",
  egger = FALSE,
  show_solution = FALSE,
  rorschach = FALSE,
  point_size = 1.5,
  text_size = 3,
  xlab = "Effect",
  ylab = NULL,
  x_trans_function = NULL,
  x_breaks = NULL
)

`x`	data.frame or matrix with the effect sizes of all studies (e.g., correlations, log odds ratios, or Cohen d) in the first column and their respective standard errors in the second column. Alternatively, x can be the output object of function `rma.uni` from package metafor; then effect sizes and standard errors are extracted from `x`.
`group`	factor indicating the subgroup of each study to show in the funnel plot. Has to be in the same order than `x`.
`group_permut`	logical scalar indicating if subgroup membership should be permuted in the null plots. Ignored if no group is supplied.
`n`	integer specifying the absolute number of plots in the lineup.
`null_model`	character string indicating which meta-analytic model should be used to simulate the effect sizes for the null plots. Available options are "FEM" for the fixed effect model and "REM" (default) for the random-effects model (using the DerSimonian-Laird method to estimate the between-study variance tau squared).
`y_axis`	character string indicating which y axis should be used in the funnel plot. Available options are "se" (default) for standard error and "precision" for the reciprocal of the standard error.
`contours`	logical scalar indicating if classic funnel plot confidence contours and the summary effect should be displayed (i.e., summary effect +/- qnorm(0.975) * SE).
`sig_contours`	logical scalar. Should significance contours be drawn? Significance contours show which combination of effect size and standard error lead to study p-values smaller than 0.05 or 0.01 (using a Wald test).
`contours_col`	character string indicating the color palette used from package RColorBrewer for `sig_contours`. Can be any of "Blues", "Greys", "Oranges", "Greens", "Reds", and "Purples".
`trim_and_fill`	logical scalar. Should studies imputed by the trim and fill method be displayed? Also shows the adjusted summary effect if `contours` is `TRUE` as well.
`trim_and_fill_side`	character string indicating on which side of the funnel plot studies should be imputed by the trim and fill method (i.e., on which side studies are presumably missing due to publication bias). Must be either "right" or "left" (default).
`egger`	logical scalar. Should Egger's regression line be drawn? Only available if `y_axis` is `"se"`.
`show_solution`	logical scalar. Should the real-data plot be highlighted?
`rorschach`	logical scalar. Should the lineup only consist of null plots?
`point_size`	numeric value. Size of the study points in the funnel plots.
`text_size`	numeric value. Size of text in the lineup.
`xlab`	character string specifying the label of the x axis.
`ylab`	character string specifying the label of the y axis.
`x_trans_function`	function to transform the labels of the x axis. Common uses are to transform log-odds-ratios or log-risk-ratios with `exp` to their original scale (odds ratios and risk ratios), or Fisher's z values back to correlation coefficients using `tanh`.
`x_breaks`	numeric vector of values for the breaks on the x-axis. When used in tandem with `x_trans_function` the supplied values should be not yet transformed.

Funnel plots are widely used in meta-analysis to assess small study effects as potential indicator for publication bias. However, interpretations of funnel plots often lead to false conclusions about the presence and severity of bias (e.g., Terrin, Schmid, and Lau, 2005). Visual inference (Buja et al. 2009; Majumder, Hofmann, and Cook 2013) can help to improve the validity of conclusions based on the visual inspection of a funnel plot by saving investigators from interpreting funnel-plot patterns which might be perfectly plausible by chance. Only if the real-data funnel plot is distinguishable from null-plots, the null hypothesis is formally rejected and conclusions based on the visual inspection of the real-data funnel plot might be warranted (for further details, see Kossmeier, Tran, & Voracek, 2019).

Function funnelinf utilizes package nullabor for null plot simulation and ggplot2 for plotting the lineup. Several tailored features for visual inference with funnel plots are provided which currently include:

options for null-plot simulation under both FEM and REM meta-analysis (see below).
subgroup analysis.
graphical options specific to the funnel plot (significance and confidence contours, and choice of the ordinate).
additional options to display various statistical information (Egger's regression line, and imputed studies by, as well as the adjusted summary effect from, the trim-and-fill method).

Null plots are simulated assuming normally distributed effect sizes with expected value equal to the observed summary effect and variance either equal to the observed study variances (null_model = "FEM") or the sum of the observed study variances and the estimated between study variance tau squared (null_model = "REM").

A lineup of n (20 by default) funnel plots; one showing the real data and n-1 showing simulated data under the null hypothesis

Michael Kossmeier* <michael.kossmeier@univie.ac.at>

Ulrich S. Tran* <ulrich.tran@univie.ac.at>

Martin Voracek* <martin.voracek@univie.ac.at>

*Department of Basic Psychological Research and Research Methods, School of Psychology, University of Vienna

Buja, A., Cook, D., Hofmann, H., Lawrence, M., Lee, E. K., Swayne, D. F., & Wickham, H. (2009). Statistical inference for exploratory data analysis and model diagnostics. Philosophical Transactions of the Royal Society of London A: Mathematical, Physical and Engineering Sciences, 367, 4361-4383.

Kossmeier, M., Tran, U. & Voracek, M. (2019) Visual inference for the funnel plot in meta-analysis. Zeitschrift für Psychologie - Journal of Psychology, 227.

Majumder, M., Hofmann, H., & Cook, D. (2013). Validation of visual statistical inference, applied to linear models. Journal of the American Statistical Association, 108, 942-956.

Terrin, N., Schmid, C. H., & Lau, J. (2005). In an empirical evaluation of the funnel plot, researchers could not visually identify publication bias. Journal of clinical epidemiology, 58, 894-901.

## Not run: 
# Plotting a funnel plot lineup with the exrehab data to conduct visual funnel plot inference
funnelinf(x = exrehab[, c("logrr", "logrr_se")])

# Plotting a funnel plot lineup with the mozart data to conduct visual funnel plot inference
# considering subgroups
funnelinf(x = mozart[, c("d", "se")],
group = mozart[, "rr_lab"],
group_permut = TRUE, null_model = "REM")

# Plotting a funnel plot lineup with the brainvolume data to conduct visual funnel plot inference
# considering heterogeneity by using the fixed effect model for null plot simulation
funnelinf(x = brainvol[, c("z", "z_se")],
null_model = "FEM")

## End(Not run)

To see the solution run nullabor::decrypt("Jzis NZoZ qA mKgqoqKA lf")
To see the solution run nullabor::decrypt("Jzis NZoZ qA mKgqoqKA hT")
To see the solution run nullabor::decrypt("Jzis NZoZ qA mKgqoqKA 2b")