gg_boxplot: Box plot

Description Usage Arguments Details Value Author(s) Examples

Description

Creates a box plot

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
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)

Arguments

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'

Details

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.

Value

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

Author(s)

Feiyang Niu (Feiyang.Niu@gilead.com)

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
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
)

statech/CommonPlots documentation built on May 6, 2019, 1:32 a.m.