Open-Systems-Pharmacology/OSPSuite.ReportingEngine
R package to create reports for the Open Systems Pharmacology models

Package index
Search the Open-Systems-Pharmacology/OSPSuite.ReportingEngine package
Vignettes
Functions
821
Source code
140
Man pages
423
Home
/
GitHub
/
Open-Systems-Pharmacology/OSPSuite.ReportingEngine
/

In Open-Systems-Pharmacology/OSPSuite.ReportingEngine: R package to create reports for the Open Systems Pharmacology models 

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
source(system.file("extdata", "vignette-helpers.R", package = "ospsuite.reportingengine"))

require(ospsuite.reportingengine)

Overview

This vignette provides some guidance to define properties and settings for the reporting engine.

These properties can at 2 levels:

How to set global workflow properties

Reporting Engine global setting names are listed in the enum reSettingsNames. Each global setting can be reviewed using the function getRESettings().

It is possible to update, save and reuse most of the reporting engine default settings using the functions available in the section Default Settings.

Note that the function resetRESettingsToDefault() allows you to reset to initial default values defined by the reporting engine.

Notion of theme

A theme is an object of R6 class Theme which defines the default properties used to build every plot in tlf package. More information can be found directly within the documentation of the the tlf package (vignettes "theme-maker" and "plot-configuration").

The best workflow to set a Theme object is to use json files. Templates of json files are available in the tlf package at the location defined below:

# Get the path of the Json template
jsonFile <- system.file("extdata", "re-theme.json",
  package = "ospsuite.reportingengine"
)

# Load the theme from the json file
reTheme <- tlf::loadThemeFromJson(jsonFile)

Modifications of the theme properties can be done directly by updating the properties of the Theme object as shown below:

# Overwrite the current background fill
reTheme$background$panel$fill <- "white"
reTheme$background$panel$fill

To save the updated Theme object, the function saveThemeToJson provided by tlf package can be used.

# Save your updated theme in "my-new-theme.json"
tlf::saveThemeToJson("my-new-theme.json", theme = reTheme)

In addition, the tlf package provides a Shiny app to define and save your own theme with a few clicks: tlf::runThemeMaker().

Then, the most important step is to define the Theme object as the current default for the workflow. In ospsuite.reportingengine, this can be either achieved using the function setDefaultTheme with a Theme object as shown in the example below with reTheme.

The properties defined by the Theme object will be used by default if no specific plot configurations are provided for the workflow plots.

# Set reTheme as current default Theme
setDefaultTheme(reTheme)

Caution: loading a workflow re-initialize the default theme. The function setDefaultTheme() needs to be called after initialization of the workflow.

Additionally, Workflow objects have a theme input argument available in method $new() to use the input theme instead of the reporting engine default.

Exporting plots in a specific format

One important global setting is the format of the figure files (e.g. png, jpg or pdf) as well as the quality of the figures. By default, the figures are saved as png files with a size of 20 x 15 cm. The format settings can be managed using the function setDefaultPlotFormat() as illustrated below, input arguments are format, width, height, their units and the plot resolution dpi.

setDefaultPlotFormat(format = "png")

Watermark

Watermark corresponds to text in the background of plots. Watermark font properties can be set in the Theme object: reTheme$fonts$watermark.

Regarding the content of the watermark, the default content available in the Theme object (i.e. at reTheme$background$watermark in the example) is overwritten by the Workflow objects:

As a consequence, setting the watermark content needs to be performed directly with the Workflow objects: either when initializing the workflow using the input argument watermark (e.g. MeanModelWorkflow$new(..., watermark = "vignette example")); or using the workflow method $setWatermark(watermark) (e.g. myWorkflow$setWatermark("vignette example")).

The workflow method $getWatermark() prints the watermark text which will be in the background of the figures output by the workflow (e.g. myWorkflow$getWatermark()).

Note: The NULL input argument for watermark leads to using the default watermark feature.

How to set task specific properties

Each task of Workflow objects includes a field named settings. This optional field of class TaskSettings can be updated and will overwrite the default behavior of a task.

Two usual subfields of settings are: plotConfigurations and bins. Other settings can also be provided and will be detailed in the next sections.

The next section will provide the names of the plots and options that can be accessed through the field settings.

Time profiles and residuals

Regardless of the workflow subclass (MeanModelWorkflow or PopulationWorkflow), the names in the plotConfigurations list available for the "plotTimeProfilesAndResiduals" task are the following:

Since histograms are performed by the task, bins can also be defined.

Displayed names and units are usually managed through the SimulationSet and Output objects. The vignette "goodness-of-fit" provides more details about the "plotTimeProfilesAndResiduals" task.

Example: below shows a typical mean model workflow example in which plotConfigurations and bins are set for a "plotTimeProfilesAndResiduals" task.

# Get the pkml simulation file: "MiniModel2.pkml"
simulationFile <- system.file("extdata", "MiniModel2.pkml",
  package = "ospsuite.reportingengine"
)

# Define the output object
outputA <- Output$new(
  path = "Organism|A|Concentration in container",
  displayName = "Simulated concentration of A",
  displayUnit = "µmol/ml"
)

# Define the simulation set object
setA <- SimulationSet$new(
  simulationSetName = "A",
  simulationFile = simulationFile,
  outputs = outputA
)

# Create the workflow object
workflowA <-
  MeanModelWorkflow$new(
    simulationSets = setA,
    workflowFolder = "Example-A"
  )

