Package 'ckbplotr'

A numeric vector of length two. The limits of the x-axis.

A numeric vector of length two. The limits of the y-axis.

A numeric vector of length two. The gap between plotting area and axis to the left and bottom of the plot, as a proportion of the x-axis length. (Default: c(0.025, 0.025))

A numeric vector of length two. The extensions to add to the right and top of the plot, as a proportion of the x-axis length. (Default: c(0, 0))

The ratio (y-axis:x-axis) to use for the plot. Ignored if both width and height are set. (Default: 1.5)

A grid::unit object to set the width of the plot (not including the gap or extension).

A grid::unit object to set the height of the plot (not including the gap or extension).

Base font size, given in pts. (Default: 11)

Base size for line elements. (Deault: base_size/22)

Colour for foreground and background elements. (Defaults: "black" and "white")

Deprecated. Use ink instead.

Margin between axis titles and plot. (Default: 1)

Margin around entire plot (Default: margin(0.5, 0, 0.5, 0, "lines"))

Passed to clip argument of ggplot2::coord_cartesian(). (Default: "on")

A list of data frames. These should include columns or point estimates, and standard errors or confidence interval limits. If you specify a row.labels data frame, then they must also all contain a key column with the same name (which can be specified by col.key).

A data frame that contains the labels to be used for the rows of the plot. Use NA if a lower level heading is not required for a given row.

A character vector. The names of columns in row.labels to use as headings/subheadings/labels for labelling rows.

If set, then only rows matching these labels (at the first level) will be included.

Title to be placed above row labels.

A numeric vector specifying the space after a row label heading, at the end of a row label heading 'section'. (Default: c(0, 1, 0, 0))

Exponentiate estimates (and CIs) before plotting. (Default: TRUE)

Use log scale on the axis, and add a line at null effect. (Default: exponentiate)

A character vector. The names to be used for each forest plot panel. If none provided, then they will be numbered 1, 2, 3 ...

Titles to be placed above each forest plot.

Panel headings are by default centred over the plotting area ("panel"). Set to "plot" to centre over plotting area and text columns.

Name of column that links the results given in each data frame provided in panels and the labels given in row.labels. If row.labels data frame is not given, then this column will be used as row labels. (Default: "key")

Names of columns for: point estimates, standard errors, lower and upper limits of confidence intervals.

Names of columns to be printed to the left/right of the plot.

A character vector, the same length as col.left/col.right (+ 1 if estcolumn = TRUE). Should the contents of the columns be parsed into expressions. Use "col", "heading" or "both" to parse the column content only, heading or both.

Headings for columns.

A unit vector to position col.left/col.right columns.

A numeric vector. The horizontal justification of col.left/col.right columns. (Default: 1)

A character vector of length two. The two characters control the gaps between the first text column and the panel, and successive text columns. (Default: c("I", "W"))

Position of the titles given by left.heading and right.heading. Increase to move them up. (Default: 0)

Include a horizontal rule below column headings? (Default: FALSE)

Include column of estimates and confidence intervals to the right of each plot. (Default: TRUE)

Names of additional columns to be kept in returned data frame.

Character string to separate lower and upper limits of confidence interval. (Default: ", ")

Number of digits after decimal point to show for estimates and confidence intervals. (Default: 2)

Title to appear at the top of the plot.

Label to appear below the x-axis. (Default: "HR (95% CI)")

A numeric vector. The limits of the x axis.

A numeric vector. The tick points of the x axis.

Add a vertical reference line at this value. (If logscale == TRUE then by default it will be added at 1, but use NA not to plot this line.)

Plot estimates and CIs as diamonds. Name of a column of logical values.

Alternative to col.diamond. A character vectors identify the rows (using the key values) for which the estimate and CI should be plotted using a diamond.

Plot text as bold. Name of a column of logical values.

A character vector identifying row labels (using key values) which should additionally be bold. (Default: NULL)

Should the points be scaled by inverse of the standard error? (Default: FALSE)

Minimum standard error to use when scaling point size. (Default will use minimum in the data.)

The (largest) size of box to use for plotting point estimates. (Default: 3 * base_size / 11)

