Create VPC plot

plotVPC_IQRdataVPC.Rd

Determines CI for the quantiles across simulated trials and quantiles of the observation and creates VPC plot.

plotVPC_IQRdataVPC(
  dataVPC,
  stratifyBy = NULL,
  periodBy = NULL,
  FLAGstratifyByPeriod = FALSE,
  filename = NULL,
  FLAGlogY = FALSE,
  FLAGuseTAD = FALSE,
  FLAGdataPlotOnly = FALSE,
  FLAGnoDataSummary = FALSE,
  FLAGnoDataPoints = FALSE,
  FLAGrmBLQ = FALSE,
  FLAGpc = FALSE,
  FLAGplotBins = FALSE,
  FLAGplotN = FALSE,
  opt_CIRibbons = c("linear_extend", "constant", "linear"),
  title = NULL,
  subtitle = NULL,
  BIN.column = NULL,
  BIN.breaks = NULL,
  BIN.groupsize = NULL,
  BIN.lambda = 1,
  BIN.resolution = 0.1,
  CIlevel = 95,
  percentiles = c(5, 95),
  alphaDataPoints = 0.4,
  nrow = 1,
  ncol = 1,
  ggLayers,
  filterExpr,
  mutateExpr,
  colorBy = NULL,
  FLAGaddSummaryNotByColor = TRUE
)

Arguments

dataVPC: Named list with simulated (sim) and potentially typical predictions for observed (obs) data
stratifyBy: Column name used to stratify VPC plots
periodBy: Colum name identifying different periods (time-varying categorical covariates) Time courses are binned and plotted separately. Whether they are plotted in the same panel is set by FLAGstratifyByPeriod
FLAGstratifyByPeriod: Flag whether period are plotted in separate panels
filename: Filename for export of the VPC to a PDF. If NULL object including plotting data is returned.
FLAGlogY: logical. If TRUE the Y axis will be shown in logscale.
FLAGuseTAD: logical. If TRUE then observed time after previous dose (TAD) is used for x-axis. If FALSE then actual TIME is used.
FLAGdataPlotOnly: logical. If TRUE then no simulation is done and only the data and lines for the percentiles are plotted. This allows to find suitable settings for the binning parameters BIN.groupsize and BIN.lambda.
FLAGnoDataSummary: logical. if TRUE then no data summary is plotted. Together with FLAGnoDataPoints this can be used to only visualise simulations.
FLAGnoDataPoints: If TRUE then data points will be ommitted but percentiles for data will be shown
FLAGrmBLQ: Flag whether to remove BLQ values from simulated data AND observations
FLAGpc: Flag whether to apply prediction correction. Can only be performed if typical prediction are present in dataVPC
FLAGplotBins: Flag whether to plot the bin boundaries as vertical lines
FLAGplotN: Flag whether to display number of subjects in panel
opt_CIRibbons: Default: "linear_extend". Character flag to choose how simulations should be displayed. Available options: c("linear_extend", "constant", "linear"). For dataVPC with simtimeOption = "simTAD" or simtimeOption = "simTFD", only "linear" is supported and automatically used.
title: Character string to be plotted as plot title (on each page)
subtitle: Character string to be plotted as plot subtitle (on each page)
BIN.column: Column name of integer column assigning the observations to time bins. Defaults to NULL such that bins are automatically generated or the user-provided BIN.breaks are used.
BIN.breaks: Numerical vector with bin borders that are used for the observation times. Defaults to NULL such that bins are automatically generated. This input is ignored if BIN.column is provided.
BIN.groupsize: Smallest expected group size for the binning. By default the round(0.5 x number of subjects) in the dataset is used.
BIN.lambda: Penalization of intra-group variance, set to 1 to have more groups and set to 0 to get less but larger groups.
BIN.resolution: Gaps between groups of data points greater than resolution lead to separation of groups
CIlevel: Confidence interval level for percentiles (in percent)
percentiles: numeric vector with 1, 2 or 3 entries between 0 and 100 to be used as percentiles for data and simulation plots. 1 entry: only this percentile is plotted, e.g. for 50 the median is visualized. 2 entries: low, and high percentiles were provided and median should also be plotted. 3 entries: low, medium and high percentiles were provided in this order.
alphaDataPoints: Alpha transparency level for data points
nrow: Number of panel rows for plot layout
ncol: Number of panel columns for plot layout
ggLayers: Additional ggplot layers which are added to the plots, e.g. labs(x="new x label") + geom_text(aes(label = IXGDF, data = obs)) + coord_cartesian(ylim = c(0,10)). You have access to the data.frames which you can also see in plot$OUTPUT1$plotdata, i.e. obs, stratsummSim, stratsummObs, and binborders. See Example 5 from the examples section.
filterExpr: Logical expression to subset dataVPC. You can use all columns which appear in dataVPC$obs. For example, you can filter with respect to TIME by filterExpr = TIME <= 24.
mutateExpr: Expression to add or mutate existing columns in dataVPC. This expression MUST start with `:=`. You can use all columns which appear in dataVPC$obs for your expressions. For example, you can add a covariate column with nicer labels by mutateExpr = ``:=``(SEX = ifelse(SEX==1, "female", "male")).
colorBy: Column name to stratify observations by color. Simulation summaries are never stratified by color.
FLAGaddSummaryNotByColor: Add an "Overall" summary in addition to the stratification by colorBy

