1.1 Objectives of ospsuite.plots

The main purpose of the ospsuite.plots library is to provide standardized plots typically used in the context of PBPK modeling. The library supports plot generation for the packages OSPSuiteR and OSPSuite.ReportingEngine.

The library is based on ggplot2 functionality and also utilizes the ggh4x package.

2.1 Plots with and without Default Layout

# ospsuite.plots function
ospsuite.plots::plotHistogram(data = testData, mapping = aes(x = Age)) + labs(tag = "A")

# Customized plot
ggplot(data = testData, mapping = aes(x = Obs, y = Pred, color = Sex, shape = Sex)) +
  geom_point() +
  theme(legend.position = "top") +
  labs(tag = "B")

# Set default layout and save previous layout in variable oldDefaults
oldDefaults <- ospsuite.plots::setDefaults(defaultOptions = list(), colorMapList = NULL)

# ospsuite.plots function
ospsuite.plots::plotHistogram(data = testData, mapping = aes(x = Age)) + labs(tag = "A")

# Customized plot
ggplot(data = testData, mapping = aes(x = Obs, y = Pred, color = Sex, fill = Sex, shape = Sex)) +
  geom_point() +
  theme(legend.position = "top") +
  labs(tag = "B")

# Reset to previously saved layout options
ospsuite.plots::resetDefaults(oldDefaults = oldDefaults)

# ospsuite.plots function
ospsuite.plots::plotHistogram(data = testData, mapping = aes(x = Age)) + labs(tag = "A")

# Customized plot
ggplot(data = testData, mapping = aes(x = Obs, y = Pred, color = Sex, shape = Sex)) +
  geom_point() +
  theme(legend.position = "top") +
  labs(tag = "B")

2.2 Default Theme

Functions to set the ospsuite.plots default theme only are setDefaultTheme() and resetDefaultTheme(). These functions are called by setDefaults() and resetDefaults().

# Set ospsuite.plots Default Theme
oldTheme <- ospsuite.plots::setDefaultTheme()

# Customize theme using ggplot functionalities
theme_update(legend.position = "top")
theme_update(legend.title = element_blank())

# Reset to the previously saved theme
ospsuite.plots::resetDefaultTheme(oldTheme)

2.3 Default Color

Functions to set the ospsuite.plots default color only are setDefaultColorMapDistinct() and resetDefaultColorMapDistinct(). These functions are called by setDefaults() and resetDefaults().

Colors are set to discrete and ordinal scales for fill and colour.

The package provides some color palettes in the object colorMaps (see ?colorMaps).

The example below shows plots with:

• A plot with default settings for up to 6 different colors
• B plot with default settings for more than 6 different colors
• C customized settings for all following plots using the colorMaps[["grays"]]
• D customized plot: set gray scale for this plot only using function scale_fill_grey()
• E customized settings for all following plots using ggsci::pal_lancet()(9)
• F customized plots: set gray scale for this plot only using function ggsci::scale_color_lancet()

# Set ospsuite.plots Default Color
oldColors <- ospsuite.plots::setDefaultColorMapDistinct()

ggplot() +
  geom_tile(aes(x = rep(seq(1, 3), 2), y = rep(seq(1, 2), each = 3), fill = as.factor(seq(1, 6)))) +
  labs(title = "Default settings for up to 6 different colors", tag = "A") +
  theme(legend.position = "none", axis.title = element_blank())

ggplot() +
  geom_tile(aes(x = c(rep(seq(1, 7), 7), 1, 2), y = c(rep(seq(1, 7), each = 7), 8, 8), fill = as.factor(seq(1, 51)))) +
  labs(title = "Default settings for more than 6 different colors") +
  theme(legend.position = "none", axis.title = element_blank())

# Customize colors: set to gray colors
ospsuite.plots::setDefaultColorMapDistinct(colorMaps[["grays"]])

ggplot() +
  geom_tile(aes(x = rep(seq(1, 3), 3), y = rep(seq(1, 3), each = 3), fill = as.factor(seq(1, 9)))) +
  theme(legend.position = "none", axis.title = element_blank()) +
  labs(title = "colorMaps gray", tag = "C")

ggplot() +
  geom_tile(aes(x = rep(seq(1, 3), 3), y = rep(seq(1, 3), each = 3), fill = as.factor(seq(1, 9)))) +
  theme(legend.position = "none", axis.title = element_blank()) +
  scale_fill_grey() +
  labs(title = "scale_fill_grey", tag = "D")

# Set to color palettes inspired by plots in Lancet journals
ospsuite.plots::setDefaultColorMapDistinct(ggsci::pal_lancet()(9))

