scatterplotClinData: Scatterplot of variables of interest for clinical data...

In clinDataReview: Clinical Data Review Tool

Scatterplot of variables of interest for clinical data visualization.

Description

The parameters for this visualization are based on ggplot2 (aesthetic, scale, ...), parameter specification, unlike the other visualizations of the package.

Usage

scatterplotClinData(
  data,
  xVar,
  yVar,
  xLab = getLabelVar(var = xVar, labelVars = labelVars),
  xLabVar = NULL,
  yLab = getLabelVar(var = yVar, labelVars = labelVars),
  yLabVar = NULL,
  aesPointVar = list(),
  pointPars = list(),
  aesLineVar = list(),
  linePars = list(),
  lineInclude = length(aesLineVar) > 0,
  aesSmoothVar = list(),
  smoothPars = list(),
  smoothInclude = length(c(aesSmoothVar, smoothPars)) > 0,
  aesLab,
  xTrans = "identity",
  yTrans = "identity",
  xPars = list(),
  yPars = list(),
  xLabVars = NULL,
  yLim = NULL,
  xLim = NULL,
  yLimExpandData = TRUE,
  xLimExpandData = TRUE,
  title = paste(c(paste(yLab, "vs", xLab), titleExtra), collapse = "<br>"),
  titleExtra = NULL,
  caption = NULL,
  subtitle = NULL,
  facetPars = list(),
  facetType = c("wrap", "grid"),
  scalePars = list(),
  themePars = list(legend.position = "bottom"),
  refLinePars = NULL,
  labelVars = NULL,
  width = NULL,
  height = NULL,
  hoverVars,
  hoverLab,
  idVar = "USUBJID",
  idLab = getLabelVar(idVar, labelVars = labelVars),
  idHighlightBox = FALSE,
  pathVar = NULL,
  pathExpand = FALSE,
  id = paste0("plotClinData", sample.int(n = 1000, size = 1)),
  selectVars = NULL,
  selectLab = getLabelVar(selectVars, labelVars = labelVars),
  table = FALSE,
  tableVars,
  tableLab,
  tableButton = TRUE,
  tablePars = list(),
  watermark = NULL,
  verbose = FALSE
)

Arguments

