Skip to contents

Plots residuals as a histogram, grouped by "group".

This function generates a histogram of the residuals, providing a visual representation of their distribution.

Usage

plotResidualsAsHistogram(
  plotData,
  metaData = NULL,
  mapping = ggplot2::aes(),
  yUnit = NULL,
  distribution = "normal",
  residualScale = "log",
  watermark = NULL,
  watermarkFormat = NULL,
  ...
)

Arguments

plotData

An object of class DataCombined or a data.table. If a data.table, it must include the following:

  • xValues: Numeric time points.

  • yValues: Observed or simulated values (numeric).

  • group: Grouping variable (factor or character).

  • name: Name for the dataset (factor or character).

  • xUnit: Unit of the x-axis values (character).

  • yUnit: Unit of the y-axis values (character).

  • dataType: Specifies data type—either observed or simulated.

  • Optional:

    • yErrorType: Type of y error, relative to ospsuite::DataErrorType.

    • yErrorValues: Numeric error values.

    • yMin, yMax: Custom ranges for y-axis instead of error types.

    • IndividualId: Used for aggregation of simulated population data.

metaData

A list containing metadata for the plot. If NULL, a default list is constructed from the data. Expected structure includes information about dimensions and units for both x and y axes.

mapping

A ggplot2 aesthetic mapping object. Default is ggplot2::aes(). This is added or replaces the default mapping constructed by the data.

yUnit

A character string specifying the target unit for the simulated and observed y-values used for residual calculation. If NULL (default), the most frequent unit in the data is used. For available units, see ospsuite::ospUnits.

distribution

parameter passed to ospsuite.plots::plotHistogram.

residualScale

Either "linear", "log", or "ratio" method for computing residuals. Default is log.

watermark

Optional watermark text for this plot.

watermarkFormat

Optional list of watermark formatting values.

...

Arguments passed on to ospsuite.plots::plotHistogram

asBarPlot

A logical indicating if geom_histogram should be used (for continuous data) or geom_bar (for categorical data). If TRUE, the variables distribution, meanFunction, xScale, and xScaleArgs are ignored.

geomHistAttributes

A list of arguments passed to ggplot2::geom_histogram (or geom_bar if asBarPlot = TRUE).

plotAsFrequency

A logical indicating if the histogram displays frequency on the y-axis.

xScale

either 'linear' then ggplot2::scale_x_continuous() or 'log' then ggplot2::scale_x_log10() is used

xScaleArgs

list of arguments passed to ggplot2::scale_x_continuous() or ggplot2::scale_x_log10()

yScale

either 'linear' then ggplot2::scale_y_continuous() or 'log' then ggplot2::scale_y_log10() is used

yScaleArgs

list of arguments passed to ggplot2::scale_y_continuous() or ggplot2::scale_y_log10()

meanFunction

Function selection for the display of a vertical line. Options: 'none', 'mean', 'geomean', 'median', 'auto' (default). 'auto' selects 'mean' for normal distribution, 'geomean' for lognormal, 'median' for other distributions, and 'none' when no distribution fit.

Value

A ggplot2 plot object representing the histogram of residuals, or NULL if the data contains no plottable entries.

See also

Examples

# Generate a histogram of residuals with default settings
plotResidualsAsHistogram(dataCombinedAciclovir)


# Generate a histogram with linear scale
plotResidualsAsHistogram(dataCombinedAciclovir, residualScale = "linear")