gg_time_profiling: Time-profiling Plots
In statech/CommonPlots: Create Commonly Used Plots

Description Usage Arguments Details Value Author(s) Examples

Creats time-profiling plots with longitudinal data

gg_time_profiling(data, x, y, subject = NULL, group = NULL,
  group_levels = NULL, facet_r = NULL, facet_c = NULL,
  facet_r_levels = NULL, facet_c_levels = NULL, facet_scale = "free",
  facet_space = "fixed", x_lab = x, y_lab = y, group_lab = group,
  title = "", x_limit = NULL, y_limit = NULL, x_tick_label = x,
  all_xticks = FALSE, x_tick_angle = 0, y_tick_angle = 0,
  geoms = c("point", "line", "sumline", "boxplot"), avg_method = "mean",
  var_method = "se", y_log = FALSE, sample_size = TRUE,
  sample_size_font_size = 3, reference_hline = NULL,
  reference_vline = NULL, subject_show = FALSE, subject_label_size = 0.8,
  add_legend = TRUE, legend_pos = "bottom", all_colors = NULL,
  all_linetypes = NULL, jitter_factor = 1, grids = "on",
  bw_theme = TRUE, randseed = NULL, return_data = FALSE)

`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
`subject`	Character: name of a `data` column mapped to subject IDs or other types of IDs that define membership of repeated measurements in the data
`group`	Character: name of a `data` column mapped to the fill of bars
`group_levels`	Vector/List: a named vector/list that specifies the levels and labels of `group`
`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: barplot 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)`
`x_tick_label`	Vector: x-axis tick marks
`all_xticks`	Logical: `TRUE` (default) to display all marks specified as the unique values of `x_tick_label`
`x_tick_angle`	Numeric: the orientation angle (in [0, 360]) of the x-axis tick marks. By default, the label will be horizontal.
`y_tick_angle`	Numeric: the orientation angle (in [0, 360]) of the y-axis tick marks. By default, the label will be horizontal.
`geoms`	Character vector: specify geometric components to be included in the plot. Valid geoms are 'boxplot', 'line', 'point', 'sumline'. For example, if the user needs to create a boxplot with raw data points, specify `geoms = c('boxplot', 'point')`; if the user wants to create a Mean + SE plot, let `geoms = c('sumline', 'point')` together with specification of `avg_method` and `var_method`
`avg_method`	Character: dicates whether to use `mean` (`avg_method = 'mean'`) or `median`. Be noted that only these two options are permitted and both methods will remove `NA`s in calculation
`var_method`	Character: dicates whether to use standard error (`var_method = 'se'`) or standard deviation (`var_method = 'sd'`). Be noted that only these two options are permitted and both methods will remove `NA`s in calculation
`y_log`	Logical: `TRUE` to use log-scale for y-axis and `FALSE` (default) otherwise.
`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
`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
`subject_show`	Logical: `TRUE` to show subject IDs (or other types) and `FALSE` (default) otherwise
`add_legend`	Logical: `TRUE` (default) to show legend and `FALSE` otherwise
`legend_pos`	Character: dictates the location where to place the legend. Possible locations are 'left', 'right', 'bottom', 'top'. By default, the legend will be place beneath the actual plot, i.e. ‘legend_pos = ’bottom''
`all_colors`	Vector of valid color representation: when `group` is present, categories of `group` will take different color for specified geometric objects. This argument allows the user to overwrite default color theme. See `col` argument in `col2rgb` for types of valid color representation
`all_linetypes`	Numeric vector: by default, lines of different categories of `group`, when present, will be solid lines. This argument allows the user to overwrite the default line types. See linetypes for valid ggplot2 linetype specification
`jitter_factor`	Numeric: determines how much the points are jittered over x-axis when ‘geoms' includes ’point'. By default, 'jitter_factor = 1'
`grids`	Character: control the grids. If 'on' (default), grids will be drawn; if 'x', only grids on x-axis will be drawn; if 'y', only grids on y-axis will be drawn; if 'off', no grids will be drawn
`bw_theme`	Logical: if 'TRUE' (default), black-and-white theme will be used. Refer to `theme_bw` for more details
`randseed`	Numeric: random seed can be set in producing jittered points when `geoms` includes 'point'. By default, no random seed is set, i.e. 'randseed = NULL'
`return_data`	Logical: `TRUE` to return both plot and the data used to produce the plot and `FALSE` (default) to return only plot

This function relies on ggplot2 package to create time-profiling plots including: Mean + SD/SE plot, Mean + Median plot, Boxplot, Spaghetti plot and their mixture. Labels can be added to the end of each line using directlabels. Panel plot layout is supported. 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(koopLME)

# Mean + SE plot
data <- koopLME
data$siblings <- factor(with(data, ifelse(SIBLINGS >= 3, '>= 3', SIBLINGS)),
                        levels = c(0, 1, 2, '>= 3'))
mean_se_plot <- gg_time_profiling(
    data, x = 'TIMETRND', y = 'LOGWAGE', group = 'siblings',
    geoms = c('sumline'), avg_method = 'mean',
    var_method = 'se', x_lab = 'Time trend',
    y_lab = 'Log of hourly wage', group_lab = 'Number of siblings',
    title = 'Mean + SE plot'
)

# Median + IQR plot
data <- koopLME
data$siblings <- factor(with(data, ifelse(SIBLINGS >= 3, '>= 3', SIBLINGS)),
                        levels = c(0, 1, 2, '>= 3'))
sib_labels <- paste('Number of siblings:', levels(data$siblings))
median_iqr_plot <- gg_time_profiling(
    data, x = 'TIMETRND', y = 'LOGWAGE', facet_c = 'siblings',
    facet_c_levels = setNames(levels(data$siblings), sib_labels),
    geoms = c('sumline'), avg_method = 'median',
    x_lab = 'Time trend', y_lab = 'Log of hourly wage',
    title = 'Median + IQR plot'
)

# Spaghetti plot
data <- koopLME
data <- with(data, data[PERSONID %in% unique(PERSONID)[1:100], ])
spaghetti_plot <- gg_time_profiling(
    data, x = 'TIMETRND', y = 'LOGWAGE', subject = 'PERSONID',
    geoms = c('line'), x_lab = 'Time trend',
    y_lab = 'Log of hourly wage', title = 'Spaghetti plot',
    subject_show = TRUE
)

# Box plot over time
data <- koopLME
data$siblings <- factor(with(data, ifelse(SIBLINGS >= 3, '>= 3', SIBLINGS)),
                        levels = c(0, 1, 2, '>= 3'))
sib_labels <- paste('Number of siblings:', levels(data$siblings))
boxplot <- gg_time_profiling(
    data, x = 'TIMETRND', y = 'LOGWAGE', facet_r = 'siblings',
    facet_r_levels = setNames(levels(data$siblings), sib_labels),
    geoms = c('boxplot', 'point'), x_lab = 'Time trend',
    y_lab = 'Log of hourly wage', title = 'Box plot',
    sample_size = FALSE, all_xticks = TRUE
)