plot_expirest_osle: Illustrating the ordinary shelf life estimate (osle)

Description

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

Usage

plot_expirest_osle(
  model,
  show_grouping = "yes",
  response_vbl_unit = NULL,
  y_range,
  x_range = NULL,
  plot_option = "full",
  ci_app = "line"
)

Value

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

Model: The ‘expirest_osle’ object that was passed via the model argument.
Expiry: 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.

Arguments

model: An ‘expirest_osle’ object, i.e. a list returned by the expirest_osle() function.
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.
plot_option: A character string of either "full" or "lean", i.e. specifying if all the information should be put out on the plot (option "full") or only basic information (option "lean"), i.e. the data points, the fitted regression line with the confidence interval, the specification limit(s) and the estimated shelf life limit(s). 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_osle() 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_osle() 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 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_osle() 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 an "ordinary shelf life estimation" (osle).
res1 <-
  expirest_osle(data = exp1[exp1$Batch %in% c("b2", "b5", "b7"), ],
                response_vbl = "Potency", time_vbl = "Month",
                batch_vbl = "Batch", sl = 95, sl_sf = 3, srch_range = c(0, 500))

# Pass the 'expirest_osle' object on to the plot_expirest_osle() function.
# This function does not produce any output. It returns a 'plot_expirest_osle'
# object that is essentially an 'expirest_osle' object augmented by a 'ggplot'
# object.
gg1 <- plot_expirest_osle(
  model = res1, show_grouping = "no", response_vbl_unit = "%",
  y_range = c(93, 107), x_range = NULL, 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 = "Ordinary Shelf Life Estimation (OSLE)",
                   x = "Time [months]", y = "Potency [% LC]") +
    scale_x_continuous(limits = c(-1, 31), breaks = seq(0, 30, 6))
}

# Illustration of the grouping
gg2 <- plot_expirest_osle(
  model = res1, show_grouping = "yes", response_vbl_unit = "%",
  y_range = c(93, 107), x_range = c(0, 35), plot_option = "full",
  ci_app = "line")
gg2

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

gg3 <- plot_expirest_osle(
  model = res2, show_grouping = "yes", response_vbl_unit = "%",
  y_range = c(83, 107), x_range = c(0, 43), plot_option = "full",
  ci_app = "ribbon")
gg3