Type: Package
Title: Visualization of Patient Profiles
Version: 2.0.9
Date: 2024-06-18
Description: Creation of patient profile visualizations for exploration, diagnostic or monitoring purposes during a clinical trial. These static visualizations display a patient-specific overview of the evolution during the trial time frame of parameters of interest (as laboratory, ECG, vital signs), presence of adverse events, exposure to a treatment; associated with metadata patient information, as demography, concomitant medication. The visualizations can be tailored for specific domain(s) or endpoint(s) of interest. Visualizations are exported into patient profile report(s) or can be embedded in custom report(s).
Imports: clinUtils, ggplot2 (≥ 3.0.0), plyr, cowplot, tools, reshape2, knitr, grid, stringr, parallel, gridExtra, scales, utils
Suggests: pander, shiny, testthat, grDevices, rmarkdown, gtable, pdftools, viridisLite
URL: https://github.com/openanalytics/patientProfilesVis
BugReports: https://github.com/openanalytics/patientProfilesVis/issues
License: MIT + file LICENSE
RoxygenNote: 7.3.1
VignetteBuilder: knitr
SystemRequirements: latex, cairo (for report creation)
NeedsCompilation: no
Packaged: 2024-06-18 07:17:56 UTC; root
Author: Laure Cougnaud [aut, cre], Margaux Faes [rev] (tests), Open Analytics [cph]
Maintainer: Laure Cougnaud <laure.cougnaud@openanalytics.eu>
Repository: CRAN
Date/Publication: 2024-06-18 09:00:02 UTC

Add reference lines to a profile plot

Description

Add reference lines to a profile plot

Usage

addReferenceLinesProfilePlot(
  gg,
  subjectVar = "USUBJID",
  refLines = NULL,
  refLinesData = NULL,
  refLinesTimeVar = NULL,
  refLinesLabelVar = NULL,
  refLinesColor = "black",
  refLinesLinetype = "dotted",
  timeLim = NULL,
  addLabel = FALSE
)

Arguments

gg

ggplot2 with a subject profile plot for a specific subject (and page) (subset of the output of the subjectProfile[X]Plot)

subjectVar

String, variable of data with subject ID

refLines

(optional) nested list with details for reference line(s). Each sublist contains:

  • (required) 'label': string with label for the reference line

  • (required) 'time': unique time (x) coordinate for the reference line

  • (optional) 'color': color for the reference line, 'black' by default

  • (optional) 'linetype': linetype for the reference line, 'dotted' by default

refLinesData

data.frame with data from which the reference line(s) should be extracted

refLinesTimeVar

string, variable of refLinesData with time for reference line(s)

refLinesLabelVar

string, variable of refLinesData with label for reference line(s)

refLinesColor

vector of length 1 with default color for reference line(s)

refLinesLinetype

vector of length 1 with default linetype for reference line(s)

timeLim

vector of length 2 with time limits. This is used to set the limits to the plot containing the reference lines labels (if requested).

addLabel

logical, if TRUE (FALSE by default) add the label of the reference line(s) at the bottom of the plot

Value

If addLabel is:

Author(s)

Laure Cougnaud

Check if some of the modules are time expanded, and extract maximum time expand for each module.

Description

Check if some of the modules are time expanded, and extract maximum time expand for each module.

Usage

checkTimeExpand(listPlots, timeLim = NULL)

Arguments

listPlots

list of plots

timeLim

time limits

Value

List of time expand for each module (named by listPlots)

Author(s)

Laure Cougnaud

Check if the subject profiles are time transformed, and if some of the plots to align (with specified timeLim) have compatible time transformation alignments.

Description

Check if the subject profiles are time transformed, and if some of the plots to align (with specified timeLim) have compatible time transformation alignments.

Usage

checkTimeTrans(listPlots, timeLim = NULL)

Arguments

listPlots

list of plots

timeLim

time limits

Value

List of time transformation for each module (named by listPlots)

Author(s)

Laure Cougnaud

Check if specified variable(s) are present in the data.

Description

Check if specified variable(s) are present in the data.

Usage

checkVar(var, data)

Arguments

var

Character vector with variable(s) of interest.

data

Data.frame with data.

Value

No returned value, an error message is triggered if some variable(s) are not available in the data.

Author(s)

Laure Cougnaud

Combine vertically multiple ggplot.

Description

If the different modules for a subject don't fit in the page, there are automatically split in multiple pages. The margins are extracted across plots to ensure that plots will be probably aligned.

Usage

combineVerticallyGGplot(
  listPlots,
  maxNLines = NULL,
  nCores = 1,
  shiny = FALSE,
  verbose = FALSE,
  reportPerSubject = FALSE
)

Arguments

listPlots

listPlots per subject as created inside the subjectProfileCombine function.

maxNLines

Maximum number of lines for a combined plot, to fit in the page height.
When the different visualizations are combined for each subject, they will be allocated to different pages if the number of lines of the combined visualization is higher than this number.

nCores

Integer containing the number of cores used for the computation (1 by default). If more than 1, computation is parallelized, in this case the package parallel is required.

shiny

