In Open-Systems-Pharmacology/TLF-Library: TLF Library

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  dpi = 300,
  fig.align = "center",
  out.width = "100%",
  fig.height = 6,
  fig.width = 8,
  fig.showtext = TRUE
)

require(tlf)

1. Introduction

The following vignette aims at documenting and illustrating workflows for producing PK ratio plots using the tlf-Library.

This vignette focuses PK ratio plots examples. Detailed documentation on typical tlf workflow, use of AgregationSummary, DataMapping, PlotConfiguration, and Theme can be found in vignette("tlf-workflow").

2. Illustration of basic PK ratio plots

2.1. Data

The data showed in the sequel is available at the following path: system.file("extdata", "test-data.csv", package = "tlf"). In the code below, the data is loaded and assigned to pkRatioData.

# Load example
pkRatioData <- read.csv(
  system.file("extdata", "test-data.csv", package = "tlf"),
  stringsAsFactors = FALSE
)

# pkRatioData
knitr::kable(utils::head(pkRatioData), digits = 2)

A list of information about pkRatioData can be provided through metaData.

# Load example
pkRatioMetaData <- list(
  Age = list(
    dimension = "Age",
    unit = "yrs"
  ),
  Obs = list(
    dimension = "Clearance",
    unit = "dL/h/kg"
  ),
  Pred = list(
    dimension = "Clearance",
    unit = "dL/h/kg"
  ),
  Ratio = list(
    dimension = "Ratio",
    unit = ""
  )
)

knitr::kable(data.frame(
  Variable = c("Age", "Obs", "Pred", "Ratio"),
  Dimension = c("Age", "Clearance", "Clearance", "Ratio"),
  Unit = c("yrs", "dL/h/kg", "dL/h/kg", "")
))

2.2. plotPKRatio

The function plotting PK ratios is: plotPKRatio(). Basic documentation of the function can be found using: ?plotPKRatio. The typical usage of this function is: plotPKRatio(data, metaData = NULL, dataMapping = NULL, plotConfiguration = NULL). The output of the function is a ggplot object. It can be seen from this usage that only data is a necessary input. Default set ups are used for metaData, dataMapping and plotConfiguration within the call of plotPKRatio. For instance, if dataMapping is not provided, smart mapping will check if data contains "x" and "y" columns. If the data has only two columns not named "x" and "y", it will assume the first one should be plot in x-axis and the second in y-axis. Then, PKRatioPlotConfiguration is initialized if not provided, defining a standard configuration with PK Ratio Plot as title, the current date as subtitle and using predefined fonts as defined by the current theme.

2.3. Minimal example

The minimal example can work using directly the function plotPKRatio(data = pkRatioData[, c("Age", "Ratio")]).

plotPKRatio(data = pkRatioData[, c("Age", "Ratio")])

2.4. Examples with dataMapping

For PK ratio, the dataMapping class PKRatioDataMapping includes 4 fields: x, y, groupMapping and lines. x and y define which variables from the data will be plotted in X- and Y-axes, groupMapping is a class mapping which aesthetic property will split which variables, and lines defines horizontal lines performed in PK ratio plots.

2.4.1 groupMapping

Some variables can be used to cluster the data. To this end, PKRatioDataMapping objects include GroupMapping objects that can define how to cluster based on a variable or a data.frame. As illustrated below, most of the time, the direct input of color and shape is faster to define such objects. Consequently, the following examples are identical:

# Two-step process
colorMapping <- GroupMapping$new(color = "Sex")
dataMappingA <- PKRatioDataMapping$new(
  x = "Age",
  y = "Ratio",
  groupMapping = colorMapping
)

print(dataMappingA$groupMapping$color$label)

# One-step process
dataMappingB <- PKRatioDataMapping$new(
  x = "Age",
  y = "Ratio",
  color = "Sex"
)

print(dataMappingB$groupMapping$color$label)

Then, in this example, plotPKRatio can use the groupMapping to split the data by "Gender" and associate different colors to each "Gender":

plotPKRatio(
  data = pkRatioData,
  dataMapping = dataMappingB
)

Multiple groupMappings can be performed for PK ratio: data can be regrouped by color, shape and/or size. The next example uses 2 groups in the groupMapping: One group splits "Gender" by color, the other splits shape by "Amount" and "Compound".

dataMapping2groups <- PKRatioDataMapping$new(
  x = "Age",
  y = "Ratio",
  color = "Sex",
  shape = c("Country", "AgeBin")
)
plotPKRatio(
  data = pkRatioData,
  dataMapping = dataMapping2groups
)

The last examples uses another feature available in the groupMapping class. The class can be initialized using a data.frame where the last column of the data.frame will be used to split the data. In the following example, the data.frame is the following:

groupDataFrame <- data.frame(
  AgeBin = rep(c("Peds", "Adults"), 6),
  Country = rep(rep(c("Canada", "Germany", "France"), each = 2), 2),
  Sex = rep(c("Male", "Female"), each = 6),
  Group = paste(rep(c("Young", "Old"), 6), rep(rep(c("Canadian", "German", "French"), each = 2), 2), rep(c("Males", "Females"), each = 6))
)

knitr::kable(groupDataFrame)

The dataMapping introduced below will split the color and shape using the data frame.

dataMappingDF <- PKRatioDataMapping$new(
  x = "Age",
  y = "Ratio",
  color = groupDataFrame,
  shape = groupDataFrame
)
plotPKRatio(
  data = pkRatioData[!(pkRatioData$Country %in% "France"), ],
  dataMapping = dataMappingDF
)

2.4.2 PK values defined in lines

In PK ratio examples, usually horizontal lines are added allowing to flag values in and out of the [0.67-1.5] as well as [0.5-2.0] ranges. The value mapping these horizontal lines was predefined as a list: "pkRatioLine1" is 1, "pkRatioLine2" is c(0.67, 1.5) and "pkRatioLine3" is c(0.5, 2). Consequently, for any default PKRatioDataMapping, you have:

linesMapping <- PKRatioDataMapping$new()
linesMapping$lines

Overwriting these value is possible by updating the value either when initializing the mapping or afterwards. For instance:

linesMapping <- PKRatioDataMapping$new(
  lines = list(pkRatio1 = 1, pkRatio2 = c(0.2, 5)),
  x = "Age",
  y = "Ratio",
  color = "Sex"
)
plotPKRatio(
  data = pkRatioData,
  dataMapping = linesMapping
)

2.5. Qualification of PK Ratios

The qualification of the PK Ratios can be performed using getPKRatioMeasure. This function return a data.frame with the PK ratios within specific ranges. As a default, these ranges are within 1.5 and 2 folds. However, they can be updated using the option ratioLimits = when running the function.

# Test of getPKRatioMeasure
PKRatioMeasure <- getPKRatioMeasure(data = pkRatioData[, c("Age", "Ratio")])

knitr::kable(
  x = PKRatioMeasure,
  caption = "Qualification of PK Ratios"
)

2.6. Plot Configuration

To configure the plot properties, PKRatioPlotConfiguration objects can be used. They combine multiple features that set the plot properties. PK ratio plot consists in lines and points. As illustrated in the vignette related to PlotConfiguration objects and Theme, you can tune the aesthetic maps and their selections (see vignette("plot-configuration") and vignette("theme-maker")). Colors, shapes and size of the PK ratio scatter points can be tuned in the plotConfiguration points field. Likewise, colors, linetype and size of the PK ratio lines can be tuned in the plotConfiguration lines field.

Open-Systems-Pharmacology/TLF-Library documentation built on Feb. 8, 2025, 11:22 a.m.