Fixes Open-Systems-Pharmacology#301 Helper function to get lines from…

… fold distance values (Open-Systems-Pharmacology#302)

* Fixes Open-Systems-Pharmacology#301 Helper function to get lines from fold distance values

* Update news, doc and style

* Update NEWS.md

* Update NEWS.md

Co-authored-by: Indrajeet Patil <patilindrajeet.science@gmail.com>

NAMESPACE

@@ -39,7 +39,6 @@ export(BoxWhiskerDataMapping)
 export(BoxWhiskerPlotConfiguration)
 export(CaptionProperties)
 export(ColorMaps)
-export(DDIComparisonTypes)
 export(DDIRatioDataMapping)
 export(DDIRatioPlotConfiguration)
 export(ExportConfiguration)
@@ -104,6 +103,7 @@ export(getGuestValuesFromDataMapping)
 export(getLabelWithUnit)
 export(getLegendCaption)
 export(getLegendPosition)
+export(getLinesFromFoldDistance)
 export(getLnTickLabels)
 export(getLogTickLabels)
 export(getPKRatioMeasure)

NEWS.md

@@ -1,7 +1,12 @@
-# tlf 1.4.0 (development versio)
+# tlf 1.4.0 (development version)
 
 ## New features
 
+* New helper functions and parameters to facilitate usage of plot functions (#301):
+
+  - Function `getLinesFromFoldDistance` tanslates fold distance values into `lines` argument for dataMapping objects.
+  - Functions `plotDDIRatio`, `plotPKRatio`, `plotObsVsPred`, `plotResVsPred` and `plotResVsTime` include optional parameters such as `foldDistance`, `deltaGuest` or `smoother`.
+
 * New helper enumerated lists: 
 
    - `TagPosition` (tag position in a plot grid) (#293)

R/ddiratio-datamapping.R

@@ -17,7 +17,7 @@ DDIRatioDataMapping <- R6::R6Class(
     #' @param deltaGuest Value of parameter `delta` in Guest et al. equation.
     #' Default value is 1.
     #' @param minRange Mininmum range for guest lines
-    #' @param lines list of ratio limits to plot as diagonal lines
+    #' @param lines List of ratio limits to display as diagonal/horizontal lines
     #' @param residualsVsObserved if true, returns a mapping for generating a residuals (predicted/observed) vs observed DDI ratio plot.  If false (default) returns a mapping for predicted vs observed DDI ratio plot.
     #' @param ... parameters inherited from \code{PKRatioDataMapping}
     #' @return A new \code{DDIRatioDataMapping} object
@@ -27,10 +27,12 @@ DDIRatioDataMapping <- R6::R6Class(
                           residualsVsObserved = FALSE,
                           ...) {
       super$initialize(...)
-      # Apply log10 transformation to lines because
-      # plot is log scaled by default and geom_abline
-      # requires the log transformed values in input of intercept
-      self$lines <- lapply(lines, log10)
+      validateIsNumeric(deltaGuest)
+      validateIsNumeric(minRange)
+      validateIsOfLength(minRange, 2)
+      validateIsLogical(residualsVsObserved)
+
+      self$lines <- lines
       self$minRange <- minRange
       self$deltaGuest <- deltaGuest
       self$residualsVsObserved <- residualsVsObserved

R/obs-vs-pred-datamapping.R

@@ -1,37 +1,37 @@
-#' @title ObsVsPredDataMapping
-#' @description  Class for mapping variables in observations vs predictions plot
-#' @export
-#' @family DataMapping classes
-ObsVsPredDataMapping <- R6::R6Class(
-  "ObsVsPredDataMapping",
-  inherit = PKRatioDataMapping,
-  public = list(
-    #' @field smoother regression function name
-    smoother = NULL,
-
-    #' @description Create a new `ObsVsPredDataMapping` object
-    #' @param lines list of lines to plot
-    #' @param smoother smoother function or parameter
-    #' To map a loess smoother to the plot, use `smoother`="loess"
-    #' @param ... parameters inherited from `XYGDataMapping`
-    #' @return A new `ObsVsPredDataMapping` object
-    initialize = function(lines = DefaultDataMappingValues$obsVsPred,
-                          smoother = NULL,
-                          ...) {
-      validateIsIncluded(smoother, c("lm", "loess"), nullAllowed = TRUE)
-
-      super$initialize(...)
-      self$lines <- lines
-      self$smoother <- smoother
-    }
-  )
-)
-
-#' @title ResVsPredDataMapping
-#' @description  Class for mapping variables in residuals vs predictions/time plot
-#' @export
-#' @family DataMapping classes
-ResVsPredDataMapping <- R6::R6Class(
-  "ResVsPredDataMapping",
-  inherit = ObsVsPredDataMapping
-)
+#' @title ObsVsPredDataMapping
+#' @description  Class for mapping variables in observations vs predictions plot
+#' @export
+#' @family DataMapping classes
+ObsVsPredDataMapping <- R6::R6Class(
+  "ObsVsPredDataMapping",
+  inherit = PKRatioDataMapping,
+  public = list(
+    #' @field smoother regression function name
+    smoother = NULL,
+
+    #' @description Create a new `ObsVsPredDataMapping` object
+    #' @param lines list of lines to plot
+    #' @param smoother smoother function or parameter
+    #' To map a loess smoother to the plot, use `smoother`="loess"
+    #' @param ... parameters inherited from `XYGDataMapping`
+    #' @return A new `ObsVsPredDataMapping` object
+    initialize = function(lines = DefaultDataMappingValues$obsVsPred,
+                          smoother = NULL,
+                          ...) {
+      validateIsIncluded(smoother, c("lm", "loess"), nullAllowed = TRUE)
+
+      super$initialize(...)
+      self$lines <- lines
+      self$smoother <- smoother
+    }
+  )
+)
+
+#' @title ResVsPredDataMapping
+#' @description  Class for mapping variables in residuals vs predictions/time plot
+#' @export
+#' @family DataMapping classes
+ResVsPredDataMapping <- R6::R6Class(
+  "ResVsPredDataMapping",
+  inherit = ObsVsPredDataMapping
+)

R/pkratio-datamapping.R

@@ -12,7 +12,7 @@ PKRatioDataMapping <- R6::R6Class(
     error = NULL,
 
     #' @description Create a new `PKRatioDataMapping` object
-    #' @param lines list of ratio limits to plot as horizontal lines
+    #' @param lines List of ratio limits to display as horizontal lines
     #' @param uncertainty mapping error bars around scatter points.
     #' Deprecated parameter replaced by `error`.
     #' @param error mapping error bars around scatter points

R/plot-ddiratio.R

@@ -5,6 +5,9 @@
 #' @inheritParams addScatter
 #' @param residualsVsObserved Optional logical value defining
 #' if DDI Ratio plot is drawn as residuals vs observed, instead of predicted vs observed.
+#' @param foldDistance Numeric values of fold distance lines to display in log plots.
+#' This argument is internally translated into `lines` field of `dataMapping`.
+#' @param deltaGuest Numeric value parameter of Guest function
 #' @param dataMapping
 #' A `DDIRatioDataMapping` object mapping `x`, `y` and aesthetic groups to their variable names of `data`.
 #' @param plotConfiguration
@@ -21,31 +24,48 @@
 #' ddiData <- data.frame(x = c(1, 2, 1, 2, 3), y = c(5, 0.2, 2, 3, 4))
 #'
 #' plotDDIRatio(data = ddiData, dataMapping = DDIRatioDataMapping$new(x = "x", y = "y"))
+#' 
+#' # Produce DDI Ratio plot with user-defined horizontal lines
+#' plotDDIRatio(
+#' data = ddiData,
+#' dataMapping = DDIRatioDataMapping$new(x = "x", y = "y"), 
+#' foldDistance = c(1, 10),
+#' deltaGuest = 1.25,
+#' residualsVsObserved = TRUE
+#' )
 #'
 plotDDIRatio <- function(data,
                          metaData = NULL,
                          dataMapping = NULL,
                          plotConfiguration = NULL,
-                         plotObject = NULL,
-                         residualsVsObserved = NULL) {
+                         residualsVsObserved = NULL,
+                         foldDistance = NULL,
+                         deltaGuest = NULL,
+                         plotObject = NULL) {
   eval(parseCheckPlotInputs("DDIRatio"))
+  validateIsLogical(residualsVsObserved, nullAllowed = TRUE)
+  validateIsNumeric(foldDistance, nullAllowed = TRUE)
+  validateIsNumeric(deltaGuest, nullAllowed = TRUE)
   mapData <- dataMapping$checkMapData(data)
   mapLabels <- getAesStringMapping(dataMapping)
 
   plotObject <- plotObject %||% initializePlot(plotConfiguration)
 
-
-  residualsVsObserved <- residualsVsObserved %||% dataMapping$residualsVsObserved %||% FALSE
-  validateIsLogical(residualsVsObserved, nullAllowed = FALSE)
-
+  dataMapping$residualsVsObserved <- residualsVsObserved %||% dataMapping$residualsVsObserved
+  dataMapping$deltaGuest <- deltaGuest %||% dataMapping$deltaGuest
+
   lineOrientation <- "diagonal"
-  if (residualsVsObserved) {
+  if (dataMapping$residualsVsObserved) {
     lineOrientation <- "ddiHorizontal"
   }
   # Include diagonal or horizontal lines depending on the plot type
+  if(!isEmpty(foldDistance)){
+    dataMapping$lines <- getLinesFromFoldDistance(foldDistance)
+  }
   for (lineIndex in seq_along(dataMapping$lines)) {
+    lineValue <- getAblineValues(dataMapping$lines[[lineIndex]], plotConfiguration$yAxis$scale)
     # position correspond to the number of layer lines already added
-    eval(parseAddLineLayer(lineOrientation, dataMapping$lines[[lineIndex]], lineIndex - 1))
+    eval(parseAddLineLayer(lineOrientation, lineValue, lineIndex - 1))
   }
   if (isEmpty(lineIndex)) {
     lineIndex <- 0
@@ -74,7 +94,7 @@ plotDDIRatio <- function(data,
     )
 
   # If uncertainty is defined, add error bars
-  if (!isOfLength(dataMapping$uncertainty, 0)) {
+  if (!isEmpty(dataMapping$error)) {
     eval(parseAddUncertaintyLayer())
   }
   eval(parseAddScatterLayer())

R/plot-obs-vs-pred.R

@@ -3,6 +3,8 @@
 #' Producing observed vs predicted plots
 #'
 #' @inheritParams addScatter
+#' @param foldDistance Numeric values of fold distance lines to display in log plots.
+#' This argument is internally translated into `lines` field of `dataMapping`.
 #' @param smoother Optional name of smoother function:
 #' \itemize{
 #' \item `"loess"` for loess regression
@@ -29,23 +31,40 @@
 #'   smoother = "lm"
 #' )
 #'
+#' # Produce Obs vs Pred plot with user-defined fold distance lines
+#' plotObsVsPred(
+#' data = obsVsPredData,
+#' dataMapping = ObsVsPredDataMapping$new(x = "x", y = "y"), 
+#' plotConfiguration = ObsVsPredPlotConfiguration$new(
+#' xScale = Scaling$log, xLimits = c(0.05, 50),
+#' yScale = Scaling$log, yLimits = c(0.05, 50)),
+#' foldDistance = c(1, 10)
+#' )
+#' 
 plotObsVsPred <- function(data,
                           metaData = NULL,
                           dataMapping = NULL,
                           plotConfiguration = NULL,
+                          foldDistance = NULL,
                           smoother = NULL,
                           plotObject = NULL) {
   eval(parseCheckPlotInputs("ObsVsPred"))
   validateIsIncluded(smoother, c("loess", "lm"), nullAllowed = TRUE)
+  validateIsNumeric(foldDistance, nullAllowed = TRUE)
   dataMapping$smoother <- smoother %||% dataMapping$smoother
   mapData <- dataMapping$checkMapData(data)
   mapLabels <- getAesStringMapping(dataMapping)
 
   plotObject <- plotObject %||% initializePlot(plotConfiguration)
 
   # Add diagonal lines with offset defined in lines of dataMapping
+  if(!isEmpty(foldDistance)){
+    dataMapping$lines <- getLinesFromFoldDistance(foldDistance)
+  }
   for (lineIndex in seq_along(dataMapping$lines)) {
-    eval(parseAddLineLayer("diagonal", dataMapping$lines[[lineIndex]], lineIndex - 1))
+    lineValue <- getAblineValues(dataMapping$lines[[lineIndex]], plotConfiguration$yAxis$scale)
+    # position correspond to the number of layer lines already added
+    eval(parseAddLineLayer("diagonal", lineValue, lineIndex - 1))
   }
   if (isEmpty(lineIndex)) {
     lineIndex <- 0

R/plot-pkratio.R

@@ -3,6 +3,8 @@
 #' Producing PK Ratio plots
 #'
 #' @inheritParams addScatter
+#' @param foldDistance Numeric values of fold distance lines to display in log plots.
+#' This argument is internally translated into `lines` field of `dataMapping`.
 #' @param dataMapping
 #' A `PKRatioDataMapping` object mapping `x`, `y` and aesthetic groups to their variable names of `data`.
 #' @param plotConfiguration
@@ -19,19 +21,31 @@
 #' pkData <- data.frame(x = c(1, 2, 1, 2, 3), y = c(5, 0.2, 2, 3, 4))
 #'
 #' plotPKRatio(data = pkData, dataMapping = PKRatioDataMapping$new(x = "x", y = "y"))
+#' 
+#' # Produce PK Ratio plot with user-defined horizontal lines
+#' plotPKRatio(
+#' data = pkData,
+#' dataMapping = PKRatioDataMapping$new(x = "x", y = "y"), 
+#' foldDistance = c(1, 10)
+#' )
 #'
 plotPKRatio <- function(data,
                         metaData = NULL,
                         dataMapping = NULL,
                         plotConfiguration = NULL,
+                        foldDistance = NULL,
                         plotObject = NULL) {
   eval(parseCheckPlotInputs("PKRatio"))
+  validateIsNumeric(foldDistance, nullAllowed = TRUE)
   mapData <- dataMapping$checkMapData(data)
   mapLabels <- getAesStringMapping(dataMapping)
 
   plotObject <- plotObject %||% initializePlot(plotConfiguration)
-
+  
   # Include horizontal lines
+  if(!isEmpty(foldDistance)){
+    dataMapping$lines <- getLinesFromFoldDistance(foldDistance)
+  }
   for (lineIndex in seq_along(dataMapping$lines)) {
     # position correspond to the number of layer lines already added
     eval(parseAddLineLayer("horizontal", dataMapping$lines[[lineIndex]], lineIndex - 1))