logical, set to TRUE (FALSE by default) if the report is generated from a Shiny application. Messages during report creation will be included in the Shiny interface, and it will be mentioned at the end of the report. In this case, the shiny package should be available.

verbose

logical, if TRUE print messages during execution

reportPerSubject

Logical, if TRUE (FALSE by default) export a subject profile report by subject.

Value

a list (by subject) of list (by page) of ggplot object

Author(s)

Laure Cougnaud

Convert aesthetic variable for patient profile visualization.

Description

This converts the empty values (”) to NA. The variable is then converted as a factor.
Missing values are also included in the levels of the factor, to ensure that missing values are displayed in the legend of the plot.

Usage

convertAesVar(data, var)

Arguments

data

data.frame with data

var

variable of data with aesthetic

Value

updated factor var variable

Author(s)

Laure Cougnaud

Count number of lines ('\n' character) per character in a vector

Description

Count number of lines ('\n' character) per character in a vector

Usage

countNLines(x)

Arguments

x

character vector

Value

numeric vector with same length than x containing number of lines in each element

Author(s)

Laure

Create subject profile report.

Description

By default all subjects available in at least one module of listPlots are considered. If only a set of subjects are of interest, these are specified either:

Usage

createSubjectProfileReport(
  listPlots,
  timeLim = NULL,
  timeAlign = "all",
  timeAlignPerSubject = "none",
  refLines = NULL,
  refLinesData = NULL,
  refLinesTimeVar = NULL,
  refLinesLabelVar = NULL,
  bookmarkData = NULL,
  bookmarkVar = NULL,
  subjectSortData = bookmarkData,
  subjectSortVar = bookmarkVar,
  subjectSortDecreasing = FALSE,
  subjectVar = "USUBJID",
  subjectSubset = NULL,
  subjectSubsetData = NULL,
  subjectSubsetVar = NULL,
  subjectSubsetValue = NULL,
  subjectSample = NULL,
  seed = 123,
  subset = NULL,
  outputFile = "subjectProfile.pdf",
  exportFigures = FALSE,
  reportPerSubject = FALSE,
  exportBatchSize = NULL,
  labelVars = NULL,
  maxNLines = NULL,
  shiny = FALSE,
  formatReport = subjectProfileReportFormat(),
  verbose = FALSE,
  nCores = 1
)

Arguments

listPlots

nested list of plots, as returned by the subjectProfileTextPlot, subjectProfileEventPlot, subjectProfileIntervalPlot or subjectProfileLinePlot functions.

timeLim

Time limits, as a numeric vector of length 2, or a list with time limits for each module, or nested list with time limits for each module and subject. If not specified, these are set to the time limits specified when creating each module (stored in attributes(x)$metaData$timeLim) otherwise to the range defined by timeAlign and timeAlignPerSubject. Note that this doesn't modify the geoms of the plots, it only extends the axis range. So for interval module(s) if the specified timeLim is smaller than the time limits in the input plot, no arrows are created in case than the time goes above/below specified timeLim (the segment is cut).

timeAlign

Character vector with time alignment across modules/subjects, either:

  • 'all' (by default): all plots have the same time limits

  • 'none': each of the plot (module*subject) has its own time limits

  • character vector with names of the modules which should have the same time limits (should correspond to the names of listPlots)

timeAlignPerSubject

Character vector, specifying if the plots should be aligned (or not) across subjects

  • 'none' (by default): all modules to align have the same time limit across subjects

  • 'all': all modules to align have different time limits per subject

  • character vector with subset of the modules to align per subject (should correspond to the names of listPlots)

Only the modules already specified in timeAlign can be aligned by subject.

refLines

(optional) nested list with details for reference line(s). Each sublist contains:

  • (required) 'label': string with label for the reference line

  • (required) 'time': unique time (x) coordinate for the reference line

  • (optional) 'color': color for the reference line, 'black' by default

  • (optional) 'linetype': linetype for the reference line, 'dotted' by default

refLinesData

data.frame with data from which the reference line(s) should be extracted

refLinesTimeVar

string, variable of refLinesData with time for reference line(s)

refLinesLabelVar

string, variable of refLinesData with label for reference line(s)

bookmarkData, bookmarkVar

Data.frame with data containing information for the index, and character vector with corresponding variable(s) of interest. An index will be created at the end of the subject profile report.
The index contains a section per variable, referencing the pages of the report containing subject profiles for each category/variable.

subjectSortData

Data.frame with data containing information on how the subjects should be sorted (by default same as bookmarkData):

  • in the report, in case one single report is created for all subjects

  • for the export, in case reportPerSubject is TRUE

This data should contain subjectSortVar and subjectVar.

subjectSortVar

Character vector, variable(s) of subjectSortData indicating the order for the subjects in the report, (by default same as bookmarkVar).

subjectSortDecreasing

Logical, if TRUE (FALSE by default) subjects are sorted based on decreasing order of subjectSortVar.

subjectVar

String, variable of data with subject ID

subjectSubset

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

subjectSubsetData

Data.frame used to select subset of subjects of interest.

subjectSubsetVar

String with variable of subjectSubsetData that should be considered to filter subjects. If not specified, all subjects available in subjectSubsetData are considered.