data	Data.frame with input data.
xVar	String with column of data containing x-variable.
yVar	String with column of data containing y-variable.
xLab	String with label for xVar.
xLabVar	(optional) Character vector with column(s) of data containing variable(s) to display in the label of the x-axis.
yLab	String with label for xVar.
yLabVar	(optional) Character vector with column(s) of data containing variable(s) to display in the label of the y-axis.
aesPointVar	List with specification of aesthetic variable(s), for the point, passed to the mapping parameter of geom_point, e.g. list(color = "TRTP"). Please note by default symbols with fill and color are used. Color is used for the outside of the points, fill for the inside and the hover. Usually, you might want to specify both filling and coloring.
pointPars	List with parameters other than aesthetic variables to pass to geom_point, defaults to empty list.
aesLineVar	List with specification of aesthetic variable(s), for the line, passed to the mapping parameter of geom_line, e.g. list(group = "USUBJID").
linePars	List with parameters other than aesthetic variables to pass to geom_line, defaults to empty list.
lineInclude	Logical, if TRUE (by default if aesLineVar is specified) include a scatterplot.
aesSmoothVar	List with specification of aesthetic variable(s), for the smoothing layer, passed to the mapping parameter of geom_smooth defaults to empty list.
smoothPars	List with parameters other than aesthetic variables to pass to geom_smooth, defaults to empty list. Note this parameter overwrites other parameters set by aesSmoothVar.
smoothInclude	Logical, if TRUE (by default if one of aesSmoothVar or smoothPars is non-empty)
aesLab	Named character vector with labels for each aesthetic variable.
xTrans, yTrans	Transformation for the x/y- variables, passed to the trans parameter of scale_x_continuous/ scale_y_continuous.
xPars, yPars	List with extra parameters for x/y axis, passed to the scale_x_continuous/ scale_y_continuous functions, besides trans and limits.
xLabVars	Character vector with variable(s) to be displayed as the labels of the ticks in the x-axis. By default, xVar is displayed. If specified, this overwrites any labels specified via xPars. In case the variable(s) contain different elements by xVar or between facets, they are combined and displayed below each other.
xLim, yLim	Numeric vector of length 2 with limits for the x/y axes.
xLimExpandData, yLimExpandData	Logical (TRUE by default), should the limits specified via xLim/yLim be expanded to include any data points outside of these limits? Please note that the same limits are set for all facets.
title	String with title for the plot.
titleExtra	String with extra title for the plot (appended after title).
caption	String with caption. The caption is included at the bottom right of the plot. Please note that this might overlap with vertical or rotated x-axis labels.
subtitle	String with subtitle. The subtitle is included at the top left of the plot, below the title.
facetPars	List with facetting parameters, passed to the facetting function.
facetType	String with facetting type, either: 'wrap': facet_wrap 'grid': facet_grid
scalePars	List with parameters to customize scales. Each sublist should contains a set of parameters passed to the scale_discrete_manual function. If palette(s) are not specified, default palettes are used (see getColorPalette, getShapePalette, getLinetypePalette )
themePars	List with general theme parameters (see theme).
refLinePars	(optional) Nested list, with parameters for each reference line(s). Each sublist (a.k.a reference line) contains: aesthetic value(s) or variable(s) for the lines (in this case column names of data) for reference lines. The line position is controlled by the aesthetics supported in geom_vline, geom_hline and geom_abline. 'label': (optional) Logical specifying if the line should be annotated (FALSE to not annotate the line) or string with annotation label. By default, the value of the position of the horizontal/vertical line or the equation of the diagonal line is displayed.
labelVars	Named character vector containing variable labels.
width	Numeric, width of the plot in pixels, 800 by default.
height	Numeric, height of the plot in pixels, 500 by default.
hoverVars	Character vector with variables to be displayed in the hover, by default xVar, yVar and any aesthetic variables.
hoverLab	Named character vector with labels for hoverVars.
idVar	String with variable containing subject ID.
idLab	String with label for idVar.
idHighlightBox	Logical, if TRUE (FALSE by default) a selectize box is included to highlight selected element(s) of the ID variable (idVar).
pathVar	String with variable of data containing path to a subject-specific report. The report info should be unique for each element of idVar. The report will be: opened in a different window in the browser if the user clicks on the 'p' (a.k.a 'profile') key when hovering on a point of the plot opened in the browser via hyperlink in the table
pathExpand	Logical, if FALSE (by default) the path to subject-report is included in an hyperlink in the table, otherwise a collapsed row is created. This should be set to TRUE only if multiple paths are included for each row in pathVar (e.g. in case of summary table).
id	String with general id for the plot: 'id' is used as group for the SharedData 'button:[id]' is used as button ID if table is TRUE If not specified, a random id, as 'plotClinData[X]' is used.
selectVars	(optional) Character vector with variable(s) from data for which a selection box should be included. This enables to select the data displayed in the plot (and associated table).
selectLab	(Named) character vector with label for selectVars.
table	Logical, if TRUE (FALSE by default) returns also a datatable containing the plot data. The plot and table are linked when included in a Rmarkdown document: when clicking on an plot element, only the corresponding records are retained in the associated table; when some records are selected in the table, they are highlighted in the associated table.
tableVars	Character vector with variables to be included in the table.
tableLab	Named character vector with labels for each tableVars.
tableButton	Logical, if TRUE (by default) the table is included within an HTML button.
tablePars	List with parameters passed to the getClinDT function.
watermark	(optional) String with path to a file containing a watermark.
verbose	Logical, if TRUE (FALSE by default) progress messages are printed in the current console. For the visualizations, progress messages during download of subject-specific report are displayed in the browser console.

Value

Either:

