Help for package swimplot

Title:

Tools for Creating Swimmers Plots using 'ggplot2'

Description:

Used for creating swimmers plots with functions to customize the bars, add points, add lines, add text, and add arrows.

Version:

1.2.0

License:

GPL-3

Author:

Jessica Weiss <jessica.weiss@uhnresearch.ca>, Wei Xu<Wei.Xu@uhnresearch.ca>

Maintainer:

Jessica Weiss <jessica.weiss@uhnresearch.ca>

Imports:

tidyr, dplyr, ggplot2,

LazyData:

true

RoxygenNote:

7.1.1

Encoding:

UTF-8

Suggests:

knitr, rmarkdown, testthat

VignetteBuilder:

knitr

NeedsCompilation:

Packaged:

2021-03-28 20:15:42 UTC; jweiss

Depends:

R (≥ 3.5.0)

Repository:

CRAN

Date/Publication:

2021-03-31 00:00:02 UTC

Clinical Trial: Adverse events

Description

A dataset containing the adverse event information from a simulated clinical trial

Usage

ClinicalTrial.AE

Format

A data frame with 11 rows and 6 variables:

id: Patient id
time: Time of an adverse event (AE)
event: Type of adverse event (AE)
Sex: Patient Sex
Age: Age of patient at trial entry date
Related: Likelihood the treatment is related to the adverse event

Clinical Trial: Treatment

Description

A dataset containing the treatment arm information from a simulated clinical trial

Usage

ClinicalTrial.Arm

Format

A data frame with 53 rows and 6 variables:

id: Patient id
Arm: Treatment Arm
End_trt: Time since enrollment to the end of treatment, in months
Continued_treatment: Continued treatment past end of follow up
Sex: Patient Sex
Age: Age of patient at trial entry date

Clinical Trial: Response

Description

A dataset containing the response information from a simulated clinical trial

Usage

ClinicalTrial.Response

Format

A data frame with 36 rows and 7 variables:

id: Patient id
Response_start: Time of starting response, in months since enrollment
Response_end: Time of ending response, in months since enrollment
Response: Type of response, CR = Complete response, and PR = Partial response
Continued_response: Continued response past end of follow up
Sex: Patient Sex
Age: Age of patient at trial entry date

Clinical Trial: Stage

Description

A dataset containing the Stage information from a simulated clinical trial

Usage

ClinicalTrial.Stage

Format

A data frame with 36 rows and 2 variables:

id: Patient id
Stage: Patients clinical stage at enrollment of the study (either Early Stage or Late Stage)

Formats a dataframe of line to add points

Description

This function formats a dataframe; used with swimmer_lines

Usage

line_df_to_point_df(df_lines, start = "start", end = "end", cont = NULL)

Arguments

df_lines

a dataframe

start

start column name

end

end column name

cont

continue column name

Value

a dataframe in a format for adding points to a swimmers plot

Adding arrows to a swimmers plot

Description

This function allows you to add arrows to a swimmers plot created with swimmer_plot

Usage

swimmer_arrows(
  df_arrows,
  id = "id",
  arrow_start = "end",
  cont = NULL,
  adj.y = 0,
  name_col = NULL,
  arrow_positions = c(0.1, 1),
  angle = 30,
  length = 0.1,
  type = "closed",
  ...
)

Arguments

df_arrows

a data frame

id

column name for id, default is 'id'

arrow_start

column name with the arrow locations default is "end"

cont

a column name including an indicator of which ids have an arrow (NA is no arrow); when NULL will use all use all of df_arrows

adj.y

amount to adjust the line within the box vertically (default is 0, line is in the centre of each bar)

name_col

a column name to map the arrow colour

arrow_positions

a vector of the distance from the arrow start to end, default is c(0.1,1)

angle

the angle of the arrow head in degrees (smaller numbers produce narrower, pointier arrows). Essentially describes the width of the arrow head. Default is 30

length

