Generate Time Profile Panels

The `plotTimeProfiles` function creates a series of time profile plots as facet panels from the provided simulated and observed data. This function is designed to visualize complex time-dependent data by allowing for multiple plots organized in a user-defined layout.

Usage

plotTimeProfiles(
  projectConfiguration,
  onePlotConfig,
  dataObserved = NULL,
  scenarioResults,
  nMaxFacetRows = 4,
  facetAspectRatio = 0.5,
  aggregationFlag = c("GeometricStdDev", "ArithmeticStdDev", "Percentiles", "Custom"),
  percentiles = getOspsuite.plots.option(optionKey = OptionKeys$Percentiles)[c(1, 3, 5)],
  customFunction = NULL,
  checkForUnusedData = FALSE,
  referenceScaleVector = list(),
  ...
)

Arguments

projectConfiguration

An object of class `ProjectConfiguration` containing project settings, including file paths and scenario definitions. This is essential for the function to access the necessary data.

onePlotConfig

A configuration table for the specific plot, detailing plot parameters.

dataObserved

A `data.table` (formatted as produced by `readObservedDataByDictionary`) or `DataCombined` object containing the observed data to be plotted.

scenarioResults

A list containing simulated scenario results.

nMaxFacetRows

An integer specifying the maximum number of facet rows (default is 4).

facetAspectRatio

A numeric value specifying the aspect ratio for the facets (default is 0.5).

aggregationFlag

A character vector indicating the type of aggregation function to use for simulated data. Options include "GeometricStdDev" (default), "ArithmeticStdDev", "Percentiles", and "Custom".

percentiles

A numeric vector of percentiles to consider if the aggregation method is set to "Percentiles" (default is c(5, 50, 95)).

customFunction

An optional custom function for aggregation. A custom function should take a numeric vector `y` as input and return a list containing:

- `yValues`: The aggregated value (e.g., mean). - `yMin`: The lower value of the aggregated data (e.g., mean - sd). - `yMax`: The upper value of the aggregated data (e.g., mean + sd). - `yErrorType`: A string indicating the type of error associated with the aggregation, it is used in plot legends and captions. It must be a concatenation of the descriptor of `yValues` and the descriptor of `yMin - yMax` range separated by "|" (e.g., "mean | standard deviation" or "median | 5th - 95th percentile").

checkForUnusedData

A boolean indicating whether to perform quality control on data usage. If TRUE, `plotList` contains an additional entry `unusedData`.

referenceScaleVector

A named list that configures colors for the display of reference scenarios. The names must be consistent with the labels defined in the config table column `colorLegend`. The first entry corresponds to aesthetic 'color', and the second entry to aesthetic 'fill'.

Example: referenceScaleVector = list( Simulation = c('blue', 'lightblue'), Reference = c('darkred', 'red') ) # Default is list()

...

Additional arguments passed to `ospsuite.plots::plotTimeprofile`.

Value

A list of generated time profile plots

Details

The function primarily focuses on simulated scenarios, with each panel displaying the result of one scenario, or one scenario versus a reference scenario. Plots containing more than one scenario or only observed data are not supported.

The function is intended to be used in combination with the `runPlot` function. See the vignette `Plot and Report Generation` for more details.

There exists a helper function `addDefaultConfigForTimeProfilePlots` which is a helpful utility designed to streamline the process of setting up your Excel configuration sheet for time profile plots. This function automatically populates a new sheet with default values that you can customize according to your needs.

There is a tutorial for this function with many examples in the accompanying vignette: `Time Profile Plotting Tutorial`.

Examples

if (FALSE) { # \dontrun{
# Example of using the referenceScaleVector parameter for a DDI Analysis
referenceScaleVector <- list(
  DDI = c("#843C39FF", "#AD494AFF"),
  Control = c("#3182BDFF", "#6BAED6FF")
)
# The scenario would be labeled as 'DDI', with aesthetic color as dark red ("#843C39FF") and
# aesthetic fill as light red ("#AD494AFF").
# The reference scenario would be labeled 'Control',
# with aesthetic color as dark blue ("#3182BDFF") and
# aesthetic fill as light blue ("#6BAED6FF").

# Example of using the referenceScaleVector parameter for a comparison between a pediatric
# and an adult simulation using the default colors
referenceScaleVector <- list(
  "Pediatric population" = c(NA, NA),
  "Adult population" = c(NA, NA)
)

# The scenario would be labeled as 'Pediatric population', using the default colors with aesthetic
# color dark blue ("#3182BDFF") and aesthetic fill as light blue ("#6BAED6FF").
# The reference scenario would be labeled 'Adult population', with both aesthetic color and fill
# as 'grey'.

# Example of using the aggregationFlag parameter "Custom"
plotList <- runPlot(
  nameOfplotFunction = "plotTimeProfiles",
  configTableSheet = "myTimeProfile",
  projectConfiguration = projectConfiguration,
  suppressExport = TRUE,
  inputs = list(
    scenarioResults = scenarioResults,
    dataObserved = dataObserved,
    aggregationFlag = c("Custom"),
    customFunction = function(y) {
      list(
        yValues = mean(y),
        yMin = mean(y) - sd(y),
        yMax = mean(y) + sd(y),
        yErrorType = "mean | standard deviation"
      )
    }
  )
)

# Example of using the aggregationFlag parameter "Percentiles"
plotList <- runPlot(
  nameOfplotFunction = "plotTimeProfiles",
  configTableSheet = "myTimeProfile",
  projectConfiguration = projectConfiguration,
  suppressExport = TRUE,
  inputs = list(
    scenarioResults = scenarioResults,
    dataObserved = observedData,
    aggregationFlag = c("Percentiles"),
    percentiles = c(0.025, 0.5, 0.975)
  )
)
} # }

Usage

Arguments

Value

Details

See also

Examples