• if a table is requested: a clinDataReview object, a.k.a a list with the 'plot' (plotly object) and 'table' (datatable object)

• otherwise: a plotly object

Author(s)

Laure Cougnaud

See Also

Other Clinical data visualization of individual profiles.: timeProfileIntervalPlot()

Examples

library(clinUtils)

data(dataADaMCDISCP01)
labelVars <- attr(dataADaMCDISCP01, "labelVars")

dataLB <- dataADaMCDISCP01$ADLBC
dataDM <- dataADaMCDISCP01$ADSL
dataLB <- annotateData(dataLB, annotations = list(data = dataDM))
# subset of the data for the example
dataLB <- subset(dataLB, VISIT %in% c("SCREENING 1", "WEEK 2", "WEEK 8"))

## time profile

dataPlot <- subset(dataLB, PARAMCD == "ALT")

# with relative day
scatterplotClinData(
	data = dataPlot, 
	xVar = "ADY",
	yVar = "LBSTRESN",
	aesPointVar = list(color = "TRTP", fill = "TRTP"),
	aesLineVar = list(group = "USUBJID", color = "TRTP"),
	labelVars = labelVars
)

# with actual visit
dataPlot$AVISIT <- with(dataPlot, reorder(trimws(AVISIT), AVISITN))
scatterplotClinData(
	data = dataPlot, 
	xVar = "AVISIT",
	yVar = "LBSTRESN",
	aesPointVar = list(color = "TRTP", fill = "TRTP"),
	aesLineVar = list(group = "USUBJID", color = "TRTP"),
	labelVars = labelVars
)

# add number of subjects below each visit
	
if (requireNamespace("inTextSummaryTable", quietly = TRUE)) {

# compute number of subjects by visit
summaryTable <- inTextSummaryTable::computeSummaryStatisticsTable(
	dataPlot,
	rowVar = "AVISIT",
	stats = "n"
)
# add it in the data
dataPlot <- merge(dataPlot, summaryTable[, c("AVISIT", "n")], all.x = TRUE)
dataPlot$n <- paste0("N=", dataPlot$n)

scatterplotClinData(
	data = dataPlot, 
	xVar = "AVISIT", xLabVars = c("AVISIT", "n"),
	yVar = "LBSTRESN",
	aesPointVar = list(color = "TRTP", fill = "TRTP"),
	aesLineVar = list(group = "USUBJID", color = "TRTP"),
	labelVars = labelVars
)

}

## pairwise comparison plot of two parameters of interest:

# format data long -> wide format (one column per lab param)
dataPlot <- subset(dataLB, PARAMCD %in% c("ALT", "AST"))
dataPlot <- stats::aggregate(
	LBSTRESN ~ USUBJID + VISIT + VISITNUM + PARAMCD, 
	data = dataPlot,
	FUN = mean
)
dataPlotWide <- stats::reshape(
	data = dataPlot,
	timevar = "PARAMCD", idvar = c("USUBJID", "VISIT", "VISITNUM"),
	direction = "wide"
)
colnames(dataPlotWide) <- sub("^LBSTRESN.", "", colnames(dataPlotWide))
# scatterplot per visit
scatterplotClinData(
	data = dataPlotWide, 
	xVar = "ALT", yVar = "AST",
	aesPointVar = list(color = "USUBJID", fill = "USUBJID"),
	themePars = list(legend.position = "none"),
	facetPars = list(facets = "VISIT"),
	labelVars = labelVars,
	subtitle = "Visualization is split by visit",
	caption = "Points are colored by subject ID"
)

# scatterplot with all visits, link subjects
xLab <- getLabelParamcd(paramcd = "ALT", data = dataLB, 
	paramcdVar = "PARAMCD", paramVar = "PARAM")
yLab <- getLabelParamcd(paramcd = "AST", data = dataLB, 
	paramcdVar = "PARAMCD", paramVar = "PARAM")
