gg_boxplot: Box plot
In statech/CommonPlots: Create Commonly Used Plots

Description Usage Arguments Details Value Author(s) Examples

Creates a box plot

gg_boxplot(data, x = NULL, y, group = NULL, group_levels = NULL,
  label = NULL, facet_r = NULL, facet_c = NULL, facet_r_levels = NULL,
  facet_c_levels = NULL, facet_scale = "free", facet_space = "free",
  x_lab = x, y_lab = y, group_lab = group, title = "", x_limit = NULL,
  y_limit = NULL, y_log = FALSE, all_colors = NULL, add_points = TRUE,
  point_shape = 19, add_legend = TRUE, legend_pos = "bottom",
  reference_hline = NULL, reference_vline = NULL, test_func = NULL,
  test_result = c(`p value` = "p.value"), x_tick_angle = 0,
  sample_size = TRUE, sample_size_font_size = 3, add_label = FALSE,
  is_repel = FALSE, jitter_factor = 1, bw_theme = TRUE, grids = "on",
  randseed = NULL)

`data`	Data frame: default dataset to use for plot
`x`	Character: name of a `data` column mapped to x-axis variable, i.e. time
`y`	Character: name of a `data` column mapped to y-axis variable
`group`	Character: name of a `data` column mapped to the color of points
`group_levels`	Vector/List: a named vector/list that specifies the levels and labels of `group`
`label`	Character: name of a `data` column used to label the points when both `add_points` and `add_label` are `TRUE`
`facet_r`	Character: name of a `data` column mapped to the facet row in panel plot layout. Check `facet_grid` for more details
`facet_c`	Character: name of a `data` column mapped to the facet column in panel plot layout. Check `facet_grid` for more details
`facet_r_levels`	Vector/List: a named vector/list that specifies the levels and labels of `facet_r`
`facet_c_levels`	Vector/List: a named vector/list that specifies the levels and labels of `facet_c`
`facet_scale`	Character: Are scales shared across all facets. Refer to the 'scale' argument in `facet_grid`. Default 'free' means that scales are not shared
`facet_space`	Character: Refer to the 'space' argument in `facet_grid`. Default 'free' means both height and width will vary
`x_lab`	Character: x-axis label
`y_lab`	Character: y-axis label
`group_lab`	Character: group variable label
`title`	Character: boxplot title
`x_limit`	Numeric vector of length 2: limits for x-axis, e.g. `c(0, 10)`.
`y_limit`	Numeric vector of length 2: limits for y-axis, e.g. `c(-5, 5)`
`y_log`	Logical: `TRUE` to use log-scale for y-axis and `FALSE` (default) otherwise.
`all_colors`	Vector: a vector of valid color representations for all the point colors. When 'group' is mapped to the color of points, specify 'all_colors' to change default colors. See `is.color` for valid color definition
`add_points`	Logical: `TRUE` (default) to add original data points, jittered along x-axis
`point_shape`	integer: valid point shape when `add_points` is `TRUE`. Refer to ggplot2 Quick Reference: shape for the details of valid point shape in ggplot2
`add_legend`	Logical: `TRUE` (default) to show legend and `FALSE` otherwise
`legend_pos`	Character: dictates the location where to place the legend. By default, the legend will be place beneath the actual plot
`reference_hline`	Numeric vector: locations of horizontal reference line(s) if there is any
`reference_vline`	Numeric vector: locations of vertical reference line(s) if there is any
`test_func`	function: the function to be applied to perform statistical test of `y` variable against `group`, if present, or `x`, if `group` is not present but `x` is. Typically, equality test is of interest and includes Student's t-Test ('test_func = t.test'), Wilcoxon Rank Sum and Signed Rank Tests ('test_func = wilcox.test'), ANOVA test ('test_func = CommonPlots::anova.test'), Kruskal-Wallis Rank Sum Test ('test_func = kruskal.test'). Besides, Jonckheere-Terpstra trend test (DescTools::JonckheereTerpstraTest) is also supported and can be specified as 'test_func = CommonPlots::JonckheereTerpstraTest'. In fact, arbitrary test function which takes 'formula' and 'data' as its first two arguments can be passed through `test_func`
`test_result`	(named) String/List: Specify which component from the test, `test_func`, to be displayed in the box plot. Note that only one component is allowed and `test_result` must be a named component of the test result. When `test_func` is specified and `test_result` is omitted, the function will guess if the test result includes a component named 'p.value'. If there is, p value will be displayed; otherwise nothing gets displayed. As an example, if ‘test_result = c(’P value:' = 'p.value')', the string 'P value: pvalue' will be displayed in the box plot, where pvalue is the numeric p value. In the case of panel plot, the specified test will be carried out in each panel and result gets displayed respectively
`x_tick_angle`	Numeric: the orientation angle (in [0, 360]) of the x-axis tick marks. By default, the label will be horizontal.
`sample_size`	Logical: `TRUE` (default) to place sample size annotation along x-axis tick marks and `FALSE` otherwise
`sample_size_font_size`	Numeric: font size of sample size annotation
`add_label`	Logical: whether or not to add labels for the points Default is set to 'FALSE'
`is_repel`	Logical: whether or not to avoid text overlapping using ggrepel
`jitter_factor`	Numeric: determines how much the points are jittered over x-axis when 'add_points = TRUE'. By default, 'jitter_factor = 1'
`bw_theme`	Logical: If 'TRUE' (default), black-and-white theme will be used. Refer to `theme_bw` for more details
`grids`	Character: grids option. Must be one of ‘c(’on', 'major', 'off')‘ with ’on' having both major and minor grids, 'major' having only major grids, and 'off' having no grids
`randseed`	Numeric: random seed can be set in producing jittered points when `add_points` is `TRUE`. By default, no random seed is set, i.e. 'randseed = NULL'

This function relies on ggplot2 package to create a box plot with ability to label points. Point labelling has the option to repel text overlapping with ggrepel. The function supports panel plot layout. By default black-and-white theme is used.

An object of class ggplot (if return_data = FALSE) or a list of two components: an object of class ggplot and a data frame that used to generate the plot

Feiyang Niu (Feiyang.Niu@gilead.com)

library(CommonPlots)
data <- mpg
data$cyl <- factor(data$cyl)
boxplot_ <- gg_boxplot(
    data, x = 'cyl', y = 'displ', group = 'year',
    x_lab = 'Number of cylinders', y_lab = 'Engine displacement (L)',
    group_lab = 'Year', title = ''
)
# boxplot with Student's t-Test performed on engine displacement against year
boxplot_ <- gg_boxplot(
    data, x = 'cyl', y = 'displ', group = 'year', test_func = t.test,
    test_result = c('T test p value:' = 'p.value'),
    x_lab = 'Number of cylinders', y_lab = 'Engine displacement (L)',
    group_lab = 'Year', title = ''
)
boxplot_ <- gg_boxplot(
    diamonds, x = 'cut', y = 'price', group = 'clarity',
    group_levels = c('SI2', 'VS2', 'VVS2'), facet_r = 'color',
    facet_r_levels = c('Color = D' = 'D', 'Color = G' = 'G', 'Color = J' = 'J'),
    x_lab = 'Cut', y_lab = 'Price', group_lab = 'Clarity', title = '',
    sample_size_font_size = 4
)
# boxplot with ANOVA test on diamond price against clarify
boxplot_ <- gg_boxplot(
    diamonds, x = 'cut', y = 'price', group = 'clarity',
    group_levels = c('SI2', 'VS2', 'VVS2'), facet_r = 'color',
    facet_r_levels = c('Color = D' = 'D', 'Color = G' = 'G', 'Color = J' = 'J'),
    test_func = anova.test, test_result = c('ANOVA p value:' = 'p.value'),
    x_lab = 'Cut', y_lab = 'Price', group_lab = 'Clarity', title = '',
    sample_size_font_size = 4
)