subjectSubsetValue

Character vector with value(s) of subjectSubsetVar of interest to filter subjects on.

subjectSample

(optional) Integer of length 1 with number of random subject(s) that should be considered in the specified subset dataset. 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).

subset

Character vector with subjects of interest (among names of each list in listPlots).

outputFile

string, path to the output report

exportFigures

Logical, if TRUE (FALSE by default) the subject profile figures are also exported in pdf format in a 'figures' folder.
Figures are named as [subjectID]-[page].pdf

reportPerSubject

Logical, if TRUE (FALSE by default) export a subject profile report by subject.

exportBatchSize

(optional) Integer, if specified, the patient-profile reports are created by batch of this number of subjects. This might speed up the export for a high number of subjects. Only available if report is created by subject (reportPerSubject is TRUE) and modules are not aligned across subjects (timeAlignPerSubject is: 'all').

labelVars

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

maxNLines

Maximum number of lines for a combined plot, to fit in the page height.
When the different visualizations are combined for each subject, they will be allocated to different pages if the number of lines of the combined visualization is higher than this number.

shiny

logical, set to TRUE (FALSE by default) if the report is generated from a Shiny application. Messages during report creation will be included in the Shiny interface, and it will be mentioned at the end of the report. In this case, the shiny package should be available.

formatReport

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

verbose

logical, if TRUE print messages during execution

nCores

Integer containing the number of cores used for the computation (1 by default). If more than 1, computation is parallelized, in this case the package parallel is required.

Value

The path(s) of the report(s) is returned invisibly, and the report is created at the location specified by outputFile.
If the report is created by subject, the name of the exported subject profile is built as: [filename]-[subjectID].pdf, with [filename] extracted from outputFile. Space and platform-specific file separator are replaced by a dash in the filename.
If no patient profiles are available in the input, nothing is returned and a warning is triggered.

Author(s)

Laure Cougnaud

Define LaTeX index based on specified variable(s) of the dataset

Description

Define LaTeX index based on specified variable(s) of the dataset

Usage

defineIndex(subjects, data, var, subjectVar = "USUBJID", labelVars = NULL)

Arguments

subjects

vector with subject IDs (based on the subjectVar variable)

data

data.frame with data containing information on which the index should be based

var

variable(s) of data of interest for the index

subjectVar

String, variable of data with subject ID

labelVars

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

Value

list with elements:

Author(s)

Laure Cougnaud

Filter a dataset for records of interest, for use in the patient profiles.

Description

Data is filtered based on the following workflow:

  1. The subset dataset (of data if not specified) is filtered based on subject variable and value (if specified).

  2. If a external subset dataset is specified, only the subject IDs of this filtered dataset are considered.

  3. The data is filtered based on the selected subjects, from subjectSubset (if specified) or from step 2.

  4. The data is filtered based on a random selection of subjects, if subjectSample is specified.

This filtering workflow is used for all subject profile visualization functions of the package.

Usage

filterData(
  data,
  subsetData = NULL,
  subsetVar = NULL,
  subsetValue = NULL,
  subjectVar = "USUBJID",
  subjectSubset = NULL,
  subjectSample = NULL,
  seed = 123
)

Arguments

data

Data.frame with data

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.

subjectVar

String, variable of data (and subset 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).

Value

possibly filtered dataset

Author(s)

Laure Cougnaud

Examples

library(clinUtils)

data(dataSDTMCDISCP01)
dataAll <- dataSDTMCDISCP01

# keep only a subset of subjects
# (e.g. to visualize specified patient profiles
# before creating them for all subject)
filterData(
	data = dataAll$AE,
	subjectSample = 2
)

# filter based on specified variable/value:
# only adverse events possibly related
filterData(
	data = dataAll$AE,
	subsetVar = "AEREL",
	subsetValue = "POSSIBLE"
)

# filter based on a different dataset:
# keep only adverse events for subjects in a specific treatment arm
filterData(
	data = dataAll$AE,
	subsetData = dataAll$DM,
	subsetVar = "ACTARM",
	subsetValue = "Placebo"
)

# filter based on subjects of interest
filterData(
	data = dataAll$AE,
	subjectSubset = c("01-701-1148", "01-701-1211")
)

Filter missing records in data in the time and y variables, with informative message.

Description

Filter missing records in data in the time and y variables, with informative message.

Usage

filterMissingInVar(
  data,
  var,
  varLab = getLabelVar(var, labelVars = labelVars),
  labelVars = NULL
)

Arguments

data

Data.frame with data.

var

String with variable of interest.

varLab

String, label for var.

labelVars

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

Value

Update data with filtered records + message in the console.

Author(s)

Laure Cougnaud

Format text variables for the subject profile text plotting function.

Description

Text variables are wrapped across multiple lines if needed, and optionally sorted according to the levels of a grouping variable.

Usage

formatParamVarTextPlot(
  data,
  paramVar = NULL,
  paramValueVar = NULL,
  paramValueLab = NULL,
  paramGroupVar = NULL,
  revert = FALSE,
  width = formatReport$yLabelWidth,
  widthValue = ifelse(formatReport$landscape, 240, 190),
  formatReport = subjectProfileReportFormat(),
  table = FALSE,
  colWidth = NULL
)