scatterplotClinData(
	data = dataPlotWide,
	xVar = "ALT", yVar = "AST",
	xLab = xLab,
	yLab = yLab,
	aesPointVar = list(color = "VISIT", fill = "VISIT"),
	aesLineVar = list(group = "USUBJID"),
	labelVars = labelVars
)

# scatterplot of different visits versus baseline

# add baseline as extra column:
dataPlot <- subset(dataLB, PARAMCD == "ALT")
dataPlotBL <- subset(dataPlot, VISIT == "SCREENING 1")
dataPlotBL <- dataPlotBL[with(dataPlotBL, order(USUBJID, -ADY)), ]
dataPlotBL <- dataPlotBL[!duplicated(dataPlotBL$USUBJID), ]
dataPlot$LBSTRESNBL <- dataPlot[match(dataPlot$USUBJID, dataPlotBL$USUBJID), "LBSTRESN"]

# sort visits:
dataPlot$VISIT <- with(dataPlot, reorder(VISIT, VISITNUM))

xLab <- paste(labelVars["LBSTRESN"], "for last screening visit")
yLab <- paste(labelVars["LBSTRESN"], "at visit X")
paramLab <- getLabelParamcd(paramcd = "ALT", data = dataLB, 
	paramcdVar = "PARAMCD", paramVar = "PARAM")
scatterplotClinData(
	data = dataPlot, 
	xVar = "LBSTRESNBL", xLab = xLab,
	yVar = "LBSTRESN", yLab = yLab,
	aesPointVar = list(color = "USUBJID", fill = "USUBJID"),
	aesLineVar = list(group = "USUBJID", color = "USUBJID"),
	hoverVars = c("USUBJID", "VISIT", "ADY", "LBSTRESN"),
	labelVars = labelVars,
	facetPars = list(facets = "VISIT"),
	themePars = list(legend.position = "none"),
	title = paste("Comparison of actual value of", 
		paramLab,
		"at each visit versus baseline"
	),
	refLinePars = list(
		list(slope = 1, intercept = 0, linetype = 1, color = "black", 
			label = FALSE),
		list(yintercept = "A1LO", linetype = 2, color = "blue"),
		list(yintercept = "A1HI", linetype = 2, color = "purple", 
			label = "Reference Range Upper Limit")
	)
)


## scatterplot with smoothing layer

data <- data.frame(
  USUBJID = c(rep('subj1', 20), rep('subj2', 20)),
  time = rep( 1:20 , 2 ),
  response =  c(1:20, 50:31) + runif(min =-3, max = +3, 40),
  treat =  rep(c('trA', 'trB'), 20),
  stringsAsFactors = FALSE
)

# smoothing per subject
scatterplotClinData(
  data = data,
  xVar = "time", yVar = "response",
  aesPointVar = list(color = "treat"),
  aesLineVar = list(group = 'USUBJID'),
  linePars = list(linetype='dotted'),
  aesSmoothVar = list(color='USUBJID', group='USUBJID'), 
  smoothPars =  list(alpha=0.5, size=0.3 , se=TRUE, color = 'black')
)


# plot smoothing over subjects
scatterplotClinData(
  data = data,
  xVar = "time", yVar = "response",
  aesPointVar = list(color = "treat"),
  aesLineVar = list(group = 'USUBJID'),
  linePars = list(linetype='dotted'),
  aesSmoothVar = list(), 
  smoothPars =  list(alpha=0.5, size=0.3 , se=TRUE, color = 'black')
)

# add a selection box
if(interactive()){
  dataPlot <- subset(dataLB, PARAMCD == "ALT")
  dataPlot$TRTA <- with(dataPlot, reorder(TRTA, TRTAN))
  scatterplotClinData(
    data = dataPlot, 
    xVar = "ADY",
    yVar = "LBSTRESN",
    aesPointVar = list(fill = "TRTA", color = "TRTA"),
    aesLineVar = list(group = "USUBJID", color = "TRTA"),
    selectVars = "TRTA",
    labelVars = labelVars
  )
}

clinDataReview documentation built on April 12, 2025, 1:14 a.m.