Title: | Forest Plots from Regression Models |
---|---|
Description: | Produces forest plots using 'ggplot2' from models produced by functions such as stats::lm(), stats::glm() and survival::coxph(). |
Authors: | Nick Kennedy <[email protected]> |
Maintainer: | Nick Kennedy <[email protected]> |
License: | GPL-2 |
Version: | 0.6.2 |
Built: | 2024-11-29 08:57:39 UTC |
Source: | CRAN |
Default panels for forest_model
default_forest_panels( model = NULL, factor_separate_line = FALSE, measure = NULL, trans_char = "I" )
default_forest_panels( model = NULL, factor_separate_line = FALSE, measure = NULL, trans_char = "I" )
model |
model object to guess label and determine defaults |
factor_separate_line |
changes defaults for widths of variable depending on whether factors have their name on separate line |
measure |
label for main forest plot |
trans_char |
character representation of transform for axes |
'list' ready to be passed to 'forest_model'
This function does not work as well as grDevices::axisTicks and so that should be used instead.
forest_breaks(limits, trans = I)
forest_breaks(limits, trans = I)
limits |
limits of plot |
trans |
transformation that will be used on the limits |
a vector with breaks ready to pass to panel_forest_plot
Produce a forest plot based on a regression model
forest_model( model, panels = default_forest_panels(model, factor_separate_line = factor_separate_line), covariates = NULL, exponentiate = NULL, funcs = NULL, factor_separate_line = FALSE, format_options = forest_model_format_options(), theme = theme_forest(), limits = NULL, breaks = NULL, return_data = FALSE, recalculate_width = TRUE, recalculate_height = TRUE, model_list = NULL, merge_models = FALSE, exclude_infinite_cis = TRUE )
forest_model( model, panels = default_forest_panels(model, factor_separate_line = factor_separate_line), covariates = NULL, exponentiate = NULL, funcs = NULL, factor_separate_line = FALSE, format_options = forest_model_format_options(), theme = theme_forest(), limits = NULL, breaks = NULL, return_data = FALSE, recalculate_width = TRUE, recalculate_height = TRUE, model_list = NULL, merge_models = FALSE, exclude_infinite_cis = TRUE )
model |
|
panels |
|
covariates |
a character vector optionally listing the variables to include in the plot (defaults to all variables) |
exponentiate |
whether the numbers on the x scale should be exponentiated for plotting |
funcs |
optional list of functions required for formatting |
factor_separate_line |
whether to show the factor variable name on a separate line |
format_options |
formatting options as a list as generated by |
theme |
theme to apply to the plot |
limits |
limits of the forest plot on the X-axis (taken as the range of the data by default) |
breaks |
breaks to appear on the X-axis (note these will be exponentiated
if |
return_data |
return the data to produce the plot as well as the plot itself |
recalculate_width |
|
recalculate_height |
|
model_list |
list of models to incorporate into a single forest plot |
merge_models |
if 'TRUE', merge all models in one section. |
exclude_infinite_cis |
whether to exclude points and confidence intervals
that go to positive or negative infinity from plotting. They will still be
displayed as text. Defaults to |
This function takes the model output from one of the common model functions in
R (e.g. lm
, glm
,
coxph
). If a label
attribute was present on any of the
columns in the original data (e.g. from the labelled
package),
this label is used in preference to the column name.
The panels
parameter is a list
of lists each of which have an element
width
and, optionally, item
, display
, display_na
,
heading
, hjust
and fontface
. item
can be "forest"
for the forest
plot (exactly one required) or "vline"
for a vertical line.
display
indicates which column to display as text. It can be a quoted variable name
or a formula. The column display can include the standard ones produced by
tidy
and in addition
variable
(the term in the model; for factors this is the bare variable without the level),
level
(the level of factors),
reference
(TRUE for the reference level of a factor). For coxph
models, there will also be n_events
for the number of events in the group with
that level of the factor and person_time
for the person-time in that group.
The function trans
is definded to be the
transformation between the coefficients and the scales (e.g. exp
). Other functions not
in base R can be provided as a list
with the parameter funcs
.
display_na
allows for an alternative display for NA terms within estimate
.
A ggplot ready for display or saving, or (with return_data == TRUE
,
a list
with the parameters to call panel_forest_plot
in the
element plot_data
and the ggplot itself in the element plot
)
library("survival") library("dplyr") pretty_lung <- lung %>% transmute(time, status, Age = age, Sex = factor(sex, labels = c("Male", "Female")), ECOG = factor(lung$ph.ecog), `Meal Cal` = meal.cal ) print(forest_model(coxph(Surv(time, status) ~ ., pretty_lung))) # Example with custom panels panels <- list( list(width = 0.03), list(width = 0.1, display = ~variable, fontface = "bold", heading = "Variable"), list(width = 0.1, display = ~level), list(width = 0.05, display = ~n, hjust = 1, heading = "N"), list(width = 0.05, display = ~n_events, width = 0.05, hjust = 1, heading = "Events"), list( width = 0.05, display = ~ replace(sprintf("%0.1f", person_time / 365.25), is.na(person_time), ""), heading = "Person-\nYears", hjust = 1 ), list(width = 0.03, item = "vline", hjust = 0.5), list( width = 0.55, item = "forest", hjust = 0.5, heading = "Hazard ratio", linetype = "dashed", line_x = 0 ), list(width = 0.03, item = "vline", hjust = 0.5), list(width = 0.12, display = ~ ifelse(reference, "Reference", sprintf( "%0.2f (%0.2f, %0.2f)", trans(estimate), trans(conf.low), trans(conf.high) )), display_na = NA), list( width = 0.05, display = ~ ifelse(reference, "", format.pval(p.value, digits = 1, eps = 0.001)), display_na = NA, hjust = 1, heading = "p" ), list(width = 0.03) ) forest_model(coxph(Surv(time, status) ~ ., pretty_lung), panels) data_for_lm <- tibble( x = rnorm(100, 4), y = rnorm(100, 3, 0.5), z = rnorm(100, 2, 2), outcome = 3 * x - 2 * y + 4 * z + rnorm(100, 0, 0.1) ) print(forest_model(lm(outcome ~ ., data_for_lm))) data_for_logistic <- data_for_lm %>% mutate( outcome = (0.5 * (x - 4) * (y - 3) * (z - 2) + rnorm(100, 0, 0.05)) > 0.5 ) print(forest_model(glm(outcome ~ ., binomial(), data_for_logistic)))
library("survival") library("dplyr") pretty_lung <- lung %>% transmute(time, status, Age = age, Sex = factor(sex, labels = c("Male", "Female")), ECOG = factor(lung$ph.ecog), `Meal Cal` = meal.cal ) print(forest_model(coxph(Surv(time, status) ~ ., pretty_lung))) # Example with custom panels panels <- list( list(width = 0.03), list(width = 0.1, display = ~variable, fontface = "bold", heading = "Variable"), list(width = 0.1, display = ~level), list(width = 0.05, display = ~n, hjust = 1, heading = "N"), list(width = 0.05, display = ~n_events, width = 0.05, hjust = 1, heading = "Events"), list( width = 0.05, display = ~ replace(sprintf("%0.1f", person_time / 365.25), is.na(person_time), ""), heading = "Person-\nYears", hjust = 1 ), list(width = 0.03, item = "vline", hjust = 0.5), list( width = 0.55, item = "forest", hjust = 0.5, heading = "Hazard ratio", linetype = "dashed", line_x = 0 ), list(width = 0.03, item = "vline", hjust = 0.5), list(width = 0.12, display = ~ ifelse(reference, "Reference", sprintf( "%0.2f (%0.2f, %0.2f)", trans(estimate), trans(conf.low), trans(conf.high) )), display_na = NA), list( width = 0.05, display = ~ ifelse(reference, "", format.pval(p.value, digits = 1, eps = 0.001)), display_na = NA, hjust = 1, heading = "p" ), list(width = 0.03) ) forest_model(coxph(Surv(time, status) ~ ., pretty_lung), panels) data_for_lm <- tibble( x = rnorm(100, 4), y = rnorm(100, 3, 0.5), z = rnorm(100, 2, 2), outcome = 3 * x - 2 * y + 4 * z + rnorm(100, 0, 0.1) ) print(forest_model(lm(outcome ~ ., data_for_lm))) data_for_logistic <- data_for_lm %>% mutate( outcome = (0.5 * (x - 4) * (y - 3) * (z - 2) + rnorm(100, 0, 0.05)) > 0.5 ) print(forest_model(glm(outcome ~ ., binomial(), data_for_logistic)))
forest_model
Create format options for forest_model
forest_model_format_options( colour = "black", color = NULL, shape = 15, text_size = 5, point_size = 5, banded = TRUE )
forest_model_format_options( colour = "black", color = NULL, shape = 15, text_size = 5, point_size = 5, banded = TRUE )
colour |
colour of the point estimate and error bars |
color |
alias for colour |
shape |
shape of the point estimate |
text_size |
text size in mm |
point_size |
point size |
banded |
whether to show light grey bands behind alternate rows |
list of format options
forest_model
Create definition of a panel for forest_model
forest_panel( width, item = c("", "forest", "vline"), display = NULL, display_na = NULL, hjust = NULL, heading = NULL, fontface = NULL, linetype = NULL, line_x = NULL, parse = NULL, width_group = NULL )
forest_panel( width, item = c("", "forest", "vline"), display = NULL, display_na = NULL, hjust = NULL, heading = NULL, fontface = NULL, linetype = NULL, line_x = NULL, parse = NULL, width_group = NULL )
width |
relative width of the panel |
item |
specification of which type of item to use; overridden if display is not missing |
display |
bare expression that specifies the variable or expresion to display |
display_na |
what to display if a value is |
hjust |
horizontal justification |
heading |
heading to be used (defaults to the variable name) |
fontface |
fontface to use |
linetype |
line type to use |
line_x |
position for dashed line in forest plot |
parse |
whether text should be parsed as expressions |
width_group |
grouping used when recalcualting widths of panels |
panel definition as a list
Generate panels for forest plots
forest_panels(..., margin = 0.03)
forest_panels(..., margin = 0.03)
... |
panels to variables in data |
margin |
margin to leave at left and right edges |
a panels list ready for forest_model
or forest_rma
Generate a forest plot from a meta-analysis
forest_rma( model, panels = NULL, study_labels = NULL, additional_data = NULL, point_size = NULL, model_label = NULL, show_individual_studies = TRUE, show_model = TRUE, show_stats = list(`I^2` = rlang::quo(sprintf("%0.1f%%", I2)), p = rlang::quo(format.pval(QEp, digits = 4, eps = 1e-04, scientific = 1))), trans = I, funcs = NULL, format_options = forest_model_format_options(), theme = theme_forest(), limits = NULL, breaks = NULL, return_data = FALSE, recalculate_width = TRUE, recalculate_height = TRUE )
forest_rma( model, panels = NULL, study_labels = NULL, additional_data = NULL, point_size = NULL, model_label = NULL, show_individual_studies = TRUE, show_model = TRUE, show_stats = list(`I^2` = rlang::quo(sprintf("%0.1f%%", I2)), p = rlang::quo(format.pval(QEp, digits = 4, eps = 1e-04, scientific = 1))), trans = I, funcs = NULL, format_options = forest_model_format_options(), theme = theme_forest(), limits = NULL, breaks = NULL, return_data = FALSE, recalculate_width = TRUE, recalculate_height = TRUE )
model |
a single |
panels |
|
study_labels |
a character vector of study labels or list of character vectors the same length as |
additional_data |
a |
point_size |
a numeric vector with the point sizes for the individual studies, or a single value used for all studies, or a list of numeric vectors if more than one model is to be plotted |
model_label |
a single model label or character vector of model labels the same length as |
show_individual_studies |
whether to show the individual studies (the default) or just the summary diamond |
show_model |
a logical value, if 'TRUE', show model result, otherwise only show forest plots for studies |
show_stats |
a |
trans |
an optional transform function used on the numeric data for plotting the axes |
funcs |
optional list of functions required for formatting |
format_options |
formatting options as a list as generated by |
theme |
theme to apply to the plot |
limits |
limits of the forest plot on the X-axis (taken as the range of the data by default) |
breaks |
breaks to appear on the X-axis (note these will be exponentiated
if |
return_data |
return the data to produce the plot as well as the plot itself |
recalculate_width |
|
recalculate_height |
|
This produces a forest plot using the rma
plot
if (require("metafor")) { data("dat.bcg") dat <- escalc(measure = "RR", ai = tpos, bi = tneg, ci = cpos, di = cneg, data = dat.bcg) model <- rma(yi, vi, data = dat) print(forest_rma(model, study_labels = paste(dat.bcg$author, dat.bcg$year), trans = exp )) print(forest_rma(model, panels = forest_panels( Study = ~study, N = ~n, ~vline, `Log Relative Risk` = ~ forest(line_x = 0), ~ spacer(space = 0.10), ~ sprintf("%0.3f (%0.3f, %0.3f)", estimate, conf.low, conf.high) ), study_labels = paste(dat.bcg$author, dat.bcg$year), trans = exp )) }
if (require("metafor")) { data("dat.bcg") dat <- escalc(measure = "RR", ai = tpos, bi = tneg, ci = cpos, di = cneg, data = dat.bcg) model <- rma(yi, vi, data = dat) print(forest_rma(model, study_labels = paste(dat.bcg$author, dat.bcg$year), trans = exp )) print(forest_rma(model, panels = forest_panels( Study = ~study, N = ~n, ~vline, `Log Relative Risk` = ~ forest(line_x = 0), ~ spacer(space = 0.10), ~ sprintf("%0.3f (%0.3f, %0.3f)", estimate, conf.low, conf.high) ), study_labels = paste(dat.bcg$author, dat.bcg$year), trans = exp )) }
Plot a forest plot with panels of text
panel_forest_plot( forest_data, mapping = aes(estimate, xmin = conf.low, xmax = conf.high), panels = default_forest_panels(), trans = I, funcs = NULL, format_options = list(colour = "black", shape = 15, banded = TRUE, text_size = 5, point_size = 5), theme = theme_forest(), limits = NULL, breaks = NULL, recalculate_width = TRUE, recalculate_height = TRUE, exclude_infinite_cis = TRUE )
panel_forest_plot( forest_data, mapping = aes(estimate, xmin = conf.low, xmax = conf.high), panels = default_forest_panels(), trans = I, funcs = NULL, format_options = list(colour = "black", shape = 15, banded = TRUE, text_size = 5, point_size = 5), theme = theme_forest(), limits = NULL, breaks = NULL, recalculate_width = TRUE, recalculate_height = TRUE, exclude_infinite_cis = TRUE )
forest_data |
|
mapping |
mapping aesthetic created using |
panels |
|
trans |
transform for scales |
funcs |
optional list of functions required for formatting |
format_options |
formatting options as a list as generated by |
theme |
theme to apply to the plot |
limits |
limits of the forest plot on the X-axis (taken as the range of the data by default) |
breaks |
breaks to appear on the X-axis (note these will be exponentiated
if |
recalculate_width |
|
recalculate_height |
|
exclude_infinite_cis |
whether to exclude points and confidence intervals
that go to positive or negative infinity from plotting. They will still be
displayed as text. Defaults to |
A ggplot ready for display or saving
Default forest theme
theme_forest()
theme_forest()
a theme object for use with ggplot2