Arguments

data

data.frame with data

paramVar

string, variable of data with parameter

paramValueVar

string, variable of data containing the parameter value.

paramValueLab

Character vector with labels for paramValueVar.

paramGroupVar

(optional) character vector with variable(s) of data with grouping.
If specified, the parameters will be grouped by this(these) variable(s) in the y-axis.

revert

logical, if TRUE revert the order of the levels of the variable

width

max number of characters in the paramVar parameter.

widthValue

max number of characters in the paramValueVar parameter.

formatReport

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

table

Logical, if TRUE the paramValueVar variables are displayed as table (so are not concatenated).

colWidth

Numeric vector with approximate width of each parameter value column for a table layout.
For example in case two parameters are specified: c(0.8, 0.2)) such as the first column takes 80% of plot area, and the second column 20%.
Note: columns can be slightly bigger if their content is larger than the specified width. If not specified, column width is optimized based on the max length of the character in each column.

Value

data with reformatted paramVar and paramValueVar variables, with additional attribute: colWidth.

Author(s)

Laure Cougnaud

See Also

subjectProfileTextPlot

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:

Time interval representation

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

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

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

Author(s)

Laure Cougnaud

Format specified timeLim.

Description

In case one of the limits if missing, the corresponding minimum/maximum across subjects is used.

Usage

formatTimeLim(
  data,
  subjectVar = "USUBJID",
  timeStartVar,
  timeEndVar,
  timeLim = NULL
)

Arguments

data

Data.frame with data.

subjectVar

String, variable of data with subject ID

timeStartVar

String, variable of data with start of time interval.

timeEndVar

String, variable of data with end of time interval.

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.

Value

Numeric vector of length 2 or list of such element for each subject.

Author(s)

Laure Cougnaud

Get custom 'scale_[type]_manual' function

Description

Get custom 'scale_[type]_manual' function

Usage

getAesScaleManual(lab, palette, type)

Arguments

lab

label for the scale (title of the legend)

palette

named vector with color palette

type

string with type of scale, e.g. 'color'

Value

output of the 'scale_[type]_manual' function

Author(s)

Laure Cougnaud

Get a color palette for patient profile visualizations.

Description

This is a simple wrapper around getColorPalette, with different defaults:

Usage

getColorPalettePatientProfile(..., includeNA = TRUE)

Arguments

...

Arguments passed on to clinUtils::getColorPalette

n

Integer of length 1, number of elements in palette.

x

Vector with elements used for palette. If factor, the levels are used, otherwise the unique elements of the vector. Missing values are automatically removed, excepted if includeNA is set to TRUE.

palette

A vector of custom colors, or a function returning this vector from a specific number of colors.
Default is the the colorblind viridis color palette.

includeNA

Logical (TRUE by default), should NA elements be retained in the palette in case x is specified?

Value

Vector of shapes, named with the elements in x if x is specified.

Author(s)

Laure Cougnaud

See Also

getColorPalette

Get maximum number of lines of a 'combined plot' for a specific document

Description

Get maximum number of lines of a 'combined plot' for a specific document

Usage

getMaxNLinesCombinePlot(
  heightLineIn = subjectProfileReportFormat()$heightLineIn,
  margin = subjectProfileReportFormat()$margin,
  landscape = subjectProfileReportFormat()$landscape,
  aspectRatio = subjectProfileReportFormat()$aspectRatio
)

Arguments

heightLineIn

Numeric of length 1 with height of a line in inches, 0.2 by default.

margin

Numeric of length 1, with margin in inches.

landscape

Logical, if TRUE the created report is in landscape format. FALSE by default, the report is created in portrait format.

aspectRatio

Numeric of length 1 (0.75 by default) with ratio between size of image in inches (derived from specified margin, landscape and heightLineIn) and real size for exported image.

Value

numeric with maximum height for plot

Author(s)

Laure Cougnaud

Get number of lines for specific label either from a ggplot2 object via gg or from the label via value

Description

Get number of lines for specific label either from a ggplot2 object via gg or from the label via value

Usage

getNLinesLabel(
  gg,
  value,
  elName = c("x", "y", "title", "caption"),
  elNLines = NULL
)

Arguments

gg

ggplot2 object

value

String with label value.

elName

string with name of label to extract, among 'x', 'y' and 'title'

elNLines

(optional) Named integer with number of lines, by default 2 for 'x'/'y', 3 for 'title' and 1 for caption.

Value

integer with (approximated) number of lines

Author(s)

Laure Cougnaud

Get number of lines in the legend, either from directly the ggplot2 object, or from the values of the legend (legendValues) and title (legendTitle)

Description

Get number of lines in the legend, either from directly the ggplot2 object, or from the values of the legend (legendValues) and title (legendTitle)

Usage

getNLinesLegend(gg, values, title)

Arguments

gg

ggplot2 object

values

Vector with unique legend values

title

String, title for the plot.

Value

integer with (approximated) number of lines

Author(s)

