plot method for objects of class popTime

Create a data frame for population time plots to give a visual representation of incidence density

# S3 method for popTime
plot(
  x,
  ...,
  xlab = "Follow-up time",
  ylab = "Population",
  add.case.series = TRUE,
  add.base.series = FALSE,
  add.competing.event = FALSE,
  casebase.theme = TRUE,
  ribbon.params = list(),
  case.params = list(),
  base.params = list(),
  competing.params = list(),
  color.params = list(),
  fill.params = list(),
  theme.params = list(),
  facet.params = list(),
  ratio = 1,
  censored.indicator,
  comprisk = FALSE,
  legend = TRUE,
  ncol,
  legend.position,
  line.width,
  line.colour,
  point.size,
  point.colour
)

popTime(data, time, event, censored.indicator, exposure, percentile_number)

checkArgsTimeEvent(data, time, event)

Arguments

x

an object of class popTime or popTimeExposure.

...

Ignored.

xlab, ylab

The title of the respective axis. Default: 'Follow-up time' for xlab and 'Population' for ylab

add.case.series

Logical indicating if the case series should be added to the plot. Default: TRUE

add.base.series

Logical indicating if the base series should be added to the plot. Default: FALSE

add.competing.event

Logical indicating if the competing event should be added to the plot. Default: FALSE

casebase.theme

Logical indication if the casebase theme be used. The casebase theme uses theme_minimal. Default: TRUE.

ribbon.params

A list containing arguments that are passed to geom_ribbon which is used to plot the population-time area. These arguments will override the function defaults. For example, you can set ribbon.params = list(colour = 'green') if you want the area to be green.

case.params, base.params, competing.params

A list containing arguments that are passed to geom_point which is used to plot the case series, base series, competing events. These arguments will override the function defaults. For example, you can set case.params = list(size = 1.5) if you want to increase the point size for the case series points. Note: do not use this argument to change the color of the points. Doing so will result in unexpected results for the legend. See the color.params and fill.params arguments, if you want to change the color of the points.

color.params

A list containing arguments that are passed to scale_color_manual which is used to plot the legend. Only used if legend=TRUE. These arguments will override the function defaults. Use this argument if you want to change the color of the points. See examples for more details.

fill.params

A list containing arguments that are passed to scale_fill_manual which is used to plot the legend. Only used if legend=TRUE. These arguments will override the function defaults. Use this argument if you want to change the color of the points. See examples for more details.

theme.params

A list containing arguments that are passed to theme. For example theme.params = list(legend.position = 'none').

facet.params

A list containing arguments that are passed to facet_wrap which is used to create facet plots. Only used if plotting exposure stratified population time plots. These arguments will override the function defaults.

ratio

If add.base.series=TRUE, integer, giving the ratio of the size of the base series to that of the case series. This argument is passed to the sampleCaseBase function. Default: 10.

censored.indicator

a character string of length 1 indicating which value in event is the censored. This function will use relevel to set censored.indicator as the reference level. This argument is ignored if the event variable is a numeric

comprisk

If add.base.series=TRUE, logical indicating whether we have multiple event types and that we want to consider some of them as competing risks. This argument is passed to the sampleCaseBase function. Note: should be TRUE if your data has competing risks, even if you don't want to add competing risk points (add.competing.event=FALSE). Default: FALSE

legend

