Skip to contents

Plot Pmetrics Simulation Objects

Source: R/plotPMsim.R
plot.PM_sim.Rd

[Stable]

Plots PM_sim objects with the option to perform a visual and numerical predictive check

Usage

# S3 method for PM_sim
plot(
  x,
  mult = 1,
  ci = 0.95,
  binSize = 0,
  outeq = 1,
  line = TRUE,
  marker = FALSE,
  obs,
  quiet = FALSE,
  legend = FALSE,
  log = TRUE,
  grid = FALSE,
  xlab,
  ylab,
  title,
  xlim,
  ylim,
  simnum,
  ...
)

Arguments

x

The name of an PM_sim data object generated by PM_sim

mult

Multiplication factor for y axis, e.g. to convert mg/L to ng/mL

ci

Width of confidence interval bands around simulated quantiles, from 0 to 1. If 0, or nsim<100, will not plot. Default is 0.95, i.e. 95th percentile with tails of 2.5 percent above and below excluded.

binSize

Width of binning interval for simulated concentrations, in time units, e.g. hours. A binSize of 0.5 will pull all simulated concentrations +/- 0.5 hours into the same time. This is useful for plotting PMsim objects made during make_valid. The default is 0, i.e. no binning. If an obs object is provided, it will be binned similarly.

outeq

Which output equation to plot. Default is 1.

line

Controls the appearance of lines. It can be specified in several ways.

  • Default is TRUE which results in simulated profiles summarized as quantiles, with default values of 0.05, 0.25, 0.5, 0.75, and 0.95. The default format will be applied, which is solid black lines of width 1. Numerical predictive checking will be calculated if observations are also included (see obs below).

  • FALSE results in no lines plotted and the plot will be blank.

  • NA Quantile summaries will be suppressed, but lines joining simulated outputs will be plotted in default format as above. In other words, all profiles will be plotted, not just the quantiles. Numerical predictive checking will be suppressed.

  • List of quantiles and formats to plot with the following elements:

    • probs Vector of quantiles to include. If missing, will be set to defaults above, i.e., c(0.05, 0.25, 0.5, 0.75, and 0.95) Example: line = list(probs = c(0.25, 0.5, 0.75)).

    • color Vector of color names whose order corresponds to probs. If shorter than probs, will be recycled. Default is "dodgerblue". Examples: line = list(color = "red") or line = list(color = c("red", "blue")).

    • width Vector of widths in pixels, as for color. Default is 1. Example: line = list(width = 2).

    • dash Vector of dash types, as for color. Default is "solid". See plotly::schema(), traces > scatter > attributes > line > dash > values. Example: line = list(dash = "dashdot").

marker

A vector of subject IDs to include in the plot, e.g. c(1:3,5,15) Formatting will only be applied to observations if included via the obs argument.

obs

The name of a PM_result data object or the PM_op field in the PM_result object, all generated by PM_load. For example, if run1 <- PM_load(1) and sim1 is a PM_sim object, then sim1$plot(obs = run1) or sim1$plot(obs = run1$op). If specified, the observations will be overlaid upon the simulation plot enabling a visual predictive check. In this case, a list object will be returned with two items: $npc containing the quantiles and probability that the observations are below each quantile (binomial test); and $simsum, the times of each observation and the value of the simulated quantile with upper and lower confidence intervals at that time. Additionally, the number of observations beyond the 5th and 95th percentiles will be reported and the binomial test P-value if this number is different than the expected 10% value.

quiet

Suppress plot if TRUE.

legend

Controls display of legend. This argument maps to the plotly layout showlegend and legend arguments. It is either a boolean operator (most common) or a list of parameters to be supplied to plotly. See plotly::schema() > layout > layoutAttributes > legend and showlegend for more details on the available options for formatting. If legend is supplied as a list, the plotly layout > layoutAttributes > showlegend value will be set to TRUE automatically.

Examples:

  • legend = T

  • legend = list(orientation = "h", font = list(color = "blue"))

Default is FALSE

log

Boolean operator to plot the y axis in log base 10. This argument maps to the the yaxis type value in the layout object in plotly. Use the plotly plotly::schema() command in the console and navigate to layout > layoutAttributes > yaxis > type.

Example: log = T Default is TRUE.

grid

Controls grid display. This argument maps to the xaxis and yaxis layout objects in plotly. Use the plotly plotly::schema() command in the console and navigate to layout > layoutAttributes > xaxis or yaxis > gridcolor or gridwidth. It is a Boolean operator. If FALSE, no grid is plotted. If TRUE, the default color grey and width 1 will be plotted at major tick marks. If a list, color and width can be customized.