Shape of points. An integer, or name of a column of integers. (Default: 15 (square))

Colour for all parts of the plot. (Default: "black")

Colour of points. Name of a colour, or name of a column of colour names. Use a list of colour names for different colours on each panel. (Default will use plotcolour.)

Colour of CI lines. Name of a colour, or name of a column of colour names. Use a list of colour names for different colours on each panel. Use a vector (or list of vectors) in conjunction with panel.width to set a different colour for narrow confidence interval lines. (Default will use colour.)

Fill colour of points. Name of a colour, or name of a column of colour names. Use a list of colour names for different colours on each panel. (Default will use colour.)

Plot CI lines before points. A logical value, or name of a column of logical values. (Default will plot CI lines after points.)

A list of data frames. List must be the same length as panels. Data frames should contain a column with the name specified in col.key, and one or more of:

1. a column named 'text' containing character strings

2. columns named 'het_dof', 'het_stat', and 'het_p' containing character strings

3. columns names 'trend_stat' and 'trend_p' containing character strings

The character strings, heterogeneity test, and trend test results will be plotted in the column of estimates and CIs, below the row with the key given in the col.key column.

Space between bottom row and axis. (Default: 0.7)

Space to the left/right/between panels. (Default mid.space: unit(5, "mm"))

Plot margin, given as margin(top, right, bottom, left, units). (Default: margin(2, 8, 2, 8, "mm"))

Set width/height of panels. A grid::unit object, if a numeric is given assumed to be in mm. If panel.width is used, will also apply different formatting to narrow CIs.

base font size, given in pts.

base size for line elements

Size of outline of shapes. (Default: 0)

Line width for diamonds. (Default: base_line_size)

A character string giving the name of the theme element to use for the row labels (axis.text.y). (Default: "marquee::element_marquee")

Set to TRUE to not print the plot nor show generated code in the RStudio 'Viewer' pane. (Default: FALSE)

Print the plot. (Default: !quiet)

Show the ggplot2 code to generate the plot in RStudio 'Viewer' pane. (Default: !quiet)

Name of a function to apply to data frame before plotting.

Methods for customising the plot. See documentation for details.

Environment in which to evaluate the plot code. May be useful when calling this function inside another function.

DEPRECATED

Deprecated. Use right.parse instead.

Deprecated. Use left.heading instead.

Deprecated. Use right.heading instead.

Deprecated. Use left.pos instead.

Deprecated. Use right.pos instead.

Deprecated. Use left.hjust instead.

Deprecated. Use right.hjust instead.

Deprecated. Use left.gap instead.

Deprecated. Use right.gap instead.

Deprecated. Use heading.space instead.

Deprecated. Use heading.rule instead.

Set of aesthetic mappings created by aes(). If specified and inherit.aes = TRUE (the default), it is combined with the default mapping at the top level of the plot. You must supply mapping if there is no plot mapping.

The data to be displayed in this layer. There are three options:

If NULL, the default, the data is inherited from the plot data as specified in the call to ggplot().

A data.frame, or other object, will override the plot data. All objects will be fortified to produce a data frame. See fortify() for which variables will be created.

A function will be called with a single argument, the plot data. The return value must be a data.frame, and will be used as the layer data. A function can be created from a formula (e.g. ~ head(.x, 10)).

The statistical transformation to use on the data for this layer. When using a ⁠geom_*()⁠ function to construct a layer, the stat argument can be used to override the default coupling between geoms and stats. The stat argument accepts the following:

• A Stat ggproto subclass, for example StatCount.

• A string naming the stat. To give the stat as a string, strip the function name of the stat_ prefix. For example, to use stat_count(), give the stat as "count".

• For more information and other ways to specify the stat, see the layer stat documentation.

A position adjustment to use on the data for this layer. This can be used in various ways, including to prevent overplotting and improving the display. The position argument accepts the following:

• The result of calling a position function, such as position_jitter(). This method allows for passing extra arguments to the position.

• A string naming the position adjustment. To give the position as a string, strip the function name of the position_ prefix. For example, to use position_jitter(), give the position as "jitter".

• For more information and other ways to specify the position, see the layer position documentation.