Logical indicating if a legend should be added to the plot. Note that if you want to change the colors of the points, through the color.params and fill.params arguments, then set legend=TRUE. If you want to change the color of the points but not have a legend, then set legend=TRUE and theme.params = list(legend.position = 'none'. Default: FALSE

ncol

Deprecated. Use facet.params instead.

legend.position

Deprecated. Specify the legend.position argument instead in the theme.params argument. e.g. theme.params = list(legend.position = 'bottom').

line.width

Deprecated.

line.colour

Deprecated. specify the fill argument instead in ribbon.params. e.g. ribbon.params = list(fill = 'red').

point.size

Deprecated. specify the size argument instead in the case.params or base.params or competing.params argument. e.g. case.params = list(size = 1.5).

point.colour

Deprecated. Specify the values argument instead in the color.params and fill.params argument. See examples for details.

data

a data.frame or data.table containing the source dataset.

time

a character string giving the name of the time variable. See Details.

event

a character string giving the name of the event variable contained in data. See Details. If event is a numeric variable, then 0 needs to represent a censored observation, 1 needs to be the event of interest. Integers 2, 3, ... and so on are treated as competing events. If event is a factor or character and censored.indicator is not specified, this function will assume the reference level is the censored indicator

exposure

a character string of length 1 giving the name of the exposure variable which must be contained in data. Default is NULL. This is used to produced exposure stratified plots. If an exposure is specified, popTime returns an exposure attribute which contains the name of the exposure variable in the dataset. The plot method for objects of class popTime will use this exposure attribute to create exposure stratified population time plots.

percentile_number

Default=0.5. Give a value between 0-1. if the percentile number of available subjects at any given point is less than 10, then sample regardless of case status. Depending on distribution of survival times and events event points may not be evenly distributed with default value.

Value

The methods for plot return a population time plot, stratified by exposure status in the case of popTimeExposure. Note that these are ggplot2 objects and can therefore be used in subsequent ggplot2 type plots. See examples and vignette for details.

An object of class popTime (or popTimeExposure if exposure is specified), data.table and data.frame in this order! The output of this function is to be used with the plot method for objects of class popTime or of class popTimeExposure, which will produce population time plots. This dataset augments the original data with the following columns:

original.event

value of the event variable in the original dataset - the one specified by the event user argument to this function

time

renames the user specified time column to time

event

renames the user specified event argument to event

Details

This function leverages the ggplot2 package to build population time plots. It builds the plot by adding layers, starting with a layer for the area representing the population time. It then sequentially adds points to the plots to show the casebase sampling mechanism. This function gives user the flexibility to add any combination of the case.series, base.series and competing events. The case series and competing events are sampled at random vertically on the plot in order to visualise the incidence density using the popTime function. That is, imagine we draw a vertical line at a specific event time. We then plot the point at a randomly sampled y-coordinate along this vertical line. This is done to avoid having all points along the upper edge of the plot (because the subjects with the least amount of observation time are plotted at the top of the y-axis). By randomly distributing them, we can get a better sense of the incidence density. The base series is sampled horizontally on the plot using the sampleCaseBase function.

It is assumed that data contains the two columns corresponding to the supplied time and event variables. If either the time or event argument is missing, the function looks for columns that contain the words "time", "event", or "status" in them (case insensitive). The function first looks for the time variable, then it looks for the event variable. This order of operation is important if for example the time variable is named "event time" and the event variable is named "event indicator". This function will first (automatically) find the time variable and remove this as a possibility from subsequent searches of the event variable. The following regular expressions are used for the time and event variables:

time

"[\s\W_]+time|^time\b"

event

"[\s\W_]+event|^event\b|[\s\W_]+status|^status\b"

This allows for "time" to be preceded or followed by one or more white space characters, one or more non-word characters or one or more underscores. For example, the following column names would be recognized by the function as the "time" variable: "time of death", "death_time", "Time", "time", "diagnosis_time", "time.diag", "diag__time". But the following will not be recognized: "diagtime","eventtime", "Timediag"

Examples

# change color of points
library(ggplot2)
data("bmtcrr")
popTimeData <- popTime(data = bmtcrr, time = "ftime", event = "Status")
fill_cols <- c("Case series" = "black", "Competing event" = "#009E73",
               "Base series" = "#0072B2")
color_cols <- c("Case series" = "black", "Competing event" = "black",
                "Base series" = "black")

plot(popTimeData,
  add.case.series = TRUE,
  add.base.series = TRUE,
  add.competing.event = FALSE,
  legend = TRUE,
  comprisk = TRUE,
  fill.params = list(
    name = element_blank(),
    breaks = c("Case series", "Competing event", "Base series"),
    values = fill_cols
  ),
  color.params = list(
    name = element_blank(),
    breaks = c("Case series", "Competing event", "Base series"),
    values = color_cols
  )
)

data("bmtcrr")
popTimeData <- popTime(data = bmtcrr, time = "ftime")
#> 'Status' will be used as the event variable
class(popTimeData)
#> [1] "popTime"    "data.table" "data.frame"
popTimeData <- popTime(data = bmtcrr, time = "ftime", exposure = "D")
#> 'Status' will be used as the event variable
attr(popTimeData, "exposure")
#> [1] "D"