formatTimeInterval {patientProfilesVis}

Set missing start/end time variable in the data.

Description

Set missing start/end time variable in the data.

Usage

formatTimeInterval(
  data,
  timeStartVar,
  timeStartLab = getLabelVar(timeStartVar, labelVars = labelVars),
  timeEndVar,
  timeEndLab = getLabelVar(timeEndVar, labelVars = labelVars),
  timeStartShapeVar = NULL,
  timeEndShapeVar = NULL,
  subjectVar = "USUBJID",
  timeLim = NULL,
  timeLimData = NULL,
  timeLimStartVar = NULL,
  timeLimStartLab = getLabelVar(timeLimStartVar, labelVars = labelVars),
  timeLimEndVar = NULL,
  timeLimEndLab = getLabelVar(timeLimEndVar, labelVars = labelVars),
  timeImpType = c("minimal", "data-based", "none"),
  labelVars = NULL
)

Arguments

data

Data.frame with data.

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.

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

subjectVar

String, variable of data with subject ID

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.

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.

labelVars

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

Value

list with:

• 'data': Data with:

  • imputed timeStartVar and timeEndVar

  • new column 'timeStartStatus': character vector containing status of timeStartVar variable: 'Complete' or 'Missing start' or NA

  • new column 'timeEndStatus': character vector containing status of timeEndVar variable: 'Complete' or 'Missing end' or NA

• 'timeLim': vector of length 2 with minimum/maximum time limits across subjects.

• 'timeLimSpecified': vector of length 2 with time limits as specified by the user, either extracted from timeLim or from timeLimData. If missing value within timeLim, the corresponding minimum/maximum value in the (updated) data is used.

• 'timeShapePalette': Named character vector with symbols for the different time status

• 'caption': String with extra explanation concerning imputation that could be included in plot caption.

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