plot_expirest_wisle: Illustrating the what-if (approach for) shelf life estimate (wisle)

Description

The function plot_expirest_wisle() makes a graphical display of the shelf life estimate done by the expirest_wisle() function.

Usage

plot_expirest_wisle(
  model,
  rl_index = 1,
  show_grouping = "yes",
  response_vbl_unit = NULL,
  y_range,
  x_range = NULL,
  scenario = "standard",
  plot_option = "full",
  ci_app = "line"
)

Value

An object of class ‘plot_expirest_wisle’ is returned invisibly consisting of the following elements:

Model: The ‘expirest_wisle’ object that was passed via the model argument.
Expiery: A data frame of type expiry.
Graph: A ‘ggplot2’ object for the graphical display.
Prediction: A data frame of the predicted values.
text: A data frame of the text elements on the plot.
hlines: A data frame of the horizontal line elements on the plot.
vlines: A data frame of the vertical line elements on the plot.
segments: A data frame of segment line elements on the plot.
arrow: A data frame of arrow elements on the plot.

Arguments

model: An ‘expirest_wisle’ object, i.e. a list returned by the expirest_wisle() function.
rl_index: A positive integer specifying which of the release limit values that have been handed over to expirest_wisle() should be displayed. The default value is 1.
show_grouping: A character string specifying if the grouping of the data should be taken into account (“yes”) or not (“no”), i.e. if the results of the most appropriate model should be shown or the results from the marginal analysis ignoring the grouping (being equivalent with the common intercept / common slope case). The default is "yes".
response_vbl_unit: A character string specifying the unit associated with the response variable. The default is NULL.
y_range: A numeric vector of the form c(min, max) specifying the range of the response variable to be plotted.
x_range: A numeric vector of the form c(min, max) specifying the range of the time variable to be plotted. The default is NULL and the \(x\) range is calculated automatically on the basis of the estimated shelf life.
scenario: A character string specifying if the plot should be extended (with respect to the \(x\) axis) up to the “standard scenario” ("standard") or up to the “worst case scenario” ("worst"). The default is "standard".
plot_option: A character string of either "full", "lean1", "lean2", "basic1" and "basic2", specifying if all the information should be shown in the plot (option "full") or only basic information (options "lean" and "basic"). Full means the data points, the fitted regression line with the confidence or prediction interval, the specification limit(s) and the estimated shelf life. The default is "full".
ci_app: A character string of either "line" or "ribbon", specifying the appearance of the confidence interval, i.e. if the limits should be plotted as lines (option "line") or as a shaded ribbon (option "ribbon"). The default is "line".

Details

The function plot_expirest_wisle() uses the data and the information about the linear model that was used for the estimation of the shelf life by aid of the expirest_wisle() function. It plots a graph of the time course of a parameter, a linear regression line fitted to the data and the associated confidence or prediction interval. In addition, it shows features of the worst case scenario shelf life estimation.

For plotting, the ggplot() function from the ‘ggplot2’ package is used. The various arguments can be used to control the appearance of the plot. The ‘ggplot2’ object of the generated plot is contained in the Graph element of the list that is returned by plot_expirest_wisle() and can be used to modify the appearance of the graph.

Examples

Run this code

# Potency stability data (in % of label claim (LC)) of five batches of a drug
# product obtained over a 24 months period:
str(exp1)

# 'data.frame':	53 obs. of  3 variables:
# $ Batch  : Factor w/ 6 levels "b2","b3","b4",..: 1 1 1 1 1 1 1 1 1 1 ...
# $ Month  : num  0 1 3 3 6 6 12 12 24 24 ...
# $ Potency: num  101 101.3 99.8 99.2 99.5 ...

# Start by making a "what-if (approach for) shelf life estimation" (wisle)
res1 <-
  expirest_wisle(data = exp1[exp1$Batch %in% c("b2", "b5", "b7"), ],
                 response_vbl = "Potency", time_vbl = "Month",
                 batch_vbl = "Batch", rl = 98, rl_sf = 3, sl = 95,
                 sl_sf = 3, srch_range = c(0, 500))

# Pass the 'expirest_wisle' object on to the plot_expirest_wisle() function.
# This function does not produce any output. It returns a 'plot_expirest_wisle'
# object that is essentially an 'expirest_wisle' object augmented by a 'ggplot'
# object.
gg1 <- plot_expirest_wisle(
  model = res1, rl_index = 1, show_grouping = "no",
  response_vbl_unit = "%", y_range = c(93, 107), x_range = NULL,
  scenario = "standard", plot_option = "full", ci_app = "line")
gg1

# Since the element gg1$Graph is a 'ggplot' object it can be used for further
# manipulation by aid of 'ggplot2' functions.
if (requireNamespace("ggplot2")) {
  library(ggplot2)

  gg1$Graph + labs(title = "What-if Shelf Life Estimation (WISLE)",
                   x = "Time [months]", y = "Potency [% LC]") +
    scale_x_continuous(limits = c(-5, 31), breaks = seq(0, 30, 6))
}

# Illustration of the grouping
gg2 <- plot_expirest_wisle(
  model = res1, rl_index = 1, show_grouping = "yes",
  response_vbl_unit = "%", y_range = c(93, 107), x_range = NULL,
  scenario = "standard", plot_option = "full", ci_app = "line")
gg2

# Repeat this for a different intercept / different slope (dids) model.
res2 <-
  expirest_wisle(data = exp1[exp1$Batch %in% c("b4", "b5", "b8"), ],
                 response_vbl = "Potency", time_vbl = "Month",
                 batch_vbl = "Batch", rl = 98, rl_sf = 3, sl = 95,
                 sl_sf = 3, srch_range = c(0, 500))

gg3 <- plot_expirest_wisle(
  model = res2, rl_index = 1, show_grouping = "yes",
  response_vbl_unit = "%", y_range = c(89, 107), x_range = c(0, 26),
  scenario = "standard", plot_option = "full", ci_app = "ribbon")
gg3