Laure Cougnaud

Get approximately the number of 'lines' in the vertical direction of a subject profile.

Description

This is extracted from the presence of labels in the y-axis, labels and title in the x-axis, general title and number of lines in the legend. Can be used to specify plot-specific height during the export.

Usage

getNLinesSubjectProfile(gg)

Arguments

gg

ggplot2 object, subset of the output of the subjectProfile[X]Plot function, for a particular subject/module/page.

Value

integer with (approximated) number of lines

Author(s)

Laure Cougnaud

Get optimal column widths, based on the minimum word size and median number of characters in each column.

Description

Get optimal column widths, based on the minimum word size and median number of characters in each column.

Usage

getOptimalColWidth(
  data,
  widthValue = ifelse(formatReport$landscape, 240, 190),
  labels = NULL,
  formatReport = subjectProfileReportFormat()
)

Arguments

data

Data.frame with columns for which optimal width should be extracted.

widthValue

max number of characters in the paramValueVar parameter.

labels

(optional) Character vector with column labels for data.

formatReport

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

Value

Numeric vector of length(ncol(data)) with optimal widths.

Author(s)

Laure Cougnaud

Get variable with page of the plot, used for automatic paging of a plot

Description

Get variable with page of the plot, used for automatic paging of a plot

Usage

getPageVar(
  data,
  var,
  typeVar = c("y", "panel"),
  formatReport = subjectProfileReportFormat(),
  title = TRUE,
  xLab = TRUE,
  caption = TRUE,
  paging = TRUE,
  table = FALSE
)

Arguments

data

data.frame with data

var

string, variable of data with variable for the y-axis

typeVar

string, type of the variable, either: 'y': the variable is displayed in the x-axis or 'panel': the variable is displayed as separated facets. This is used to compute height for each line of the plot.

formatReport

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

title

logical, has the plot a title?

xLab

logical, has the plot a label for the x-axis?

caption

logical, has the plot a caption?

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.

table

Logical, if TRUE the paramValueVar variables are displayed as table (so are not concatenated).

Value

input data with additional column 'pagePlot' containing the page for the plot

Author(s)

Laure Cougnaud

Get path of the report template in the patientProfilesVis package

Description

Get path of the report template in the patientProfilesVis package

Usage

getPathTemplate(file)

Arguments

file

file name (with extension)

Value

String with path to the template in the installed patientProfilesVis package

Author(s)

Laure Cougnaud

Get a shape palette for patient profile visualizations.

Description

This is a simple wrapper around getShapePalette, with different defaults:

Usage

getShapePalettePatientProfile(..., includeNA = TRUE, asText = TRUE)

Arguments

...

Arguments passed on to clinUtils::getShapePalette

n

Integer of length 1, number of elements in palette.

x

Vector with elements used for palette. If factor, the levels are used, otherwise the unique elements of the vector. Missing values are automatically removed, excepted if includeNA is set to TRUE.

palette

A vector of custom shapes, or a function returning this vector from a specific number of shapes.
The vector should be a character if asText is set to TRUE.
Default is the clinShapes shape palette, or clinShapesText if asText is set to TRUE.

includeNA

Logical (TRUE by default), should NA elements be retained in the palette in case x is specified?

asText

Logical (TRUE by default), should the palette be expressed as integer (base R plot and ggplot2 compatible) or in text format (e.g. required if combined with unicode symbols in ggplot2)?

Value

Vector of shapes, named with the elements in x if x is specified.

Author(s)

Laure Cougnaud

See Also

getShapePalette

Split/combine a vector of size(s) to have a fixed combined size

Description

Split/combine a vector of size(s) to have a fixed combined size

Usage

getSplitVectorByInt(sizes, max = NULL)

Arguments

sizes

vector with size

max

integer with maximum combined size in output, Inf by default.

Value

vector of same length as sizeVect, containing corresponding class

Author(s)

Laure Cougnaud

Get the limits to set for the subject profile plots, depending on the alignment policy set.

Description

These limits are extracted from specified timeLim for each module (stored in the attributes()$metaData$timeLim), and if empty for all modules: from the maximal range of the x-coordinates across all plots.

Usage

getTimeLimSubjectProfilePlots(
  listPlots,
  timeAlign = "all",
  timeAlignPerSubject = "none"
)

Arguments

listPlots

list of list of subjectProfile[X]Plot plots

timeAlign

Character vector with time alignment across modules/subjects, either:

  • 'all' (by default): all plots have the same time limits

  • 'none': each of the plot (module*subject) has its own time limits

  • character vector with names of the modules which should have the same time limits (should correspond to the names of listPlots)

timeAlignPerSubject

Character vector, specifying if the plots should be aligned (or not) across subjects

  • 'none' (by default): all modules to align have the same time limit across subjects

  • 'all': all modules to align have different time limits per subject

  • character vector with subset of the modules to align per subject (should correspond to the names of listPlots)

Only the modules already specified in timeAlign can be aligned by subject.

Value

Time limits, as a numeric vector of length 2. If time limits should be set by module, named list with time limits by module. If time limits should be set by module and subject, nested list with time limits 1) by module 2) by subject.
The names of the list contains the module/subject name extracted from the names of listPlots.
The time limits are only returned if they will need to be explicitly set for a plot. Otherwise, NULL is returned.

