subjectProfileLinePlot {patientProfilesVis}

Visualize subject profiles of the evolution of continuous parameters versus time (spaghetti plot).

Description

Visualize subject profiles of the evolution of continuous parameters versus time (spaghetti plot).

Usage

subjectProfileLinePlot(
  data,
  paramValueVar,
  paramLab = getLabelVar(paramValueVar, labelVars = labelVars),
  paramNameVar = NULL,
  paramVarSep = " - ",
  paramValueRangeVar = NULL,
  colorValueRange = "lightgreen",
  yLimFrom = c("all", "value"),
  colorVar = NULL,
  colorLab = getLabelVar(colorVar, labelVars = labelVars),
  colorPalette = NULL,
  shapeVar = colorVar,
  shapeLab = if (isTRUE(colorVar == shapeVar)) {
     colorLab
 } else
    getLabelVar(shapeVar, labelVars = labelVars),
  shapePalette = NULL,
  paramGroupVar = NULL,
  timeVar,
  timeLab = getLabelVar(timeVar, labelVars = labelVars),
  timeTrans = NULL,
  timeExpand = NULL,
  subjectVar = "USUBJID",
  subjectSubset = NULL,
  subjectSample = NULL,
  seed = 123,
  subsetData = NULL,
  subsetVar = NULL,
  subsetValue = NULL,
  xLab = timeLab,
  yLab = "",
  timeLim = NULL,
  title = toString(getLabelVar(paramValueVar, labelVars = labelVars, label = paramLab)),
  label = title,
  labelVars = NULL,
  formatReport = subjectProfileReportFormat(),
  paging = TRUE,
  alpha = 1,
  shapeSize = rel(1)
)

Arguments

data

Data.frame with data.

paramValueVar

String, variable of data with parameter value to represent.
Records with missing values are discarded.

paramLab

Named character vector, with label for the parameter variable(s) (paramNameVar).
This is used to set the default title.

paramNameVar

Character vector with variable(s) of data with parameter name. If multiple, they are concatenated with paramVarSep.

paramVarSep

string with character(s) used to concatenate multiple paramNameVar, ' - ' by default.

paramValueRangeVar

Character vector of length 2 containing variables of data with minimum and maximum value for paramValueVar, typically reference range indicators.
Range can differ per parameter and even per time point. This range is represented as a ribbon in the plot background. e.g. to represent the reference range of the variable.

colorValueRange

String with color for the filling of the ribbon represented by paramValueRangeVar.

yLimFrom

String with specification on the limits of the y-axis, either:

• 'all' (by default): for each parameter (paramNameVar), the y-axis range contains the minimum/maximum value of the reference range (paramValueRangeVar) or data

• 'value': for each parameter (paramNameVar), the y-axis minimum/maximum value is restricted to the data range only. Please note that the ribbon visualizing the reference range is also restricted to the data range if wider.

colorVar

String, variable of data with color. This variable is used for the colors and the filling of the points.

colorLab

String, label for colorVar.

colorPalette

Named vector with color palette. The variable should be named with the corresponding element in colorVar.
Colors can also be defined for the entire session, by setting options(patientProfilesVis.colors = X) with X either:

• a vector with colors

• a function returning a vector of colors for a specified number of elements (viridis by default)

shapeVar

String, variable of data for shape of the points. By default, same as colorVar.

shapeLab

String, label for shapeVar. Set by default to colorLab if colorVar but not shapeVar is not specified.

shapePalette

Named character vector with shape palette for shapeVar. The variable should be named with the corresponding element in shapeVar.
Shapes can also be defined for the entire session, by setting options(patientProfilesVis.shapes = X) with X either:

• a vector with shapes

• a function returning a vector of shapes for a specified number of elements

Note it is advised to specify the shapes as character, e.g. 'cross' instead of 4, in case Unicode symbols should also be used.

paramGroupVar

(optional) Character vector with variable(s) of data based on which the data will be grouped and sorted (in the y-axis) in the plot.

timeVar

String, variable of data with time, displayed in the x axis.
Records with missing time are not displayed in the plot.

timeLab

String, label for timeVar. This is used in the message indicating missing values for timeVar, and for the default label of the x-axis.

timeTrans

transformation for the time variable, (see trans parameter in scale_x_continuous, and trans_new). For example, produced by the getTimeTrans function.

timeExpand

Vector of range expansion constants for the time axis (see expand parameter in scale_x_continuous).

subjectVar

String, variable of data with subject ID

subjectSubset

(optional) Character vector with subjects of interest (available in subjectVar), NULL by default.

subjectSample

(optional) Integer of length 1 with number of random subject(s) that should be considered, e.g. to check the created patient profiles for a subset of the data. By default, all specified subjects are considered (set to NULL).

seed

(optional) Integer of length 1 with seed used to select random subjects if subjectSample is specified (123 by default).

subsetData

(optional) Data.frame with extra dataset to filter on. This dataset is filtered, and only records from data with common subject IDs will be retained.
If not specified, data is used.

subsetVar

(optional) String with variable of subset data to filter on. subsetValue should be specified too.
If not specified, all records from the subset data are retained.

subsetValue

(optional) Character vector with value(s) of interest to retain in the filtered data. These values should be available in subsetVar.
Missing values in the subject variable are not retained in the filtered data.

xLab

String, label for the x-axis.

yLab

String, label for the y-axis.

timeLim

(optional) Vector of length 2 with time limits (x-axis). If not specified, these are extracted from the minimum timeStartVar and maximum timeEndVar per subject.
The time limits are stored as attributes of the plots, used to align the plots in the final report.

title

String with title, label of the parameter value variable by default.

label

String, label for the visualization. This label is stored as attributes of the output from the subjectProfile[]Plot function.
This label is displayed in the final profile report, in case no data is available for for a specific patient, as: 'No [label] available.'

labelVars

Named character vector with variable labels (names are the variable code)

formatReport

list with parameters used to specify the format of the report, e.g. output of the subjectProfileReportFormat function

paging

Logical, if TRUE (by default), automatic paging is enabled, so patient profiles module too big to fit in one page will span multiple pages. Please note that the size of the graphic window (or report page) may need to be re-sized in order that the plot fits.
If FALSE, the entire plot is included in one single page.

alpha

Numeric with transparency, 1 by default.

shapeSize

Size for the symbols, any integer or object supported by size in geom_point.

Value

List of (across subjects) of list (across modules) of ggplot2 objects, also of class subjectProfileLinePlot. Each subject profile contains attributes: 'subjectID' and 'nLines' (estimated number of lines of space the plot will take). The entire list also contains attributes: 'label', 'timeLim' and 'timeTrans' (if specified).

Author(s)

Laure Cougnaud

See Also

Other patient profiles plotting function: subjectProfileEventPlot(), subjectProfileIntervalPlot(), subjectProfileTextPlot()