Examples:

  • grid = F

  • grid = list(gridcolor = "black", gridwidth = 2)

Default is FALSE

xlab

Value for x axis label. This argument maps to the the xaxis title element of the layout object in plotly. It can simply be a character vector of length 1 that specifies the name of the axis, or it can be a list for greater control. Use the plotly plotly::schema() command in the console and navigate to layout > layoutAttributes > xaxis > title to see the ways to customize this axis label. In addition to the plotly attributes, a custom Pmetrics attribute bold may be included as a list element, either on its own or within the font list. The default for bold is TRUE.

Examples:

  • xlab = "Time (h)"

  • xlab = list(text = "Time", bold = F, font = list(color = "red", family = "Arial", size = 10))

  • xlab = list(text = "Time", font = list(bold = T))

Default is "Time".

ylab

Value for y axis label. This argument maps to the the yaxis title element of the layout object in plotly. See xlab for details. If xlab is specified as a list with formatting, and ylab is simply a character label, then the formatting for the xlab will be applied to the ylab. To format ylab independently, specify a formatting list as for xlab.

Default is "Output".

title

Plot title. This argument maps to the the title layout object in plotly. It can simply be a character vector of length 1 that specifies the name of the plot title, or it can be a list for greater control. Use the plotly plotly::schema() command in the console and navigate to layout > layoutAttributes > title to see other ways to customize the title using lists as additional arguments. In addition to the plotly attributes, a custom Pmetrics attribute bold may be included as a list element. The default for bold is TRUE.

Examples:

  • title = "Observed vs. Predicted"

  • title = list(text = "Raw Data", font = list(color = "red", family = "Arial", size = 10, bold = T))

Default is to have no title.

xlim

Limits of the x axis as a vector. This argument maps to the the xaxis range in the layout object in plotly. Use the plotly plotly::schema() command in the console and navigate to layout > layoutAttributes > xaxis > range.

Example: xlim = c(0,1)

ylim

Limits of the y axis as a vector. This argument maps to the the yaxis range in the layout object in plotly. Use the plotly plotly::schema() command in the console and navigate to layout > layoutAttributes > yaxis > range.

Example: ylim = c(0,100)

simnum

Choose which object to plot in a PM_simlist, i.e., a list of PM_sim objects created when more than one subject is included in a simultation data template and combine = F (the default) when parsing the results of a simulation.

...

Other attributes which can be passed to the layout > xaxis/yaxis in a plotly plot to further control formatting. Note that log, xlab, ylab, xlim, and ylim are all controlled by the layout object, but are provided throughout Pmetrics plotly function arguments as shortcuts that map to layout elements. Therefore, the dots argument should be used to specify other aspects of the x axis, y axis, or both. See plotly::schema() layout > layoutAttributes > xaxis/yaxis for options. To add to single axis, name it as a list. If attributes are specified without an enclosing xaxis or yaxis list, they will be applied to both axes.

Examples:

  • NPex$data$plot(xaxis = list(tickcolor = "black", tickfont = list(family = "Arial", size = 14, color = "black"))) #applies to x axis only

  • NPex$data$plot(linecolor = "red", ticks = "inside") #applies to both axes

.

Value

Plots the simulation object. If obs is included, a list will be returned with the folowing items:

  • npc A dataframe with three columns: quantile, prop_less, pval. ** quantile are those specified by the probs argument to the plot call ** prop_less are the proportion of simulated observations at all times less than the quantile ** pval is the P-value of the difference in the prop.less and quantile by the beta-binomial test.

  • simsum A dataframe with the quantile concentration at each simulated time, with lower and upper confidence intervals

  • obs A data frame similar to an PMop object made by makeOP at the end of a run with the addition of the quantile for each observation

Details

Simulated observations are plotted as quantiles on the y-axis vs. time on the x.axis. If measured observations are included, a visual and numerical predictive check will be performed. The default plot is to omit markers, but if the marker arugment is set to TRUE, the resulting marker will have the following plotly properties: list(symbol = "circle-open", color = "black", size = 8). By default a grid is omitted. The legend is also omitted by default, but if included, clicking on a quantile item in the legend will hide it in the plot, and double clicking will hide all other quantiles.

See also

PM_sim, plot_ly, schema

Other PMplots: plot.MMopt(), plot.PM_cov(), plot.PM_cycle(), plot.PM_data(), plot.PM_final(), plot.PM_model(), plot.PM_op(), plot.PM_pta(), plot.PM_valid()

Author

Michael Neely

Examples

library(PmetricsData)
simEx$plot()
simEx$plot(log = FALSE, line = list(color = "orange"))