Export calculateResiduals() and convertUnits() (#1085)

* Export `calculateResiduals()` * fix example * fix example * Export `convertUnits()` * keep similar validations together * docs * fix example * Address review comments * Fix plotting function; more code review Closes #1081
Open-Systems-Pharmacology · Aug 16, 2022 · 1252a50 · 1252a50
1 parent af89b3a
commit 1252a50
Show file tree

Hide file tree

Showing 36 changed files with 1,153 additions and 819 deletions.
diff --git a/NAMESPACE b/NAMESPACE
@@ -34,9 +34,11 @@ export(addUserDefinedPKParameter)
 export(allAvailableDimensions)
 export(allPKParameterNames)
 export(calculatePKAnalyses)
+export(calculateResiduals)
 export(clearMemory)
 export(clearOutputIntervals)
 export(clearOutputs)
+export(convertUnits)
 export(createDistributions)
 export(createImporterConfigurationForFile)
 export(createIndividual)

diff --git a/NEWS.md b/NEWS.md
@@ -8,6 +8,11 @@
     - `plotResidualsVsTime()` for time versus residuals data scatter plot.
     - `plotResidualsVsSimulated()` for simulated versus residuals data scatter plot.
 
+* Adds new helper functions to work with `DataCombined` objects:
+
+    - `convertUnits()` to convert datasets in `DataCombined` to common units.
+    - `calculateResiduals()` to calculate residuals for datasets in `DataCombined`.
+
 ## Major Changes
 
 * The class `SimulationBatch` gets a new property `id`.

diff --git a/R/data-combined.R b/R/data-combined.R
@@ -67,6 +67,7 @@
 #' # Accessing the combined data frame
 #' myDataCombined$toDataFrame()
 #'
+#' @family data-combined
 #' @docType class
 #' @export
 DataCombined <- R6::R6Class(
@@ -375,7 +376,7 @@ DataCombined <- R6::R6Class(
     #'
     #' @return
     #'
-    #' In the returned data frame, the following columns will always be present:
+    #' In the returned tibble data frame, the following columns will always be present:
     #'
     #' name - group - dataType - xValues - xDimension - xUnit - yValues -
     #' yErrorValues - yDimension - yUnit - yErrorType - yErrorUnit - molWeight

diff --git a/R/messages.R b/R/messages.R
@@ -46,8 +46,8 @@ messages$plottingWithEmptyDataCombined <- function() {
   "No plot can be created because the entered `DataCombined` object does not contain any datasets."
 }
 
-messages$plottingWithNoPairedDatasets <- function() {
-  "No plot can be created because the entered `DataCombined` object does not contain any observed-simulated datasets that can be paired."
+messages$residualsCanNotBeComputed <- function() {
+  "No residuals can be computed because the entered `DataCombined` object does not contain any observed-simulated datasets that can be paired."
 }
 
 messages$logScaleNotAllowed <- function() {

diff --git a/R/plot-individual-time-profile.R b/R/plot-individual-time-profile.R
@@ -1,6 +1,6 @@
 #' Time-profile plot of individual data
 #'
-#' @param dataCombined A `DataCombined` object.
+#' @inheritParams calculateResiduals
 #' @param defaultPlotConfiguration A `DefaultPlotConfiguration` object, which is
 #'   an `R6` class object that defines plot properties.
 #'
@@ -61,9 +61,9 @@ plotIndividualTimeProfile <- function(dataCombined,
                              quantiles = NULL) {
   # validation -----------------------------
 
-  .validateDataCombinedForPlotting(dataCombined)
   defaultPlotConfiguration <- .validateDefaultPlotConfiguration(defaultPlotConfiguration)
 
+  .validateDataCombinedForPlotting(dataCombined)
   if (is.null(dataCombined$groupMap)) {
     return(NULL)
   }
@@ -78,10 +78,8 @@ plotIndividualTimeProfile <- function(dataCombined,
 
   # data frames -----------------------------
 
-  combinedData <- dataCombined$toDataFrame()
-
   # Getting all units on the same scale
-  combinedData <- .unitConverter(combinedData, defaultPlotConfiguration$xUnit, defaultPlotConfiguration$yUnit)
+  combinedData <- convertUnits(dataCombined, defaultPlotConfiguration$xUnit, defaultPlotConfiguration$yUnit)
 
   # Datasets which haven't been assigned to any group will be plotted as a group
   # on its own. That is, the `group` column entries for them will be their names.

diff --git a/R/plot-observed-vs-simulated.R b/R/plot-observed-vs-simulated.R
@@ -51,9 +51,9 @@ plotObservedVsSimulated <- function(dataCombined,
                                     foldDistance = 2) {
   # validation -----------------------------
 
-  .validateDataCombinedForPlotting(dataCombined)
   defaultPlotConfiguration <- .validateDefaultPlotConfiguration(defaultPlotConfiguration)
 
+  .validateDataCombinedForPlotting(dataCombined)
   if (is.null(dataCombined$groupMap)) {
     return(NULL)
   }
@@ -96,10 +96,10 @@ plotObservedVsSimulated <- function(dataCombined,
   #
   # `DefaultPlotConfiguration` provides units for conversion.
   # `PlotConfiguration` provides scaling details needed while computing residuals.
-  pairedData <- .dataCombinedToPairedData(dataCombined,
+  pairedData <- calculateResiduals(dataCombined,
+    scaling = obsVsPredPlotConfiguration$yAxis$scale,
     xUnit = defaultPlotConfiguration$xUnit,
-    yUnit = defaultPlotConfiguration$yUnit,
-    scaling = obsVsPredPlotConfiguration$yAxis$scale
+    yUnit = defaultPlotConfiguration$yUnit
   )
 
   # Quit early if there is no data to visualize.
@@ -112,14 +112,14 @@ plotObservedVsSimulated <- function(dataCombined,
   #
   # This will happen in rare case scenarios where simulated data is sampled at a
   # lower frequency than observed data.
-  predValueMissingIndices <- which(is.na(pairedData$predValue))
+  predictedValuesMissingIndices <- which(is.na(pairedData$predictedValues))
 
   # Warn the user about failure to interpolate.
-  if (length(predValueMissingIndices) > 0) {
+  if (length(predictedValuesMissingIndices) > 0) {
     warning(
       messages$printMultipleEntries(
         header = messages$valuesNotInterpolated(),
-        entries = pairedData$obsTime[predValueMissingIndices]
+        entries = pairedData$xValues[predictedValuesMissingIndices]
       )
     )
   }
@@ -135,11 +135,11 @@ plotObservedVsSimulated <- function(dataCombined,
   tlf::plotObsVsPred(
     data = as.data.frame(pairedData),
     dataMapping = tlf::ObsVsPredDataMapping$new(
-      x = "obsValue",
-      y = "predValue",
+      x     = "yValues",
+      y     = "predictedValues",
       group = "group",
-      xmin = "yValuesLower",
-      xmax = "yValuesHigher"
+      xmin  = "yValuesLower",
+      xmax  = "yValuesHigher"
     ),
     foldDistance = foldDistance,
     plotConfiguration = obsVsPredPlotConfiguration

diff --git a/R/plot-residuals-vs-simulated.R b/R/plot-residuals-vs-simulated.R
@@ -50,9 +50,9 @@ plotResidualsVsSimulated <- function(dataCombined,
                                      defaultPlotConfiguration = NULL) {
   # validation -----------------------------
 
-  .validateDataCombinedForPlotting(dataCombined)
   defaultPlotConfiguration <- .validateDefaultPlotConfiguration(defaultPlotConfiguration)
 
+  .validateDataCombinedForPlotting(dataCombined)
   if (is.null(dataCombined$groupMap)) {
     return(NULL)
   }
@@ -77,10 +77,10 @@ plotResidualsVsSimulated <- function(dataCombined,
   #
   # `DefaultPlotConfiguration` provides units for conversion.
   # `PlotConfiguration` provides scaling details needed while computing residuals.
-  pairedData <- .dataCombinedToPairedData(dataCombined,
+  pairedData <- calculateResiduals(dataCombined,
+    scaling = resVsPredPlotConfiguration$yAxis$scale,
     xUnit = defaultPlotConfiguration$xUnit,
-    yUnit = defaultPlotConfiguration$yUnit,
-    scaling = resVsPredPlotConfiguration$yAxis$scale
+    yUnit = defaultPlotConfiguration$yUnit
   )
 
   # Quit early if there is no data to visualize.
@@ -99,8 +99,8 @@ plotResidualsVsSimulated <- function(dataCombined,
   tlf::plotResVsPred(
     data = as.data.frame(pairedData),
     dataMapping = tlf::ResVsPredDataMapping$new(
-      x = "predValue",
-      y = "resValue",
+      x = "predictedValues",
+      y = "residualValues",
       group = "group"
     ),
     plotConfiguration = resVsPredPlotConfiguration

diff --git a/R/plot-residuals-vs-time.R b/R/plot-residuals-vs-time.R
@@ -49,9 +49,9 @@ plotResidualsVsTime <- function(dataCombined,
                                 defaultPlotConfiguration = NULL) {
   # validation -----------------------------
 
-  .validateDataCombinedForPlotting(dataCombined)
   defaultPlotConfiguration <- .validateDefaultPlotConfiguration(defaultPlotConfiguration)
 
+  .validateDataCombinedForPlotting(dataCombined)
   if (is.null(dataCombined$groupMap)) {
     return(NULL)
   }
@@ -76,10 +76,10 @@ plotResidualsVsTime <- function(dataCombined,
   #
   # `DefaultPlotConfiguration` provides units for conversion.
   # `PlotConfiguration` provides scaling details needed while computing residuals.
-  pairedData <- .dataCombinedToPairedData(dataCombined,
+  pairedData <- calculateResiduals(dataCombined,
+    scaling = resVsTimePlotConfiguration$yAxis$scale,
     xUnit = defaultPlotConfiguration$xUnit,
-    yUnit = defaultPlotConfiguration$yUnit,
-    scaling = resVsTimePlotConfiguration$yAxis$scale
+    yUnit = defaultPlotConfiguration$yUnit
   )
 
   # Quit early if there is no data to visualize.
@@ -98,8 +98,8 @@ plotResidualsVsTime <- function(dataCombined,
   tlf::plotResVsTime(
     data = as.data.frame(pairedData),
     dataMapping = tlf::ResVsTimeDataMapping$new(
-      x = "obsTime",
-      y = "resValue",
+      x = "xValues",
+      y = "residualValues",
       group = "group"
     ),
     plotConfiguration = resVsTimePlotConfiguration