# Set the workflow tasks to be run
workflowA$activateTasks(c("simulate", "plotTimeProfilesAndResiduals"))

The next chunk of code will define PlotConfiguration objects to be included in settings:

# Define plot configuration for obsVsPred
obsVsPredConfiguration <- PlotConfiguration$new(
  xlabel = "Observed values [µmol/ml]",
  ylabel = "Simulated values [µmol/ml]",
  watermark = "vignette"
)

# Define plot configuration for resHisto
resHistoConfiguration <- PlotConfiguration$new(
  xlabel = "Residuals",
  ylabel = "Count",
  watermark = "vignette"
)

# Update some fields of the configuration if necessary
resHistoConfiguration$background$plot$fill <- "lemonchiffon"
resHistoConfiguration$background$panel$fill <- "lemonchiffon"
resHistoConfiguration$background$panel$color <- "goldenrod3"
resHistoConfiguration$background$xGrid$color <- "goldenrod3"
resHistoConfiguration$background$yGrid$color <- "goldenrod3"

# Define plotConfigurations list
plotConfigurations <- list(
  resHisto = resHistoConfiguration,
  obsVsPred = obsVsPredConfiguration
)

# Define list to update task settings with plotConfigurations field and and bins field
mySettings <- list(
  plotConfigurations = plotConfigurations,
  bins = 3
)

Then, the settings field of the "plotTimeProfilesAndResiduals" task can be updated as shown below:

# Run the workflow
workflowA$plotTimeProfilesAndResiduals$settings <- mySettings

The run of the workflow with updated settings and get the resulting report as shown below.

Since the histogram across the all simulations did not get the plot configuration settings defined for individual simulations, the plots are quite different. However, the option bins is currently set among all plots of the task. Regarding observed vs simulated plots, the got the updated xlabel, ylabel and watermark as defined in the plot configuration.

# Run the workflow
workflowA$runWorkflow()

cat(includeReportFromWorkflow(workflowA))

# Remove the workflow folders
unlink(workflowA$workflowFolder, recursive = TRUE)

PK parameters plots

Selection, displayed names and units are usually managed through the ospsuite PKParameters objects or PkParametersInfo objects. The vignette "pk-parameters" provides more details about the "plotPKParameters" task.

For mean model workflows, the PK parameters are only summarized as tables. In the current version, there is no option for number of decimal numbers to set.

For population workflows, the parameters are described using plots which depends on the population workflow type. The names in the plotConfigurations list available for the "plotPKParameters" task are the following:

Since pediatric workflows perform VPC like plot, aggregation of the data is performed along the demography parameters. The binning of the demography parameters can be set by the optional field bins from the task field settings. This field can be either a unique value corresponding to the number of bins or a vector defining the bin edges for all the demography parameter paths.

Besides, the final plot can either link the aggregated values or plot them as stairstep. The default behaviour is to perform a stairstep plot, but this can be tuned with the optional field stairstep (TRUE/FALSE) from the task field settings.

Below shows examples of how to set such options:

# Associate the bin edges
workflowA$plotPKParameters$settings$bins <- c(0, 1, 2, 3, 5, 10)

# Associate the number of bins
workflowA$plotPKParameters$settings$bins <- 15

# Set VPC as stair step
workflowA$plotPKParameters$settings$stairstep <- TRUE

Sensitivity plots

Settings for the sensitivity plots are SensitivityPlotSettings objects. The vignette "sensitivity-analysis" provides more details about the "plotSensitivity" task.

The input argument of the SensitivityPlotSettings settings object are then (to be created using SensitivityPlotSettings$new()):

Since displayed sensitivity parameters can include long strings of characters shrinking the actual plot even using small yAxisFontSize, an algorithm providing line breaks is included in the task to prevent the shrinking issue as much as possible. Two fields are available in settings to tune the algorithm:

Absorption

The name in the plotConfigurations list available for the "plotAbsorption" task is the following:

Mass Balance

The name in the plotConfigurations list available for the "plotMassBalance" task is the following:

Another field of settings is selectedCompoundNames which allows to keep only a selected list of compounds to be kept in the mass balance plots.

Demography plots

The names in the plotConfigurations list available for the "plotDemography" task are the following:

Since pediatric workflows perform VPC like plot, aggregation of the data is performed along the demography parameters. The binning of the demography parameters can be set by the optional field bins from the task field settings. This field can be either a unique value corresponding to the number of bins or a vector defining the bin edges for all the demography parameter paths.

Besides, the final plot can either link the aggregated values or plot them as stairstep. The default behaviour is to perform a stairstep plot, but this can be tuned with the optional field stairstep (TRUE/FALSE) from the task field settings.

Similarly, parallel comparison and ratio types of population workflows perform histograms, whose binning can set using the settings field bins.



Open-Systems-Pharmacology/OSPSuite.ReportingEngine documentation built on May 1, 2024, 12:27 p.m.

R Package Documentation

rdrr.io home R language documentation Run R code online

Browse R Packages

CRAN packages Bioconductor packages R-Forge packages GitHub packages

We want your feedback!

Note that we can't provide technical support on individual packages. You should contact the package authors for that.
GitHub issue tracker
ian@mutexlabs.com
Personal blog

 
Embedding an R snippet on your website

Add the following code to your website.

For more information on customizing the embed code, read Embedding Snippets.

Close