Author(s)

Laure Cougnaud

Get useful transformation for the time variable in patient profiles.

Description

Get useful transformation for the time variable in patient profiles.

Usage

getTimeTrans(
  type = c("asinh", "asinh-neg"),
  scale = 1,
  formatFct = prettyNum,
  n = 10
)

Arguments

type

String with transformation type, either:

  • 'asinh': hyperbolic arc-sine (asinh) transformation

  • 'asinh-neg': hyperbolic arc-sine transformation only for the negative values, otherwise linear scale

scale

Numeric vector of length 1 (1 by default) with size of the linear region around 0, only used if in case type is: 'asinh'.
If specified, the time variable is first scaled with: x/scale, then transformed.

formatFct

function formatting the time axis breaks, (prettyNum by default), see format parameter of the trans_new.

n

Integer of length 1 with number of breaks, 10 by default.

Value

ggplot2 transformation (see trans_new)

Author(s)

Pieter-Jan Stiers, Laure Cougnaud

Get width for a plot for a certain page layout

Description

Get width for a plot for a certain page layout

Usage

getWidthPlot(
  margin = subjectProfileReportFormat()$margin,
  landscape = subjectProfileReportFormat()$landscape,
  aspectRatio = subjectProfileReportFormat()$aspectRatio
)

Arguments

margin

Numeric of length 1, with margin in inches.

landscape

Logical, if TRUE the created report is in landscape format. FALSE by default, the report is created in portrait format.

aspectRatio

Numeric of length 1 (0.75 by default) with ratio between size of image in inches (derived from specified margin, landscape and heightLineIn) and real size for exported image.

Value

width for the plot in inches

Author(s)

Laure Cougnaud

Get interaction variable between different variables.

Description

This ensures that missing values in one of the variable(s) don't propagate, so the combined result will be: 'NA - a', and that the levels of the combined vector are sorted as the levels of the specified variables (levels of the first variable varying first).

Usage

interactionWithMissing(data, vars, varSep = " - ")

Arguments

data

Data.frame with data.

vars

Character vector with variable(s) of interest.

varSep

String with separator to which the variable(s) should be combined.

Value

Vector of length: nrow(data), with interaction vector.

Author(s)

Laure Cougnaud

Check if the all profile(s) is/are 'time-variant', so not a subject profile 'text' module or empty plot

Description

Check if the all profile(s) is/are 'time-variant', so not a subject profile 'text' module or empty plot

Usage

isSubjectProfileTimeVariant(gg, empty = TRUE)

Arguments

gg

object of class subjectProfileX (and ggplot) or potentially nested list of such objects.

empty

Logical, should empty subject profile be considered as time-variant?

Value

Logical, is plot time variant?

Author(s)

Laure Cougnaud

Arguments used across the functions of the patientProfilesVis package.

Description

Arguments used across the functions of the patientProfilesVis package.

Arguments

data

Data.frame with data.

colorVar

String, variable of data with color.

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.

xLab

String, label for the x-axis.

yLab

String, label for the y-axis.

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

title

String, title for 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.

paramVar

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

paramLab

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

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.

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

listPlots

Named list of subject profiles. Each sublist contains subject profiles as returned by the subjectProfile[X]Plot function, so nested by subject and page. The names of the list should be unique, and are used

alpha

Numeric with transparency, 1 by default.

labelVars

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

subjectVar

String, variable of data with subject ID

formatReport

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

paramVarSep

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

Value

No return value, used for the documentation of the functions of the package.

Parameters for all patient profiles visualization palette functions.

Description

Parameters for all patient profiles visualization palette functions.

Arguments

includeNA

Logical (TRUE by default), should NA elements be retained in the palette in case x is specified?

Value

No return value, used for the documentation of the palette functions of the package.

prepare list of subject profile (s) to be combined with the combineVerticallyGGplot

Description

prepare list of subject profile (s) to be combined with the combineVerticallyGGplot

Usage

prepareSubjectProfile(
  ...,
  labels,
  timeLim = NULL,
  refLines = NULL,
  refLinesData = NULL,
  refLinesTimeVar = NULL,
  refLinesLabelVar = NULL,
  subjectVar = "USUBJID",
  timeTrans = NULL,
  timeExpand = NULL
)

Arguments

...

list of subject profiles (across modules)

labels

string with labels for the plots

timeLim

time limits, as returned by the getTimeLimSubjectProfilePlots function.

refLines

(optional) nested list with details for reference line(s). Each sublist contains:

  • (required) 'label': string with label for the reference line

  • (required) 'time': unique time (x) coordinate for the reference line

  • (optional) 'color': color for the reference line, 'black' by default

  • (optional) 'linetype': linetype for the reference line, 'dotted' by default

refLinesData

data.frame with data from which the reference line(s) should be extracted

refLinesTimeVar

string, variable of refLinesData with time for reference line(s)

refLinesLabelVar

string, variable of refLinesData with label for reference line(s)

subjectVar