a unit specifying the length of the arrow head (from tip to base in inches (default is 0.1)'

type

one of "open" or "closed" indicating whether the arrow head should be a closed triangle. Default is 'closed'

...

additional geom_segment() arguments

Value

a swimmer plot with arrows

Examples


#Mapping the arrows to the bars




swim_plot <-
swimmer_plot(df=ClinicalTrial.Arm,id='id',end='End_trt',name_fill='Arm',col="black",id_order
= 'Arm')



swim_plot_with_arrows <- swim_plot+
swimmer_arrows(df_arrows=ClinicalTrial.Arm,id='id',arrow_start='End_trt',
cont = 'Continued_treatment',name_col='Arm',show.legend = FALSE,type =
"open",cex=1.25)



 swim_plot_with_arrows+
ggplot2::scale_color_manual(name="Treatment",values=c("#e41a1c", "#377eb8","#4daf4a"),drop=FALSE)+
ggplot2::scale_fill_manual(name="Treatment",values=c("#e41a1c", "#377eb8","#4daf4a"))+
ggplot2::ylab('Time (Days)')






#Mapping the arrows to lines

#Start with a base swimmer plot with lines and points


swim_plot <-
swimmer_plot(df=ClinicalTrial.Arm,id='id',end='End_trt',name_fill='Arm',col="black",id_order
= 'Arm')+ swimmer_lines(df_lines=ClinicalTrial.Response,id='id',start =
'Response_start',end='Response_end',name_col='Response',size=3)+
swimmer_points_from_lines(df_lines=ClinicalTrial.Response,id='id',start =
'Response_start',end = 'Response_end',cont =
'Continued_response',name_col='Response',size=4)


# Then add arrows to the plot

  swim_plot_with_arrows <- swim_plot+
swimmer_arrows(df_arrows=ClinicalTrial.Response,id='id',arrow_start='Response_end',
cont = 'Continued_response',name_col='Response',show.legend = FALSE,type =
"open",cex=1.25)


# Add ggplot layers to improve the plot's aesthetic

swim_plot_with_arrows+
ggplot2::scale_color_manual(name="Response",values=c("grey20","grey80"))+
ggplot2::scale_fill_manual(name="Treatment",values=c("#e41a1c", "#377eb8","#4daf4a"))+
ggplot2::ylab('Time (Days)')+
ggplot2::guides(fill = ggplot2::guide_legend(override.aes = list(shape =
NA)))+
ggplot2::scale_shape_manual(name='',values=c(17,15),breaks =
c('Response_start','Response_end'),labels=c('Response Start','Response End'))

Adding lines to a swimmers plot

Description

This function allows you to add lines to a swimmers plot created with swimmer_plot

Usage

swimmer_lines(
  df_lines,
  id = "id",
  start = "start",
  end = "end",
  adj.y = 0,
  name_linetype = NULL,
  name_col = NULL,
  name_size = NULL,
  name_alpha = NULL,
  ...
)

Arguments

df_lines

a data frame

id

column name for id, default is 'id'

start

column name with the line start locations

end

column name with the line end locations

adj.y

amount to adjust the line within the box vertically (default is 0, line is in the centre of each bar)

name_linetype

a column name to map the line type

name_col

a column name to map the line colour

name_size

a column name to map the line size

name_alpha

a column name to map the line transparency

...

additional geom_segment() arguments

Value

a swimmer plot with lines

Examples



#Start with a base swimmer plot
swim_plot <-
swimmer_plot(df=ClinicalTrial.Arm,id='id',end='End_trt',name_fill='Arm',col="black",id_order='Arm')


# Then add lines to the plot

swim_plot_with_lines <- swim_plot +
swimmer_lines(df_lines=ClinicalTrial.Response,id='id',start =
'Response_start',end='Response_end',name_col='Response',size=3)


# Add ggplot layers to improve the plot's aesthetic

swim_plot_with_lines +
ggplot2::scale_color_manual(name="Response",values=c("grey20","grey80"))+
ggplot2::scale_fill_manual(name="Treatment",values=c("#e41a1c", "#377eb8","#4daf4a"))+
ggplot2::ylab('Time (Days)')

Creating the base of a swimmers plot

Description

This function allows you to create swimmers plots with bars, includes options to have the bars change colours and create stratified plots

Usage

swimmer_plot(
  df,
  id = "id",
  end = "end",
  start = "start",
  name_fill = NULL,
  name_col = NULL,
  name_alpha = NULL,
  increasing = TRUE,
  id_order = NULL,
  stratify = FALSE,
  base_size = 11,
  identifiers = TRUE,
  ...
)

Arguments

df

a data frame

id

column name for id, default is 'id'

end

column name with the bar lengths (or bar end positions if bars change colour), default is 'end'

start

column name with the bar start positions (only required when there are gaps between sections of bars, or bars which do not start at zero), default is 'start'

name_fill

a column name to map the bar fill

name_col

a column name to map the bar colour

name_alpha

a column name to map the bar transparency

increasing

Binary to specify bars in increasing order (Default is TRUE)

id_order

order of the bars by id, can input a column name to sort by, or the ids in order.

stratify

a list of column names to stratify by

base_size

the base size for the plot, default is 11

identifiers

Binary to specify patient identifiers are included in the y axis (default is TRUE)

...

additional geom_col() arguments

Value

a swimmer plot with bars

Examples





swim_plot <-
swimmer_plot(df=ClinicalTrial.Arm,id='id',end='End_trt',name_fill='Arm',col="black",id_order='Arm')

# Add ggplot layers to improve the plot's aesthetic

swim_plot +
ggplot2::scale_fill_manual(name="Treatment",values=c("#e41a1c", "#377eb8","#4daf4a"))+
ggplot2::ylab('Time (Days)')



#Example with Stratification

swim_plot_stratify <- swimmer_plot(df=ClinicalTrial.Arm,id='id',end='End_trt',name_fill='Arm',
col="black",alpha=0.75,width=.8,base_size = 18,stratify= c('Age','Sex'))

swim_plot_stratify +
ggplot2::scale_fill_manual(name="Treatment",values=c("#e41a1c", "#377eb8","#4daf4a"))+
ggplot2::ylab('Time (Days)')

#Example when there are gaps between the bars and bars do not start at zero

#Both a start and end time need to be specified when there are gaps between sections of bars

Gap_data <- data.frame(patient_ID=c('ID:3','ID:1','ID:1','ID:1','ID:2',
                                   'ID:2','ID:2','ID:3','ID:3','ID:2'),
                      start=c(10,1,2,7,2,10,14,5,0,22),
                      end=c(20,2,4,10,7,14,22,7,3,26),
                      treatment=c("A","B","C","A","A","C","A","B","C",NA))

swimmer_plot(df=Gap_data,id='patient_ID',name_fill="treatment",col=1,identifiers=FALSE,
id_order = c('ID:1','ID:2','ID:3')) +
ggplot2::theme_bw()+ggplot2::scale_fill_manual(name="Treatment",
values=c("A"="#e41a1c", "B"="#377eb8","C"="#4daf4a",na.value=NA),breaks=c("A","B","C"))+
 ggplot2::scale_y_continuous(breaks=c(0:26))

Adding points to a swimmers plot

Description

This function allows you to add points to a swimmers plot created with swimmer_plot

Usage

swimmer_points(
  df_points,
  id = "id",
  time = "time",
  adj.y = 0,
  name_shape = NULL,
  name_col = NULL,
  name_size = NULL,
  name_fill = NULL,
  name_stroke = NULL,
  name_alpha = NULL,
  ...
)

Arguments

df_points

a data frame

id

column name for id, default is 'id'

time

column name with the point locations

adj.y

amount to adjust the point within the box vertically (default is 0, point is in the centre of each bar)

name_shape

a column name to map the point shape

name_col

a column name to map the point colour

name_size

a column name to map the point size

name_fill

a column name to map the point fill

name_stroke

a column name to map the point stroke

name_alpha

a column name to map the point transparency

...

additional geom_point() arguments

Value

a swimmer plot with points

Examples




#Start with a base swimmer plot

swim_plot <-
 swimmer_plot(df=ClinicalTrial.Arm,id='id',end='End_trt',name_fill='Arm',col="black",id_order='Arm')


# Then add points to the plot

swim_plot_with_points <- swim_plot + swimmer_points(df_points=
ClinicalTrial.AE,id='id',time='time',name_shape =
'event',size=3,fill='white',col='black')



# Add ggplot layers to improve the plot's aesthetic

swim_plot_with_points + ggplot2::scale_shape_manual(name="Adverse
event",values=c(21,24,17),breaks=c('AE','SAE','Death'))+
ggplot2::scale_fill_manual(name="Treatment",values=c("#e41a1c", "#377eb8","#4daf4a"))+
ggplot2::ylab('Time (Days)')



##Another example with the colour and shape mapped to different columns

#Start with a base swimmer plot

swim_plot <-
 swimmer_plot(df=ClinicalTrial.Arm,id='id',end='End_trt',name_fill='Arm',col="black",id_order='Arm')


swim_plot +
 swimmer_points(df_points=ClinicalTrial.AE,id='id',time='time',name_shape =
                 'event',fill='white',name_col = 'Related',size=5)+
 ggplot2::scale_shape_manual(name="Adverse event",values=c(16,17,18),breaks=c('AE','SAE','Death'))+
 ggplot2::scale_fill_manual(name="Treatment",values=c("#e41a1c", "#377eb8","#4daf4a"))+
 ggplot2::ylab('Time (Days)') +
 ggplot2::scale_color_manual(name="Likelihood related to treatment",values=c(1,'grey52','grey90'))

Adding points to a swimmers plot which match up with lines

Description

This function will create points at the beginning and end of line to match with swimmer_lines.

Usage

swimmer_points_from_lines(
  df_lines,
  id = "id",
  start = "start",
  end = "end",
  cont = NULL,
  adj.y = 0,
  name_shape = "type",
  name_col = NULL,
  name_size = NULL,
  name_fill = NULL,
  name_stroke = NULL,
  name_alpha = NULL,
  ...
)

Arguments

df_lines

a data frame

id

column name for id, default is 'id'

start

column name where the line starts, default is 'start'

end

column name where the line ends, default is 'end'

cont

a column name of which lines continue (NA is does not continue) these will not have a point at the end of the line

adj.y

amount to adjust the point within the box vertically (default is 0, point is in the centre of each bar)

name_shape

a column name to map the point shape

name_col

a column name to map the point colour

name_size

a column name to map the point size

name_fill

a column name to map the point fill

name_stroke

a column name to map the point stroke

name_alpha

a column name to map the point transparency

...

additional geom_point() arguments

Value

a swimmer plot with points matching the lines

Examples



#Start with a base swimmer plot


swim_plot <-swimmer_plot(df=ClinicalTrial.Arm,id='id',end='End_trt',name_fill='Arm',col="black"
,id_order= 'Arm')


# Then add lines to the plot

swim_plot_with_lines <- swim_plot +
swimmer_lines(df_lines=ClinicalTrial.Response,id='id',start =
'Response_start',end='Response_end',name_col='Response',size=3)

# Add points to the start and end of the lines

swim_plot_with_lines_and_points <- swim_plot_with_lines+
swimmer_points_from_lines(df_lines=ClinicalTrial.Response,id='id',start =
'Response_start',end = 'Response_end', cont =
'Continued_response',name_col='Response',size=4)

# Add ggplot layers to improve the plot's aesthetic

swim_plot_with_lines_and_points +
ggplot2::scale_color_manual(name="Response",values=c("grey20","grey80"))+
ggplot2::scale_fill_manual(name="Treatment",values=c("#e41a1c", "#377eb8","#4daf4a"))+
ggplot2::ylab('Time (Days)')+
ggplot2::guides(fill = ggplot2::guide_legend(override.aes = list(shape =
NA)))+
ggplot2::scale_shape_manual(name='',values=c(17,15),breaks =
c('Response_start','Response_end'),labels=c('Response Start','Response End'))

Adding text to a swimmers plot

Description

This function allows you to add text to a swimmers plot created with swimmer_plot

Usage

swimmer_text(
  df_text,
  id = "id",
  start = "start",
  label = "label",
  name_col = NULL,
  name_size = NULL,
  name_alpha = NULL,
  name_fontface = NULL,
  adj.y = 0,
  adj.x = 0,
  ...
)

Arguments

df_text

a data frame

id

column name for id, default is 'id'

start

column name with the text start locations (if there is no start column will default 0 for all text)

label

a column with the text to be added to the plot

name_col

a column name to map the text colour

name_size

a column name to map the text size

name_alpha

a column name to map the text transparency

name_fontface

a column name to map the text fontface ("plain", "bold", "italic", "bold.italic" can all be used)

adj.y

amount to adjust the text within the box vertically (default is 0, text is in the centre of each bar)

adj.x

amount to adjust the text within the box horizontally (default is 0, text starts at the origin)

...

additional geom_text() arguments

Value

a swimmer plot with text on the bars

Examples

#Start with a base swimmer plot

swim_plot <-
 swimmer_plot(df=ClinicalTrial.Arm,id='id',end='End_trt',
 name_fill='Arm',col="black",id_order='Arm',alpha=0.6)


# Then add text to the plot



swim_plot_with_text <- swim_plot +   swimmer_text(df_text =
ClinicalTrial.Stage,label = 'Stage',size=3,
fontface=ifelse(ClinicalTrial.Stage$Stage=="Early Stage","bold","plain"))


# Add ggplot layers to improve the plot's aesthetic

swim_plot_with_text +
ggplot2::scale_fill_manual(name="Treatment",values=c("#e41a1c", "#377eb8","#4daf4a"))+
ggplot2::ylab('Time (Days)')

Clinical Trial: Adverse events

Description

Usage

Format

Clinical Trial: Treatment

Description

Usage

Format

Clinical Trial: Response

Description

Usage

Format

Clinical Trial: Stage

Description

Usage

Format

Formats a dataframe of line to add points

Description

Usage

Arguments

Value

Adding arrows to a swimmers plot

Description

Usage

Arguments

Value

See Also

Examples

Adding lines to a swimmers plot

Description

Usage

Arguments

Value

See Also

Examples

Creating the base of a swimmers plot

Description

Usage

Arguments

Value

See Also

Examples

Adding points to a swimmers plot

Description

Usage

Arguments

Value

See Also

Examples

Adding points to a swimmers plot which match up with lines

Description

Usage

Arguments

Value

See Also

Examples

Adding text to a swimmers plot

Description

Usage

Arguments

Value

See Also

Examples