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,
  x_range = NULL,
  y_range = NULL,
  mtbs = "verified",
  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: `r lifecycle::badge("deprecated")` `show_grouping = \"yes\" or \"no\"` is no longer supported. Use the mtbs parameter instead which allows choosing a specific model, i.e. also the common intercept / common slope case model which was the default model when show_grouping was "no".
response_vbl_unit: A character string that specifies the unit associated with the response variable. The default is NULL.
x_range: A numeric vector of the form c(min, max) that specifies 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.
y_range: A numeric vector of the form c(min, max) that specifies the range of the response variable to be plotted. The default is NULL and the \(y\) range is calculated automatically on the basis of the time course of the response.
mtbs: A character string that specifies the “model to be shown”, i.e. either verified, which is the default, or one of cics, dics, dids or dids.pmse. The verified model is the model that was identified through the poolability check. It is thus also one of the possible optional models. The dids model represents the case where a separate model is fitted to the data of each individual batch while the dids.pmse model is the interaction model which includes the \(batch\) variable as main effect and in the interaction term with the \(time\) variable (\(batch \times time\)), i.e. a model where the mean square error is pooled across batches.
plot_option: A character string of either "full" or "lean" that specifies if additional 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", that specifies 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

# 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), sf_option = "loose")

# 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, response_vbl_unit = "%", x_range = NULL, y_range = c(93, 105),
  mtbs = "verified", plot_option = "full", ci_app = "line")
if (FALSE) {
  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))
  }
}

# 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), sf_option = "loose")

gg2 <- plot_expirest_osle(
  model = res2, response_vbl_unit = "%", x_range = c(0, 43),
  y_range = c(83, 107), mtbs = "verified", plot_option = "full",
  ci_app = "ribbon")
if (FALSE) {
  gg2
}

# In case of different intercept / different slope models, individually fit
# linear models are shown by default, i.e. with the 'mtbs' parameter set
# as "verified". To get the different intercept / different slope model
# displayed where the mean square error is pooled across batches, i.e. the
# dids.pmse model, the 'mtbs' parameter has to be set accordingly.

gg3 <- plot_expirest_osle(
  model = res2, response_vbl_unit = "%", x_range = c(0, 43),
  y_range = c(83, 107), mtbs = "dids.pmse", plot_option = "full",
  ci_app = "ribbon")
if (FALSE) {
  gg3
}