String, variable of data with subject ID

timeTrans

Time transformation, or list of such transformation named by module. If NULL, no transformation are done.

timeExpand

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

Value

subjectProfilePlot object, containing the combined profile plots

Author(s)

Laure Cougnaud

Sort subjects based on a specified dataset/variable.

Description

Sort subjects based on a specified dataset/variable.

Usage

sortSubjects(
  subjects,
  subjectVar = "USUBJID",
  subjectSortData = NULL,
  subjectSortVar = NULL,
  subjectSortDecreasing = FALSE,
  verbose = FALSE
)

Arguments

subjects

Character vector with subjects of interest

subjectVar

String, variable of data with subject ID

subjectSortData

Data.frame with data containing information on how the subjects should be sorted.

subjectSortVar

Variable(s) of subjectSortData used to order the subjects

subjectSortDecreasing

Logical, if TRUE (FALSE by default) subjects are sorted based on inverse order of subjectSortVar.

verbose

logical, if TRUE print messages during execution

Value

Updated subjects

Author(s)

Laure Cougnaud

Combine subject profile plots.

Description

Visualizations of different modules are combined by subject. The plots are aligned in the time axis (if requested). If the plots should be aligned:

If some plots are missing for a specific subject, an empty plot is created, containing information as a text based on the label with which the plot was created.

Usage

subjectProfileCombine(
  listPlots,
  timeLim = NULL,
  timeAlign = "all",
  timeAlignPerSubject = "none",
  subjectVar = "USUBJID",
  maxNLines = NULL,
  refLines = NULL,
  refLinesData = NULL,
  refLinesTimeVar = NULL,
  refLinesLabelVar = NULL,
  shiny = FALSE,
  verbose = FALSE,
  nCores = 1,
  reportPerSubject = FALSE
)

Arguments

listPlots

listPlots per subject as created inside the subjectProfileCombine function.

timeLim

time limits, as returned by the getTimeLimSubjectProfilePlots function.

timeAlign

Character vector with time alignment across modules/subjects, either:

  • 'all' (by default): all plots have the same time limits

  • 'none': each of the plot (module*subject) has its own time limits

  • character vector with names of the modules which should have the same time limits (should correspond to the names of listPlots)

timeAlignPerSubject

Character vector, specifying if the plots should be aligned (or not) across subjects

  • 'none' (by default): all modules to align have the same time limit across subjects

  • 'all': all modules to align have different time limits per subject

  • character vector with subset of the modules to align per subject (should correspond to the names of listPlots)

Only the modules already specified in timeAlign can be aligned by subject.

subjectVar

String, variable of data with subject ID

maxNLines

Maximum number of lines for a combined plot, to fit in the page height.
When the different visualizations are combined for each subject, they will be allocated to different pages if the number of lines of the combined visualization is higher than this number.

refLines

(optional) nested list with details for reference line(s). Each sublist contains:

  • (required) 'label': string with label for the reference line

  • (required) 'time': unique time (x) coordinate for the reference line

  • (optional) 'color': color for the reference line, 'black' by default

  • (optional) 'linetype': linetype for the reference line, 'dotted' by default

refLinesData

data.frame with data from which the reference line(s) should be extracted

refLinesTimeVar

string, variable of refLinesData with time for reference line(s)

refLinesLabelVar

string, variable of refLinesData with label for reference line(s)

shiny

logical, set to TRUE (FALSE by default) if the report is generated from a Shiny application. Messages during report creation will be included in the Shiny interface, and it will be mentioned at the end of the report. In this case, the shiny package should be available.

verbose

logical, if TRUE print messages during execution

nCores

Integer containing the number of cores used for the computation (1 by default). If more than 1, computation is parallelized, in this case the package parallel is required.

reportPerSubject

Logical, if TRUE (FALSE by default) export a subject profile report by subject.

Value

a nested list of ggplot object, containing the combined profile plots across modules for each subject/page.
Each plot object contains in the associated attribute: metaData containing: nLines: an estimation of the number of 'lines' each plot occupies (e.g. to set height of the exported figure).

Author(s)

Laure Cougnaud

Visualize events in subject profiles, so event with a single time.

Description

Visualize events in subject profiles, so event with a single time.

Usage

subjectProfileEventPlot(
  data,
  paramVar,
  paramLab = getLabelVar(paramVar, labelVars = labelVars),
  paramVarSep = " - ",
  paramGroupVar = NULL,
  colorVar = NULL,
  colorLab = getLabelVar(colorVar, labelVars = labelVars),
  colorPalette = NULL,
  shapeVar = colorVar,
  shapeLab = if (isTRUE(colorVar == shapeVar)) {
     colorLab
 } else
    getLabelVar(shapeVar, labelVars = labelVars),
  shapePalette = NULL,
  alpha = 1,
  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(paramVar, labelVars = labelVars, label = paramLab)),
  label = title,
  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.

paramLab

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

paramVarSep

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

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.

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.

alpha

Numeric with transparency, 1 by default.

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

Value

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

Author(s)

Laure Cougnaud

See Also

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

Create report

Description

Create report

Usage