Other arguments passed on to layer()'s params argument. These arguments broadly fall into one of 4 categories below. Notably, further arguments to the position argument, or aesthetics that are required can not be passed through .... Unknown arguments that are not part of the 4 categories below are ignored.

• Static aesthetics that are not mapped to a scale, but are at a fixed value and apply to the layer as a whole. For example, colour = "red" or linewidth = 3. The geom's documentation has an Aesthetics section that lists the available options. The 'required' aesthetics cannot be passed on to the params. Please note that while passing unmapped aesthetics as vectors is technically possible, the order and required length is not guaranteed to be parallel to the input data.

• When constructing a layer using a ⁠stat_*()⁠ function, the ... argument can be used to pass on parameters to the geom part of the layer. An example of this is stat_density(geom = "area", outline.type = "both"). The geom's documentation lists which parameters it can accept.

• Inversely, when constructing a layer using a ⁠geom_*()⁠ function, the ... argument can be used to pass on parameters to the stat part of the layer. An example of this is geom_area(stat = "density", adjust = 0.5). The stat's documentation lists which parameters it can accept.

• The key_glyph argument of layer() may also be passed on through .... This can be one of the functions described as key glyphs, to change the display of the layer in the legend.

If TRUE, the labels will be parsed into expressions and displayed as described in ?plotmath.

Unit value to move text horizontally (Default: unit(0, "pt"))

Unit value to move text vertically (Default: unit(0, "pt"))

If TRUE, text that overlaps previous text in the same layer will not be plotted. check_overlap happens at draw time and in the order of the data. Therefore data should be arranged by the label column before calling geom_text(). Note that this argument is not supported by geom_label().

If FALSE, the default, missing values are removed with a warning. If TRUE, missing values are silently removed.

logical. Should this layer be included in the legends? NA, the default, includes if any aesthetics are mapped. FALSE never includes, and TRUE always includes. It can also be a named logical vector to finely select the aesthetics to display. To include legend keys for all levels, even when no data exists, use TRUE. If NA, all levels are shown in legend, but unobserved levels are omitted.

If FALSE, overrides the default aesthetics, rather than combining with them. This is most useful for helper functions that define both data and aesthetics and shouldn't inherit behaviour from the default plot specification, e.g. annotation_borders().

Arguments passed to ggsave and the PNG device function.

A ggplot2 plot

Arguments passed to ckb_style()

Plot (or graphical object).

Title to be added to the page. (Default: "")

Position of the title text. Default is 1/4 inch from top left of page. (Default: unit.c(unit(1.27/2, "cm"), unit(1, "npc") - unit(1.27/2, "cm")))

Justification of the title text. (Default: c(0, 1))

Graphical parameters for title. (Default: list(fontsize = 12, fontface = "bold"))

Footer to be added to the page. (Default: "")

Position of the footer text. Default is 1/6 inch from bottom and 1/4 inch from left of page. (Default: unit.c(unit(1.27/2, "cm"), unit(1.27/3, "cm")))

Justification of the footer text. (Default: c(0, 0))

Graphical parameters for footer. (Default: list(fontsize = 9))

Margin to be placed around the plot. Default is 2.27cm top, 1.27cm (1/2 inch) other sides. (Default: unit(c(2.27, 1.27, 1.27, 1.27), units = "cm"))

A unit vector of length two (width, height). Size of plot (a width/height larger than page weight/height minus margins will be ignored), centred within margins. By default, plot will fill the space within margins.

If size is set, where to place figure within margins. 1 = top, 0.5 = middle, 0 = bottom. (Default: 0.5)

If size is set, where to place figure within margins. 1 = right, 0.5 = middle, 0 = left (Default: 0.5)

Page size of output: "A4" or "A5". (Default: "A4")

Landscape page orientation? (Default: False)

Dimensions (width, height) of output. Overrides pagesize and landscape arguments if used.

Plot (or graphical object).

Name of file to create.

Name of second output file of the figure without margins or title.

List of arguments passed to ggplot2::ggsave() for the main figure.

List of arguments passed to ggplot2::ggsave() for the cropped figure.

Preview the output in the RStudio Viewer pane. (Default: False)