ggplot() +
  geom_tile(aes(x = rep(seq(1, 3), 3), y = rep(seq(1, 3), each = 3), fill = as.factor(seq(1, 9)))) +
  theme(legend.position = "none", axis.title = element_blank()) +
  labs(title = "ggsci::pal_lancet", tag = "E")

# Set to color palettes inspired by plots in Lancet journals
ospsuite.plots::setDefaultColorMapDistinct(ggsci::pal_lancet()(9))

ggplot() +
  geom_tile(aes(x = rep(seq(1, 3), 3), y = rep(seq(1, 3), each = 3), fill = as.factor(seq(1, 9)))) +
  theme(legend.position = "none", axis.title = element_blank()) +
  ggsci::scale_color_lancet() +
  labs(title = "ggsci::scale_color_lancet", tag = "F")

# Reset to the previously saved color map
ospsuite.plots::resetDefaultColorMapDistinct(oldColorMaps = oldColors)

2.4 Default Shapes

All point layers produced by ospsuite.plots use geom_point_osp(), which draws from the OSP shape palette defined in ospShapeNames. When you build your own plots and want them to combine consistently with ospsuite.plots outputs, prefer geom_point_osp() over the raw ggplot2::geom_point().

Shape ordering is controlled per plot, not via a global option:

• geom_point_osp() paired with scale_shape_osp() assigns shapes automatically from ospShapeNames.
• scale_shape_osp_manual(values = c(level1 = "circle", level2 = "diamond", ...)) sets an explicit mapping.
• scale_shape_osp_identity() is the right choice when the data already contains shape names.

Raw ggplot2::geom_point() keeps using ggplot2’s native pch shapes and is unaffected.

2.5 Default Options

getDefaultOptions() returns a list of options used in this package. These options are set by the function setDefaults() via the variable defaultOptions.

ospsuite.plots::setDefaults(defaultOptions = ospsuite.plots::getDefaultOptions())

The names of all options defined by this package start with the package name ospsuite.plots as a prefix and a suffix. The suffixes are listed in the enumeration OptionKeys. There are two helper functions (setOspsuite.plots.option and getOspsuite.plots.option) to set and get these options.

2.5.1 Options to Customize Watermark

All plots in this packages are created with the function ggplotWithWatermark() instead of ggplot(). This function creates a ggplot with a customized print function which adds a watermark.

The watermark is enabled by default — plots produced without any configuration will already carry the watermark. Setting the option to NULL is treated the same as using the default, so the watermark will still appear.

No opt-in is required; you only need to interact with these options if you want to customize or remove the watermark. To override this default in your .Rprofile (e.g., to disable watermarks globally):

# Disable watermarks globally
options(ospsuite.plots.watermarkEnabled = FALSE)

You can edit your .Rprofile with usethis::edit_r_profile().

Attention! If you combine plots e.g. with cowplot:plot_grid the default print function without watermark is called. In this case you have to add the watermark with the function addWatermark(plotObject) before the print.

The watermark can be customized by these options:

• Switch the watermark on and off (option key = watermarkEnabled, default = TRUE)
• Define the label (option key = watermarkLabel, default = “preliminary analysis”)
• Customize format (option key = watermarkFormat, default = list(x = 0.5, y = 0.5, color = "lightgrey", angle = 30, fontsize = 12, alpha = 0.7))

# Change format and label of watermark
setOspsuite.plots.option(optionKey = OptionKeys$watermarkFormat, value = list(x = 0.2, y = 0.6, color = "red", angle = 90, fontsize = 24, alpha = 0.2))
setOspsuite.plots.option(optionKey = OptionKeys$watermarkLabel, value = "NEW")

# Initialize plot
ggplotWithWatermark() + labs(title = "Changed Watermark", tag = "A")

# Disable watermark
setOspsuite.plots.option(optionKey = OptionKeys$watermarkEnabled, value = FALSE)

# Initialize plot
ggplotWithWatermark() + labs(title = "No Watermark", tag = "B")

# Reset to default
setOspsuite.plots.option(optionKey = OptionKeys$watermarkFormat, value = NULL)
setOspsuite.plots.option(optionKey = OptionKeys$watermarkLabel, value = NULL)
setOspsuite.plots.option(optionKey = OptionKeys$watermarkEnabled, value = TRUE)

# Initialize plot
ggplotWithWatermark() + labs(title = "Default Watermark", tag = "C")

2.5.2 Options to Set the Defaults for Geom Layer Attributes

All plot functions have input variables geom*Attributes which are passed as variables to the corresponding ggplot layer. The defaults of the input variables can be set by options.

With default options:

