subjectProfileIntervalPlot {patientProfilesVis}

Visualize time interval in subject profiles, so event with a start and end time.

Description

Visualize time interval in subject profiles, so event with a start and end time.

Usage

subjectProfileIntervalPlot(
  data,
  paramVar,
  paramVarSep = " - ",
  paramLab = getLabelVar(paramVar, labelVars = labelVars),
  paramGroupVar = NULL,
  timeStartVar,
  timeStartLab = getLabelVar(timeStartVar, labelVars = labelVars),
  timeEndVar,
  timeEndLab = getLabelVar(timeEndVar, labelVars = labelVars),
  timeLab = toString(c(timeStartLab, timeEndLab)),
  subjectVar = "USUBJID",
  subjectSubset = NULL,
  subjectSample = NULL,
  seed = 123,
  subsetData = NULL,
  subsetVar = NULL,
  subsetValue = NULL,
  timeImpType = c("minimal", "data-based", "none"),
  timeLim = NULL,
  timeLimData = NULL,
  timeLimStartVar = NULL,
  timeLimStartLab = getLabelVar(timeLimStartVar, labelVars = labelVars),
  timeLimEndVar = NULL,
  timeLimEndLab = getLabelVar(timeLimEndVar, labelVars = labelVars),
  timeTrans = NULL,
  timeExpand = NULL,
  timeAlign = TRUE,
  xLab = timeLab,
  yLab = "",
  colorVar = NULL,
  colorLab = getLabelVar(colorVar, labelVars = labelVars),
  colorPalette = NULL,
  alpha = 1,
  timeStartShapeVar = NULL,
  timeEndShapeVar = NULL,
  shapePalette = NULL,
  shapeLab = toString(unique(getLabelVar(c(timeStartShapeVar, timeEndShapeVar), labelVars
    = labelVars))),
  shapeSize = rel(3),
  title = toString(getLabelVar(paramVar, labelVars = labelVars, label = paramLab)),
  label = title,
  caption,
  labelVars = NULL,
  formatReport = subjectProfileReportFormat(),
  paging = TRUE
)

Arguments

data

Data.frame with data.

paramVar

Character vector with variable(s) of data with parameters. Variable content is displayed in the y-axis.

paramVarSep

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

paramLab

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

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.

timeStartVar

String, variable of data with start of time interval.

timeStartLab

String, label for timeStartVar, displayed in a message and in the plot caption.

timeEndVar

String, variable of data with end of time interval.

timeEndLab

String, label for timeEndVar, displayed in a message and in the plot caption.

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.

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.

timeImpType

String with imputation type: 'minimal' (default), 'data-based' or 'none', see section: 'Time interval representation'.
This imputation type is not used if a dataset used to impute time is specified.

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.

timeLimData

Data.frame with data used to impute time in case some time records are missing in data, see section: 'Time interval representation'.

timeLimStartVar

String, variable of timeLimData with start of the time interval.

timeLimStartLab

String, label for timeLimeStartVar, displayed in a message and in the plot caption.

timeLimEndVar

String, variable of timeLimData with end of the time interval.

timeLimEndLab

String, label for timeLimEndVar, displayed in a message and in the plot caption.

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).

timeAlign

Logical, if TRUE (by default) the different plots are horizontally aligned. If set to FALSE, each plot has its own time-limits.
If set to FALSE, this is not compatible with the specification of timeLim.

xLab

String, label for the x-axis.

yLab

String, label for the y-axis.

colorVar

String, variable of data with color, used both for the point(s) and segment(s).

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)

alpha

Numeric with transparency, 1 by default.

timeStartShapeVar

(optional) String, variable of data used for the shape of the symbol displayed at the start of the time interval.
If not specified, default shape palette is used, see section 'Time interval representation'.

timeEndShapeVar

String, variable of data used for the shape of the symbol displayed at the end of the time interval. If not specified, default shape palette is used, see section 'Time interval representation'.

shapePalette

Named vector with (combined) shape palette for timeStartShapeVartimeEndShapeVar.

shapeLab

String with label for timeStartShapeVartimeEndShapeVar

shapeSize

Size for symbols (only used if timeStartShapeVar/timeEndShapeVar is specified).

title

String with title, label of the parameter 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.'

caption

(optional) String with caption (NULL for no caption). By default the caption contains information on the imputation strategy for missing time.

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.

Value

list of (across subjects) of list (across pages) of ggplot2 objects, also of class subjectProfileIntervalPlot. with additional 'metaData' attributes containing 'label', 'timeLim' timeTrans and timeExpand (if specified).

Time interval representation

In case the start or the end of the time interval contain missing values:

• if a dataset (timeLimData), start (timeLimStartVar) and end (timeLimEndVar) variables are specified:

  1. for each subject:

     • the minimum and maximum time values across these specified time variables are extracted

     • missing start values are replaced by the minimum time

     • missing start values are replaced by the maximum time

  2. if all values are missing for this subject, they are taken across subjects

• otherwise, depending on the imputation type (timeImpType):

  • 'minimal' (by default):

    • if the start and the end of the interval are missing: no imputation is done, only the label is displayed

    • if the start time is missing and the end time is not missing: start time is imputed with end time, and status is set to 'Missing start'

    • if the end time is missing and the start time is not missing: end time is imputed with start time, and status is set to 'Missing end'

  • 'data-based' (default in version < 1.0.0): minimum/maximum values in the start/end time variables in the data are considered for the specific subject (if available). If there are missing for a specific subject, they are taken across subjects. If all time are missings, the range is set to 0 and Inf

  • 'none': no imputation is done

The symbols displayed at the start and end of the interval are:

• by default:

  • a filled square labelled 'Complete' if the time is not missing

  • a filled left-directed arrow in case of missing start time

  • a filled right-directed arrow in case of missing end time

• if the variable(s) used for the shape of the start or end of the interval are specified (via timeStartShapeVar/timeEndShapeVar): labels are based on these variables, and a standard shape palette is used

The time limits are the same across subjects, and set to:

• timeLim if specified

• maximum time range in timeLimStartVar and timeLimEndVar in timeLimData if specified

• the maximum range on the data obtained after imputation of missing values

Author(s)

Laure Cougnaud

See Also

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