Other arguments passed to prepare_figure.

The data frame containing estimates to be plotted.

Name of column that provides the x-axis value (e.g. exposure, risk factor, dependent variable). (Default: "x")

Name of column that provides point estimates. (Default: "estimate")

Name of column that provides standard errors. (Default: "stderr")

Name of column that provides lower limit of confidence intervals.

Name of column that provides upper limit of confidence intervals.

Name of column that provides number to be plotted below CIs.

Exponentiate estimates (and CIs) before plotting, use log scale on the axis. (Default: FALSE)

Use log scale for the y axis. (Default: exponentiate)

Use log scale for the x axis. (Default: FALSE)

Should the points be scaled by inverse of the standard error? (Default: FALSE)

Number of digits to use in text of estimates.

Minimum standard error to use when scaling point size. (Default will use minimum in the data.)

The (largest) size of box to use for plotting point estimates. (Default: 3 * base_size / 11)

Name of column that groups the estimates. (Default: NULL)

Shape of points. An integer, or name of a column of integers. (Default: 15)

Colour for non-data aspects of the plot. (Default: "black")

Colour of points. Name of a colour, or name of a column of colour names. (Default will use plotcolour)

Colour of CI lines. Colour of CI lines. Name of a colour, or name of a column of colour names. (Default will use plotcolour)

Fill colour of points. Fill colour of points. Name of a colour, or name of a column of colour names. (Default will use plotcolour)

Plot CI lines before points. A logical value, or name of a column of logical values. (Default will plot CI lines after points.)

Add lines to the plot. "lmw" = Linear fit through estimates, weighted by inverse variance. "lm" = Unweighted linear fit through estimates. "connect" = Lines connecting each estimate. (Default: "none")

A numeric vector of length two. The limits of the x-axis.

A numeric vector of length two. The limits of the y-axis.

Panel height to use and apply different formatting to short CIs. A grid::unit() object, or if numeric is assumed to be in mm.

Panel width.A grid::unit() object, or if numeric is assumed to be in mm.

A numeric vector of length two. The gap between plotting area and axis to the left and bottom of the plot, as a proportion of the x-axis length. (Default: c(0.025, 0.025))

A numeric vector of length two. The extensions to add to the right and top of the plot, as a proportion of the x-axis length. (Default: c(0.025, 0.025))

The ratio (y-axis:x-axis) to use for the plot. (Default: 1.5)

Plot margin, given as margin(top, right, bottom, left, units). (Default: margin(0.5, 1.5, 0.5, 0.5, "lines"))

Passed to clip argument of ggplot2::coord_cartesian(). (Default: "on")

Base font size, given in pts. (Default: 11)

Base size for line elements. (Deault: base_size/22)

Size of outline of shapes. (Default: base_size/22)

Margin between axis titles and plot. (Default: 1)

Breaks for the x axis. Passed to ggplots::scale_x_continuous. (Default: NULL)

Breaks for the y axis. Passed to ggplots::scale_y_continuous. (Default: NULL)

Label for x-axis. (Default: "Risk factor")

Label for y-axis. (Default: "Estimate (95% CI)")

The name of the colour scale/legend for groups. (Default: "")

Position of the legend for groups ("none", "left", "right", "bottom", "top", or two-element numeric vector). (Default: "top")

Plot title. (Default: NULL)

Set to TRUE to not print the plot nor show generated code in the RStudio 'Viewer' pane. (Default: FALSE)

Print the plot. (Default: !quiet)

Show the ggplot2 code to generate the plot in RStudio 'Viewer' pane. (Default: !quiet)

Methods for customising the plot. See documentation for details.

Environment in which to evaluate the plot code. May be useful when calling this function inside another function.

Base font size, given in pts. (Default: 11)

Base size for line elements. (Deault: base_size/22)

Colour for foreground and background elements. (Defaults: "black" and "white")

Deprecated. Use ink instead.

Margin between axis titles and plot. (Default: 1)

Margin around entire plot (Default: margin(0.5, 0, 0.5, 0, "lines"))

Arguments passed to ggplot2::theme_bw() if using ggplot2 4.0.0 or later.