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

library(ospsuite.reportingengine)

Overview

In Mean Model workflows, the Mass Balance task (plotMassBalance) aims at reporting diagnostics of the simulation mass balance.

The diagnostic plots correspond to 5 plots for each molecule (or group of molecules if defined by user) :

• Plot 1: Amount vs time
• Plot 2: Cumulative amount vs time in which the amounts of all the molecule paths included are stacked up.
• Plot 3: Normalized amount vs time in which the amounts are normalized by the drug mass applied at the current time.
• Plot 4: Normalized cumulative amount vs time in which the cumulative amounts are normalized by the drug mass applied at the current time.
• Plot 5: Pie Chart displaying the fraction of drug mass at the last simulated time point for all the molecule paths included.

Since version 2.3, normalization uses the current drug mass and not the final drug mass. As a result, normalized plots 3 and 4 provide more realistic results in case of multiple applications.

Regular mass balance workflow

In the example below, the mass balance task is performed using the default settings. By default, the mass balance is performed for each unique xenobiotic molecule (check Simulation$allXenobioticFloatingMoleculeNames() for more details).

The legend of the mass balance corresponds to the molecule name associated with the compartment name.

Code

# Define file paths for pkml simulation
simulationFile <- system.file("extdata", "Aciclovir.pkml", package = "ospsuite.reportingengine")

simulationSet <- SimulationSet$new(
  simulationSetName = "Aciclovir",
  simulationFile = simulationFile
)
massBalanceWorkflow <- MeanModelWorkflow$new(
  simulationSets = simulationSet,
  workflowFolder = "Mass-Balance-Workflow"
)

massBalanceWorkflow$inactivateTasks(massBalanceWorkflow$getAllTasks())
massBalanceWorkflow$activateTasks("plotMassBalance")
massBalanceWorkflow$runWorkflow()

cat(includeReportFromWorkflow(massBalanceWorkflow))

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

Mass balance settings

The mass balance task can now be customized using settings defined through the SimulationSet field massBalanceFile as a json file.

The settings aims at defining criteria for grouping molecule paths for a molecule or group of molecules. These settings can be useful especially when the simulation includes metabolites that need to be appropriately displayed in the diagnostics. For each plot the file needs to include the following fields:

• "Name": name of the sub-section in report
• "Molecules": array of the molecule names (or/and metabolites) to be included in the mass balance
• "Groupings": array of the grouping names and criteria

Groupings

The field "Groupings" is an array that defines how to group and label molecule paths in the mass balance diagnostic plots. Thus, each element of "Groupings" includes the following fields:

• "Name": reported name of the group
• "Include": array of included molecule paths
• "Exclude": array of excluded molecule paths (optional)
• "ExcludePreviousGroupings": logical to exclude molecule paths that have been already included in previous groupings (optional - default is true)

Note that inclusion and exclusion criteria for molecule paths leverage wild card symbols (*).

The most common use case is to include all the paths for specific compartments such as Plasma. Here this would translate as:

{
  "Name": "Plasma",
  "Include": ["Organism|**|Plasma|Aciclovir"]
}

Another use case is when a metabolite is defined using the molecule name as prefix. Then, the metabolite can be included in the grouping.

{
  "Name": "Plasma for Aciclovir and metabolites", 
  "Include": ["Organism|**|Plasma|Aciclovir*"]
}

A workflow leveraging mass balance settings

In this workflow, the following mass balance settings file is used. The file is also available through the following link mass-balance-settings.json.

cat(
  c(
    "```json",
    readLines(
      system.file(
        "extdata", "mass-balance-settings.json",
        package = "ospsuite.reportingengine"
      ),
      warn = FALSE
    ),
    "```"
  ),
  sep = "\n"
)

The workflow is similar to the previous one except that the mass balance settings file is provided to the SimulationSet object.

Code

simulationFile <- system.file("extdata", "Aciclovir.pkml", package = "ospsuite.reportingengine")
massBalanceFile <- system.file("extdata", "mass-balance-settings.json", package = "ospsuite.reportingengine")

simulationSet <- SimulationSet$new(
  simulationSetName = "Aciclovir",
  simulationFile = simulationFile,
  massBalanceFile = massBalanceFile
)
massBalanceWorkflow <- MeanModelWorkflow$new(
  simulationSets = simulationSet,
  workflowFolder = "Mass-Balance-Workflow"
)

massBalanceWorkflow$inactivateTasks(massBalanceWorkflow$getAllTasks())
massBalanceWorkflow$activateTasks("plotMassBalance")
massBalanceWorkflow$runWorkflow()

Since the settings included 2 plots, the report includes 2 sub-sections.

cat(includeReportFromWorkflow(massBalanceWorkflow))

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

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