subjectProfileExport(
  listPlotsSubject,
  outputFile = "subjectProfile.pdf",
  index = NULL,
  formatReport = subjectProfileReportFormat(),
  shiny = FALSE,
  verbose = FALSE,
  nCores = NULL,
  exportFigures = FALSE
)

Arguments

listPlotsSubject

List of plots for each subject

outputFile

string, path to the output report

index

Index, output from defineIndex

formatReport

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

shiny

logical, set to TRUE (FALSE by default) if the report is generated from a Shiny application. Messages during report creation will be included in the Shiny interface, and it will be mentioned at the end of the report. In this case, the shiny package should be available.

verbose

logical, if TRUE print messages during execution

nCores

Integer containing the number of cores used for the computation (1 by default). If more than 1, computation is parallelized, in this case the package parallel is required.

exportFigures

Logical, if TRUE (FALSE by default) the subject profile figures are also exported in pdf format in a 'figures' folder.
Figures are named as [subjectID]-[page].pdf

Value

No returned value, the plots are exported to outputDir

Author(s)

Laure Cougnaud

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:

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

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

Author(s)

Laure Cougnaud

See Also

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

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

Get list with format specification for subject profile report.

Description

This format is used to set default for the created subject profile report: line height, margin, report in landscape or portrait format, aspect ratio and width for the y-label.

Usage

subjectProfileReportFormat(
  heightLineIn = 0.2,
  margin = 0.75,
  landscape = FALSE,
  aspectRatio = 0.5,
  yLabelWidth = 30
)

Arguments

heightLineIn

Numeric of length 1 with height of a line in inches, 0.2 by default.

margin

Numeric of length 1, with margin in inches.

landscape

Logical, if TRUE the created report is in landscape format. FALSE by default, the report is created in portrait format.

aspectRatio

Numeric of length 1 (0.75 by default) with ratio between size of image in inches (derived from specified margin, landscape and heightLineIn) and real size for exported image.

yLabelWidth

Integer of length 1 with approximate maximum number of characters in the y-label of the plot, 30 by default. If the label of the y-axis is longer than this number of character, it will be splitted between words in separated lines.

Value

List with parameters to set format of the subject profile report. If not specified, default are used.

Author(s)

Laure Cougnaud

Visualize text-information in subject profiles.

Description

There are two ways to specify the variables of interest to include:

Usage

subjectProfileTextPlot(
  data,
  paramValueVar,
  paramValueLab = getLabelVar(paramValueVar, labelVars = labelVars),
  paramNameVar = NULL,
  paramGroupVar = NULL,
  subsetData = NULL,
  subsetVar = NULL,
  subsetValue = NULL,
  subjectVar = "USUBJID",
  subjectSubset = NULL,
  subjectSample = NULL,
  seed = 123,
  xLab = "",
  yLab = "",
  title = "Subject information",
  label = title,
  labelVars = NULL,
  paramVarSep = " - ",
  formatReport = subjectProfileReportFormat(),
  paging = TRUE,
  table = FALSE,
  colWidth = NULL
)

Arguments

data

Data.frame with data.

paramValueVar

Character vector, either:

  • vector with names of variable(s) (multiple are possible) of data of interest. The values are displayed in the plot area and variable name in the labels of the y-axis.
    Multiple variables can be concatenated in the same line by specifying them, as an unique string separated by a 'pipe', e.g 'SEX|AGE'. Variable label(s) are concatenated (with ', ') and displayed in the y-axis.

  • if paramNameVar is specified:

    • character vector with names of variable(s) (multiple possible) of data with values to represent in the plot area.

    • function taking data as input and returning a new variable (of length equal to number of rows in data) with parameter value to represent

paramValueLab

(optional) Named character vector with labels for paramValueVar.

paramNameVar

(optional) Character vector of length 1 with variable of data with parameter name. This is displayed in the labels of the y-axis.

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.

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.

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

xLab

String, label for the x-axis.

yLab

String, label for the y-axis.

title

String with title, 'Subject information' 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)

paramVarSep

String (' - ' by default) with character(s) used to concatenate multiple variables for the same record in the plot area.

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.

table

Logical, if TRUE (FALSE by default) the information contained in the variables: paramValueVar is displayed as a table. Otherwise, the values of the different variables are concatenated in the same line.

colWidth

Numeric vector with approximate width of each parameter value column for a table layout.
For example in case two parameters are specified: c(0.8, 0.2)) such as the first column takes 80% of plot area, and the second column 20%.
Note: columns can be slightly bigger if their content is larger than the specified width. If not specified, column width is optimized based on the max length of the character in each column.

Value

list of (across subjects) of list (across modules) of ggplot2 objects, also of class subjectProfileTextPlot, with additional metaData attributes containing 'label' and 'timeLim'.

Author(s)

Laure Cougnaud

See Also

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

Custom theme for subject profile plot. Currently classic dark-on-light ggplot2 theme with alternated grey color for vertical grid lines

Description

Custom theme for subject profile plot. Currently classic dark-on-light ggplot2 theme with alternated grey color for vertical grid lines

Usage

subjectProfileTheme()

Value

theme object

Author(s)

Laure Cougnaud