• LineAttributes = list()
• Ribbon = list(color = NA)
• PointAttributes = list()
• ErrorbarAttributes = list(width = 0)
• LLOQAttributes = list()
• ComparisonLineAttributes = list(linetype = "dashed")
• GuestLineAttributes = list(linetype = "dashed")
• BoxplotAttributes = list(position = position_dodge(width = 1), color = "black")
• HistAttributes = list(bins = 10, position = ggplot2::position_nudge())

2.5.3 Options to Set Defaults for Aesthetics

Options to set the face alpha of ribbons, filled points and options to set the filled points for values below and above LLOQ.

# Default alpha = 0.5
getOspsuite.plots.option(optionKey = "alpha")

# Alpha of LLOQ values
c("TRUE" = 0.3, "FALSE" = 1)
getOspsuite.plots.option(optionKey = "lloqAlphaVector")

# Linetype LLOQ comparison lines
"dashed"
getOspsuite.plots.option(optionKey = "lloqLineType")

2.5.4 Options for Percentiles

There are two percentile-related options controlling default behavior:

• percentiles: A numeric vector of five quantiles defining the lower whisker, lower box, median, upper box, and upper whisker used by plotBoxWhisker() (default = c(0.05, 0.25, 0.5, 0.75, 0.95)).
• defaultPercentiles: A numeric vector of three quantiles used as the default for plotRangeDistribution() (default = c(0.05, 0.5, 0.95)).

# Get current box-whisker percentiles (5 values)
getOspsuite.plots.option(optionKey = OptionKeys$percentiles)

# Change box-whisker percentiles globally
setOspsuite.plots.option(optionKey = OptionKeys$percentiles, value = c(0.1, 0.25, 0.5, 0.75, 0.9))

# Get current range-plot percentiles (3 values)
getOspsuite.plots.option(optionKey = OptionKeys$defaultPercentiles)

# Change range-plot default percentiles globally
setOspsuite.plots.option(optionKey = OptionKeys$defaultPercentiles, value = c(0.1, 0.5, 0.9))

2.5.5 Options to Define Export Format

There are options to define the export format using the function exportPlot (see details below):

• exportWidth: Width of the exported file
• exportUnits: Units for width and height
• exportDevice: Device for plot export
• exportDpi: Plot resolution

The latter options are used directly as input for ggplot2::ggsave, so check the help for available values.

3.1 plotTimeProfile()

Time Profile Plots

3.2 plotBoxWhisker()

Box Whisker Plots

3.3 plotHistogram()

Histogram Plots

3.4 plotPredVsObs()

Goodness of Fit

3.5 plotResVsCov()

Goodness of Fit

3.6 plotRatioVsCov()

Goodness of Fit

3.7 plotQQ()

Goodness of Fit

5.1 Basic Usage

To export a plot, you need a ggplot object. Here’s a basic example:

Create a simple ggplot object:

plotObject <- ospsuite.plots::plotHistogram(data = testData, mapping = aes(x = Age))

Exporting the Plot: Using the exportPlot function, you can easily save this plot to a file:

Replace “path/to/save” with the actual directory path where you want to save the plot, and adjust the width and height parameters as needed.

exportPlot(plotObject = plotObject, filepath = "path/to/save", filename = "myplot", width = 10, height = 8)

5.2 Advanced Usage

exportPlot(plotObject = plotObject, filepath = "path/to/save", filename = "adjusted_plot.png")

6.1 Default Shapes

shapes <- data.frame(
  shapeNames = ospShapeNames,
  x = rep(1:6, length.out = length(ospShapeNames)),
  y = rep(1:4, each = 6, length.out = length(ospShapeNames))
)

ggplot(shapes, aes(x, y, shape = shapeNames)) +
  geom_point_osp(size = 5, color = "blue", fill = "red") +
  scale_shape_osp_identity() +
  geom_text(aes(label = shapeNames), nudge_y = -0.3, size = 3) +
  theme_void()

6.2 Using OSP Shapes in Plot Functions

OSP shapes are available in all ospsuite.plots functions via the default shape scale set by setDefaults(). You can also apply them directly with scale_shape_osp().

oldDefaults <- ospsuite.plots::setDefaults()

dt <- data.frame(x = c(1, 2, 1, 2), y = c(1, 1, 2, 2), species = c("dog", "cat", "mouse", "rat"))

plotObject <- plotYVsX(data = dt, mapping = aes(x = x, y = y, groupby = species), xScale = "linear", xScaleArgs = list(limits = c(0.5, 2.5)), yScale = "linear", yScaleArgs = list(limits = c(0.5, 2.5)))

plot(plotObject)

```