Nothing
# =============================================================================
# render_forestplot.R - Helper for Rendering ForestSearch Forest Plots
# =============================================================================
#
# Provides functions to create custom themes and render forestploter plots
# with size control in Quarto/RMarkdown documents.
#
# =============================================================================
#' Create Forest Plot Theme with Size Controls
#'
#' Creates a forestploter theme with parameters that control overall plot
#' sizing and appearance. This is the primary way to control how large
#' the forest plot renders.
#'
#' @param base_size Numeric. Base font size in points. This is the primary
#' scaling parameter - increasing it will proportionally scale all fonts,
#' row padding, and line widths. Default: 10.
#' @param scale Numeric. Additional scaling multiplier applied on top of
#' base_size. Use for quick overall scaling. Default: 1.0.
#' @param row_padding Numeric vector of length 2. Padding around row content
#' in mm as c(vertical, horizontal). If NULL, auto-calculated from base_size.
#' Default: NULL.
#' @param ci_pch Integer. Point character for CI. 15=square, 16=circle,
#' 18=diamond. Default: 15.
#' @param ci_lwd Numeric. Line width for CI lines. If NULL, auto-calculated
#' from base_size. Default: NULL.
#' @param ci_Theight Numeric. Height of T-bar ends on CI. If NULL, auto-calculated
#' from base_size. Default: NULL.
#' @param ci_col Character. Color for CI lines and points. Default: "black".
#' @param header_fontsize Numeric. Font size for column headers.
#' If NULL, auto-calculated as base_size * scale + 1. Default: NULL.
#' @param body_fontsize Numeric. Font size for body text.
#' If NULL, auto-calculated as base_size * scale. Default: NULL.
#' @param footnote_fontsize Numeric. Font size for footnotes.
#' If NULL, auto-calculated as base_size * scale - 1. Default: NULL.
#' @param footnote_col Character. Color for footnote text. Default: "darkcyan".
#' @param title_fontsize Numeric. Font size for title.
#' If NULL, auto-calculated as base_size * scale + 4. Default: NULL.
#' @param cv_fontsize Numeric. Font size for CV annotation text.
#' If NULL, auto-calculated as base_size * scale. Default: NULL.
#' @param cv_col Character. Color for CV annotation text. Default: "gray30".
#' @param refline_lwd Numeric. Reference line width. If NULL, auto-calculated.
#' Default: NULL.
#' @param refline_lty Character. Reference line type. Default: "dashed".
#' @param refline_col Character. Reference line color. Default: "gray30".
#' @param vertline_lwd Numeric. Vertical line width. If NULL, auto-calculated.
#' Default: NULL.
#' @param vertline_lty Character. Vertical line type. Default: "dashed".
#' @param vertline_col Character. Vertical line color. Default: "gray20".
#' @param arrow_type Character. Arrow type: "open" or "closed". Default: "closed".
#' @param arrow_col Character. Arrow color. Default: "black".
#' @param summary_fill Character. Fill color for summary diamonds. Default: "black".
#' @param summary_col Character. Border color for summary diamonds. Default: "black".
#'
#' @return A list of class "fs_forest_theme" containing all theme parameters.
#'
#' @details
#' The \code{base_size} parameter is the primary way to control plot size.
#' When you change \code{base_size}, the following are automatically scaled:
#' \itemize{
#' \item All font sizes (body, header, footnote, CV, title)
#' \item Row padding (vertical and horizontal)
#' \item CI line width and T-bar height
#' \item Reference and vertical line widths
#' }
#'
#' The scaling formula uses base_size = 10 as the reference point:
#' \itemize{
#' \item base_size = 10: Default sizing
#' \item base_size = 12: 20% larger
#' \item base_size = 14: 40% larger
#' \item base_size = 16: 60% larger
#' }
#'
#' You can override any individual parameter by specifying it explicitly.
#'
#' The theme does NOT set row background colors - those are determined
#' automatically by \code{plot_subgroup_results_forestplot()} based on
#' row types (ITT, reference, posthoc, etc.).
#'
#' @examples
#' \dontrun{
#' # Simple: just increase base_size for larger plot
#' large_theme <- create_forest_theme(base_size = 14)
#'
#' # Or use scale for quick adjustment
#' large_theme <- create_forest_theme(base_size = 10, scale = 1.4)
#'
#' # Fine-tune specific elements
#' custom_theme <- create_forest_theme(
#' base_size = 14,
#' cv_fontsize = 12, # Override auto-calculated CV font size
#' ci_lwd = 2.5 # Override auto-calculated CI line width
#' )
#'
#' # Use with plot_subgroup_results_forestplot
#' result <- plot_subgroup_results_forestplot(
#' fs_results = list(fs.est = fs, fs_bc = fs_bc),
#' df_analysis = df.analysis,
#' outcome.name = "time",
#' event.name = "status",
#' treat.name = "treatment",
#' theme = large_theme
#' )
#'
#' render_forestplot(result)
#' }
#'
#' @seealso \code{\link{plot_subgroup_results_forestplot}}, \code{\link{render_forestplot}}
#'
#' @importFrom grid unit gpar
#' @export
create_forest_theme <- function(
base_size = 10,
scale = 1.0,
row_padding = NULL,
ci_pch = 15,
ci_lwd = NULL,
ci_Theight = NULL,
ci_col = "black",
header_fontsize = NULL,
body_fontsize = NULL,
footnote_fontsize = NULL,
footnote_col = "darkcyan",
title_fontsize = NULL,
cv_fontsize = NULL,
cv_col = "gray30",
refline_lwd = NULL,
refline_lty = "dashed",
refline_col = "gray30",
vertline_lwd = NULL,
vertline_lty = "dashed",
vertline_col = "gray20",
arrow_type = "closed",
arrow_col = "black",
summary_fill = "black",
summary_col = "black"
) {
if (!requireNamespace("forestploter", quietly = TRUE)) {
stop("Package 'forestploter' is required but not installed.", call. = FALSE)
}
# Calculate scaling factor relative to base_size = 10
size_factor <- (base_size / 10) * scale
# Auto-calculate font sizes if not provided
if (is.null(body_fontsize)) body_fontsize <- base_size * scale
if (is.null(header_fontsize)) header_fontsize <- base_size * scale + 1
if (is.null(footnote_fontsize)) footnote_fontsize <- max(base_size * scale - 1, 8)
if (is.null(title_fontsize)) title_fontsize <- base_size * scale + 4
if (is.null(cv_fontsize)) cv_fontsize <- base_size * scale
# Auto-calculate row padding if not provided
# Base padding is c(4, 4) at base_size = 10
if (is.null(row_padding)) {
row_padding <- c(4 * size_factor, 4 * size_factor)
}
# Auto-calculate line widths if not provided
# Base ci_lwd is 1.5 at base_size = 10
if (is.null(ci_lwd)) ci_lwd <- 1.5 * size_factor
if (is.null(ci_Theight)) ci_Theight <- 0.2 * size_factor
if (is.null(refline_lwd)) refline_lwd <- 1.0 * size_factor
if (is.null(vertline_lwd)) vertline_lwd <- 1.0 * size_factor
# Create result object with parameters
result <- list(
base_size = base_size,
scale = scale,
size_factor = size_factor,
row_padding = row_padding,
body_fontsize = body_fontsize,
header_fontsize = header_fontsize,
footnote_fontsize = footnote_fontsize,
footnote_col = footnote_col,
title_fontsize = title_fontsize,
cv_fontsize = cv_fontsize,
cv_col = cv_col,
ci_pch = ci_pch,
ci_lwd = ci_lwd,
ci_Theight = ci_Theight,
ci_col = ci_col,
refline_lwd = refline_lwd,
refline_lty = refline_lty,
refline_col = refline_col,
vertline_lwd = vertline_lwd,
vertline_lty = vertline_lty,
vertline_col = vertline_col,
arrow_type = arrow_type,
arrow_col = arrow_col,
summary_fill = summary_fill,
summary_col = summary_col
)
class(result) <- c("fs_forest_theme", "list")
return(result)
}
#' Print Method for ForestSearch Forest Theme
#'
#' @param x An fs_forest_theme object
#' @param ... Additional arguments (ignored)
#' @return The input \code{x}, invisibly.
#' @examples
#' theme <- create_forest_theme()
#' print(theme)
#' @export
print.fs_forest_theme <- function(x, ...) {
cat("ForestSearch Forest Plot Theme\n")
cat("==============================\n")
cat("Base size: ", x$base_size, "\n")
cat("Scale: ", x$scale, "\n")
cat("Size factor: ", round(x$size_factor, 2), "x (relative to base_size=10)\n")
cat("\nCalculated values:\n")
cat(" Body font: ", round(x$body_fontsize, 1), "\n")
cat(" Header font: ", round(x$header_fontsize, 1), "\n")
cat(" CV font: ", round(x$cv_fontsize, 1), "\n")
cat(" Footnote font: ", round(x$footnote_fontsize, 1), "\n")
cat(" Row padding: ", paste(round(x$row_padding, 1), collapse = ", "), " mm\n")
cat(" CI line width: ", round(x$ci_lwd, 2), "\n")
cat("\nUse with: plot_subgroup_results_forestplot(..., theme = x)\n")
invisible(x)
}
#' Render ForestSearch Forest Plot
#'
#' Renders a forest plot from \code{plot_subgroup_results_forestplot()}.
#'
#' @param x An fs_forestplot object from \code{plot_subgroup_results_forestplot()}.
#' @param newpage Logical. Call grid.newpage() before drawing. Default: TRUE.
#'
#' @return Invisibly returns the grob object.
#'
#' @details
#' To control plot sizing, create a custom theme using \code{create_forest_theme()}
#' and pass it to \code{plot_subgroup_results_forestplot()}:
#'
#' \code{my_theme <- create_forest_theme(base_size = 14, row_padding = c(6, 4))}
#'
#' \code{result <- plot_subgroup_results_forestplot(..., theme = my_theme)}
#'
#' \code{render_forestplot(result)}
#'
#' @examples
#' \dontrun{
#' # For larger plot, use theme parameter in plot_subgroup_results_forestplot:
#' large_theme <- create_forest_theme(
#' base_size = 14,
#' row_padding = c(6, 4),
#' cv_fontsize = 11
#' )
#'
#' result <- plot_subgroup_results_forestplot(
#' fs_results = list(fs.est = fs, fs_bc = fs_bc),
#' df_analysis = df.analysis,
#' outcome.name = "time",
#' event.name = "status",
#' treat.name = "treatment",
#' theme = large_theme
#' )
#'
#' render_forestplot(result)
#' }
#'
#' @importFrom grid grid.newpage grid.draw
#' @export
render_forestplot <- function(x, newpage = TRUE) {
if (!inherits(x, "fs_forestplot")) {
stop("x must be an fs_forestplot object from plot_subgroup_results_forestplot()")
}
if (newpage) grid::grid.newpage()
grid::grid.draw(x$plot)
invisible(x$plot)
}
#' Save ForestSearch Forest Plot to File
#'
#' Saves a forest plot to a file (PDF, PNG, etc.) with explicit dimensions.
#'
#' @param x An fs_forestplot object.
#' @param filename Character. Output filename. Extension determines format.
#' @param width Numeric. Plot width in inches. Default: 12.
#' @param height Numeric. Plot height in inches. Default: 10.
#' @param dpi Numeric. Resolution for raster formats. Default: 300.
#' @param bg Character. Background color. Default: "white".
#'
#' @return Invisibly returns the filename.
#'
#' @examples
#' \dontrun{
#' # Create plot with custom theme
#' large_theme <- create_forest_theme(base_size = 14, row_padding = c(6, 4))
#'
#' result <- plot_subgroup_results_forestplot(
#' fs_results = list(fs.est = fs, fs_bc = fs_bc),
#' df_analysis = df.analysis,
#' outcome.name = "time",
#' event.name = "status",
#' treat.name = "treatment",
#' theme = large_theme
#' )
#'
#' # Save to file
#' save_forestplot(result, "forest_plot.pdf", width = 14, height = 12)
#' }
#'
#' @importFrom grDevices pdf png svg jpeg dev.off
#' @export
save_forestplot <- function(
x,
filename,
width = 12,
height = 10,
dpi = 300,
bg = "white"
) {
if (!inherits(x, "fs_forestplot")) {
stop("x must be an fs_forestplot object")
}
# Determine format from extension
ext <- tolower(tools::file_ext(filename))
# Open appropriate device
if (ext == "pdf") {
grDevices::pdf(filename, width = width, height = height, bg = bg)
} else if (ext == "png") {
grDevices::png(filename, width = width, height = height, units = "in",
res = dpi, bg = bg)
} else if (ext == "svg") {
if (requireNamespace("svglite", quietly = TRUE)) {
svglite::svglite(filename, width = width, height = height, bg = bg)
} else {
grDevices::svg(filename, width = width, height = height, bg = bg)
}
} else if (ext %in% c("jpg", "jpeg")) {
grDevices::jpeg(filename, width = width, height = height, units = "in",
res = dpi, bg = bg, quality = 95)
} else {
stop("Unsupported file format: ", ext, ". Use .pdf, .png, .svg, or .jpg")
}
# Draw the plot
grid::grid.newpage()
grid::grid.draw(x$plot)
# Close device
grDevices::dev.off()
message("Saved forest plot to: ", filename)
invisible(filename)
}
#' Print Method for ForestSearch Forest Plot
#'
#' @param x An fs_forestplot object
#' @param ... Additional arguments (ignored)
#' @return The input \code{x}, invisibly.
#' @examples
#' \dontrun{
#' gbsg <- survival::gbsg
#' gbsg$grade3 <- as.integer(gbsg$grade == 3)
#' fs <- forestsearch(gbsg, id.name = "pid",
#' confounders.name = c("age", "meno", "size", "grade3", "nodes", "pgr", "er"),
#' outcome.name = "rfstime", treat.name = "hormon", event.name = "status")
#' fp <- plot_subgroup_results_forestplot(list(fs.est = fs), gbsg,
#' outcome.name = "rfstime", event.name = "status", treat.name = "hormon")
#' print(fp)
#' }
#' @export
print.fs_forestplot <- function(x, ...) {
cat("ForestSearch Subgroup Results Forest Plot\n")
cat("=========================================\n")
cat("Number of rows:", nrow(x$data), "\n")
cat("Row types:", paste(unique(x$row_types), collapse = ", "), "\n")
if (length(x$cv_metrics) > 0) {
cat("\nCross-validation metrics:\n")
for (i in seq_along(x$cv_metrics)) {
cat(" -", x$cv_metrics[[i]], "\n")
}
}
cat("\nTo display: render_forestplot(x) or plot(x)\n")
cat("To save: save_forestplot(x, 'plot.pdf', width = 14, height = 12)\n")
cat("\nFor larger plot or bigger CV text, recreate with custom theme:\n")
cat(" theme <- create_forest_theme(base_size = 14, cv_fontsize = 11)\n")
cat(" result <- plot_subgroup_results_forestplot(..., theme = theme)\n")
invisible(x)
}
#' Plot Method for ForestSearch Forest Plot
#'
#' @param x An fs_forestplot object
#' @param ... Additional arguments (ignored)
#' @return The input \code{x}, invisibly.
#' @examples
#' \dontrun{
#' gbsg <- survival::gbsg
#' gbsg$grade3 <- as.integer(gbsg$grade == 3)
#' fs <- forestsearch(gbsg, id.name = "pid",
#' confounders.name = c("age", "meno", "size", "grade3", "nodes", "pgr", "er"),
#' outcome.name = "rfstime", treat.name = "hormon", event.name = "status")
#' fp <- plot_subgroup_results_forestplot(list(fs.est = fs), gbsg,
#' outcome.name = "rfstime", event.name = "status", treat.name = "hormon")
#' plot(fp)
#' }
#' @export
plot.fs_forestplot <- function(x, ...) {
render_forestplot(x)
invisible(x)
}
Any scripts or data that you put into this service are public.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.