Value

If no filename is given, ggplot object with additional plotting information

Details

Input dataVPC is the output of vpc_IQRnlmeProject.

Author

Anne Kuemmel, IntiQuan, additions from Daniel Lill, IntiQuan

Examples

if (FALSE) { # \dontrun{

# Advanced uses of plotVPC_IQRdataVPC

# Load data
dataNLME <- getData_IQRnlmeProject(system.file("examples/NLMEProjects/Webinar/03-Models/00_FinalPKmodel/", package = "IQRtools"), FLAGcolonsAsSpaces = TRUE, FLAGcatColsAsFactor = TRUE)
dataVPC <- readRDS(system.file("examples/VPC/Output/Webinar/vpcdata_00_FinalPKmodel_modified.rds", package = "IQRtools"))

# Example 1.1
# * Plot using dataNLME only - no need for dataVPC with simulations
# * filterExpr to subset data - in this case multiple dose regimens, second full profile
# * colorBy
# * FLAGaddSummaryNotByColor: Adds a "color level" called "Overall"
plotVPC_IQRdataVPC(dataNLME, FLAGlogY = TRUE,
                   filterExpr = grepl("daily", TRTNAME) & TIME > 480 & TIME < 520,
                   colorBy = "SEX")
# Example 1.2
# * FLAGaddSummaryNotByColor = FALSE: Don't show overall summary
plotVPC_IQRdataVPC(dataNLME, FLAGlogY = TRUE,
                   filterExpr = grepl("daily", TRTNAME) & TIME > 480 & TIME < 520,
                   colorBy = "SEX", FLAGaddSummaryNotByColor = FALSE)
# Example 1.3
# * Use dataVPC instead of dataVPC
plotVPC_IQRdataVPC(dataVPC, FLAGlogY = TRUE,
                   filterExpr = grepl("daily", TRTNAME) & TIME > 480 & TIME < 520,
                   colorBy = "SEX", FLAGaddSummaryNotByColor = FALSE,
                   ggLayers = geom_text(aes(x=-Inf,y=Inf, label = "Note that the model apparently\ndoes not account well for SEX"), hjust = -0.1, vjust = 2, color = "red", fontface = "bold"))

# Example 2: Danger zone, use at your own risk
# * Dose-normalize with mutateExpr by using the DOSE column (This column should be
#   double-checked for correctness. Note that BLOQ handling etc must be ensured by the user!)
# * Show only median
plotVPC_IQRdataVPC(dataNLME, FLAGlogY = TRUE,
                   filterExpr = grepl("daily", TRTNAME) & TIME > 480 & TIME < 520,
                   mutateExpr = `:=`(DV = DV / DOSE),
                   colorBy = "SEX",
                   percentiles = c(50),
                   ggLayers = labs(y = "Dose-normalized concentration (ug/mL/mg)"))

# Example 3: Danger zone, use at your own risk
# * Dose-normalize with mutateExpr by using the DOSE column (This column should be
#   double-checked for correctness. Note that BLOQ handling etc must be ensured by the user!)
# * Plot using dataVPC
plotVPC_IQRdataVPC(dataVPC, FLAGlogY = TRUE,
                   filterExpr = grepl("daily", TRTNAME) & TIME > 480 & TIME < 520,
                   mutateExpr = `:=`(DV = DV / DOSE),
                   colorBy = "SEX",
                   percentiles = c(50),
                   ggLayers = labs(y = "Dose-normalized concentration (ug/mL/mg)"))

# Example 4
# * mutateExpr
plotVPC_IQRdataVPC(dataVPC, FLAGlogY = TRUE,
                   filterExpr = grepl("daily", TRTNAME) & TIME > 480 & TIME < 520,
                   mutateExpr = `:=`(SEX = factor(ifelse(SEX == "male", "M", "F"), c("M", "F"))),
                   colorBy = "SEX")

# Example 5
# * ggLayers to add geoms and other ggplot layers
# 1. turn font to bold
# 2. add lines for each individual
# 3. Add common y scale for all panels
plotVPC_IQRdataVPC(dataVPC, FLAGlogY = TRUE,
                   filterExpr = grepl("daily", TRTNAME) & TIME > 480 & TIME < 520,
                   stratifyBy = "SEX",
                   ggLayers = geom_line(aes(y = DV, group = USUBJID), data = obs, alpha = 0.1) +
                     theme(text = element_text(face = "bold")) +
                     coord_cartesian(ylim = c(0.001,1)),
                     ncol = 2)

# Example 6
# * Constant ribbons per bin
plotVPC_IQRdataVPC(dataVPC, FLAGlogY = TRUE,
                   filterExpr = grepl("daily", TRTNAME) & TIME > 480 & TIME < 520,
                   opt_CIRibbons = "constant")


# Example 7
# * Manually fix binning

# 7.0 Load and subset data
dataVPC <- readRDS(system.file("examples/VPC/Output/Webinar/vpcdata_00_FinalPKmodel_modified.rds", package = "IQRtools"))
dataVPC <- filterMutateDataVPC(dataVPC, TIME < 450)

# 7.1 Calculate bins automatically: Run plotVPC to invoke the binning algorithm
pl <- plotVPC_IQRdataVPC(dataVPC, FLAGplotBins = TRUE)

# 7.2 Collect the resulting BIN column and add it to the VPC data
bins <- extractBins_VPCplot(pl)
dataVPC$obs <- merge(dataVPC$obs, bins, by = "IXGDF", all.x = TRUE)

# 7.3 Apply the manual fix: We want to merge bins 6 and 7. We do this by simply assigning BIN = 6 when BIN is 7.
dataVPC$obs$BIN <- case_when(dataVPC$obs$BIN == 7 ~ 6,
                             TRUE                 ~ dataVPC$obs$BIN)

# 7.4 Plot, but now use BIN.column instead of the automatic binning algorithm
pl <- plotVPC_IQRdataVPC(dataVPC, FLAGplotBins = TRUE, BIN.column = "BIN")


# Example 8
# * Exposure response VPCs: Re-mapping of x axis

# 8.0 Prepare mockup exposure-response dataset
# * Add CMAX per subject to the dataset
dataVPC <- readRDS(system.file("examples/VPC/Output/Webinar/vpcdata_00_FinalPKmodel_modified.rds", package = "IQRtools"))
dataVPC <- filterMutateDataVPC(dataVPC, filterExpr = grepl("daily", TRTNAME) & TIME > 480 & TIME < 520 & EVID == 0)
dCmax <- dataVPC$obs  %>% filter(EVID == 0) %>% group_by(USUBJID) %>% summarize(CMAX = max(DV))
dataVPC$obs <- merge(dataVPC$obs, dCmax, by = "USUBJID")
# * Filter to CMAX observations and create fake exposure response data based on sigmoidal relationship
dataVPC <- filterMutateDataVPC(dataVPC, DV == CMAX)
dataVPC <- filterMutateDataVPC(dataVPC, mutateExpr = `:=`(DV = DV^3 / (0.2^3 + DV^3) * rnorm(.N,1,0.1) + 0.08))

# 8.1 Exposure-response VPC:
# * Re-map CMAX as TIME to be used as x axis
# * Use ggLayers to overwrite axis labels
plotVPC_IQRdataVPC(dataVPC, FLAGlogY = TRUE,
                   mutateExpr = `:=`(TIME = CMAX),
                   BIN.breaks = c(0,0.04,0.8,0.1,0.2,0.3,0.4),
                   ggLayers = labs(x = "Cmax (ug/mL)", y = "Response (a.u.)") +
                     scale_x_log10_IQRtools(n_minor = 3)
)

# 8.2 Dose-response VPC
# * Re-map DOSE as TIME to be used as x axis.
# * Use ggLayers to overwrite axis labels
plotVPC_IQRdataVPC(dataVPC, FLAGlogY = TRUE,
                   mutateExpr = `:=`(TIME = DOSE),
                   opt_CIRibbons = "constant",
                   BIN.column = "DOSE",
                   ggLayers = labs(x = "Daily dose (mg)", y = "Response (a.u.)")
)

} # }