The Xpose 4 generic functions for continuous y-variables.

This function is a wrapper for the lattice xyplot function.

Usage

xpose.plot.default(
  x,
  y,
  object,
  inclZeroWRES = FALSE,
  onlyfirst = FALSE,
  samp = NULL,
  panel = xpose.panel.default,
  groups = object@Prefs@Xvardef$id,
  ids = object@Prefs@Graph.prefs$ids,
  logy = FALSE,
  logx = FALSE,
  yscale.components = "default",
  xscale.components = "default",
  aspect = object@Prefs@Graph.prefs$aspect,
  funx = NULL,
  funy = NULL,
  iplot = NULL,
  PI = NULL,
  by = object@Prefs@Graph.prefs$condvar,
  force.by.factor = FALSE,
  ordby = object@Prefs@Graph.prefs$ordby,
  byordfun = object@Prefs@Graph.prefs$byordfun,
  shingnum = object@Prefs@Graph.prefs$shingnum,
  shingol = object@Prefs@Graph.prefs$shingol,
  by.interval = NULL,
  strip = function(...) {
     strip.default(..., strip.names = c(TRUE, TRUE))
 },
  use.xpose.factor.strip.names = TRUE,
  subset = xsubset(object),
  autocorr = FALSE,
  main = xpose.create.title(x, y, object, subset, funx, funy, ...),
  xlb = xpose.create.label(x, object, funx, logx, autocorr.x = autocorr, ...),
  ylb = xpose.create.label(y, object, funy, logy, autocorr.y = autocorr, ...),
  scales = list(),
  suline = object@Prefs@Graph.prefs$suline,
  bwhoriz = object@Prefs@Graph.prefs$bwhoriz,
  dilution = FALSE,
  dilfrac = object@Prefs@Graph.prefs$dilfrac,
  diltype = object@Prefs@Graph.prefs$diltype,
  dilci = object@Prefs@Graph.prefs$dilci,
  seed = NULL,
  mirror = FALSE,
  max.plots.per.page = 4,
  mirror.aspect = "fill",
  pass.plot.list = FALSE,
  x.cex = NULL,
  y.cex = NULL,
  main.cex = NULL,
  mirror.internal = list(strip.missing = missing(strip)),
  ...
)

Arguments

x: A string or a vector of strings with the name(s) of the x-variable(s).
y: A string or a vector of strings with the name(s) of the y-variable(s).
object: An "xpose.data" object.
inclZeroWRES: A logical value indicating whether rows with WRES=0 should be plotted.
onlyfirst: A logical value indicating whether only the first row per individual should be included in the plot.
samp: An integer between 1 and object@Nsim (seexpose.data-class) specifying which of the simulated data sets to extract from SData.
panel: The name of the panel function to use.
groups: A string with the name of any grouping variable (used as the groups argument to panel.xyplot.
ids: A logical value indicating whether text labels should be used as plotting symbols (the variable used for these symbols indicated by the idlab xpose data variable).
logy: Logical value indicating whether the y-axis should be logarithmic.
logx: Logical value indicating whether the x-axis should be logarithmic.
yscale.components: Used to change the way the axis look if logy is used. Can be a user defined function or link{xpose.yscale.components.log10}. If the axes are not log transformed then yscale.components.default is used.
xscale.components: Used to change the way the axis look if logx is used. Can be a user defined function or link{xpose.xscale.components.log10}. If the axes are not log transformed then xscale.components.default is used.
aspect: The aspect ratio of the display (see xyplot).
funx: String with the name of a function to apply to the x-variable before plotting, e.g. "abs".
funy: String with the name of a function to apply to the y-variable before plotting, e.g. "abs".
iplot: Is this an individual plots matrix? Internal use only.
PI: Either "lines", "area" or "both" specifying whether prediction intervals (as lines, as a shaded area or both) should be computed from the data in SData and added to the display. NULL means no prediction interval.
by: A string or a vector of strings with the name(s) of the conditioning variables.
force.by.factor: Logical value. If TRUE, and by is not NULL, the variable specified by by is taken as categorical.
ordby: A string with the name of a variable to be used to reorder any factor conditioning variables (by). The variable is used in a call to the reorder.factor function.
byordfun: The name of the function to be used when reordering a factor conditioning variable (see argument ordby)
shingnum: The number of shingles ("parts") a continuous conditioning variable should be divided into.
shingol: The amount of overlap between adjacent shingles (see argument shingnum)
by.interval: The intervals to use for conditioning on a continuous variable with by.
strip: The name of the function to be used as the strip argument to the xyplot. An easy way to change the strip appearance is to use strip.custom. For example, if you want to change the text in the strips you can use strip=strip.custom(factor.levels=c("Hi","There")) if the by variable is a factor and strip=strip.custom(var.name=c("New Name")) if the by variable is continuous.
use.xpose.factor.strip.names: Use factor names in strips of conditioning plots..
subset: A string giving the subset expression to be applied to the data before plotting. See xsubset.
autocorr: Is this an autocorrelation plot? Values can be TRUE/FALSE.
main: A string giving the plot title or NULL if none.
xlb: A string giving the label for the x-axis. NULL if none.
ylb: A string giving the label for the y-axis. NULL if none.
scales: A list to be used for the scales argument in xyplot.
suline: A string giving the variable to be used to construct a smooth to superpose on the display. NULL if none. This argument is used if you want to add a superpose line of a variable not present in the y list of variables.
bwhoriz: A logical value indicating if box and whiskers bars should be plotted horizontally or not. Used when the x-variable(s) is categorical.
dilution: Logical value indicating whether data dilution should be used.
dilfrac: Dilution fraction indicating the expected fraction of individuals to display in the plots. The exact meaning depends on the type of dilution (see below).
diltype: Indicating what type of dilution to apply. NULL means random dilution without stratification. A nonNULL value means stratified dilution.
dilci: A number between 0 and 1 giving the range eligible for dilution in a stratified dilution (see below).
seed: Seed number used for random dilution. NULL means no seed.
mirror: Should we create mirror plots from simulation data? Value can be FALSE, TRUE or 1 for one mirror plot, or 3 for three mirror plots.
max.plots.per.page: The maximum number of plots per page that can be created with the mirror plots.
mirror.aspect: The aspect ratio of the plots used for mirror functionality.
pass.plot.list: Should we pass the list of plots created with mirror or should we print them directly. Values can be TRUE/FALSE.
x.cex: The size of the x-axis label.
y.cex: The size of the y-axis label.
main.cex: The size of the title.
mirror.internal: an internal mirror argument used in create.mirror. Checks if the strip argument from xyplot has been used.
...: Other arguments passed to xpose.panel.default.

Value

Returns a xyplot graph object.

Details

y must be numeric (continuous) while x can be either numeric of factor. If x is numeric then a regular xy-plot is drawn. If x is a factor, on the other hand, a box and whiskers plot is constructed.

x and y can be either single valued strings or vector of strings. x and y can not both be vectors in the same call to the function.

If ids is TRUE, text labels are added to the plotting symbols. The labels are taken from the idlab xpose data variable. The way the text labels are plotted is governed by the idsmode argument (passed down to the panel function). idsmode=NULL (the default) means that only extreme data points are labelled while a non-NULL value adds labels to all data points (the default in Xpose 3). xpose.panel.default identifies extreme data points by fitting a loess smooth (y~x) and looking at the residuals from that fit. Points that are associated with the highest/lowest residuals are labelled. "High" and "low" are judged by the panel function parameter idsext, which gives the fraction of the total number of data points that are to be judged extreme in the "up" and "down" direction. The default value for idsext is 0.05 (see xpose.prefs-class). There is also a possibility to label only the high or low extreme points. This is done through the idsdir argument to xpose.panel.default. A value of "both" (the default) means that both high and low extreme points are labelled while "up" and "down" labels the high and low extreme points respectively.

Data dilution is useful is situations when there is an excessive amount of data. xpose.plot.default can dilute data in two different ways. The first is a completely random dilution in which all individuals are eligible for exclusion from the plot. In this case the argument dilfrac determines the fraction of individuals that are excluded from the plot. The second type of dilution uses stratification to make sure that none of the extreme individuals are omitted from the plot. Extreme individuals are identified in a similar manner as extreme data points are identified for text labelling. A smooth is fitted to the data and the extreme residuals from that fit is used to inform about extremeness. What is judged as extreme is determined by the argument dilci, which defaults to 0.95 (Note that the meaning of this is the opposite to idsext). dilci give the confidence level of the interval around the fitted curve outside of which points are deemed to be extreme. Extreme individuals are those that have at least one point in the "extremeness" interval. Individuals that do not have any extreme points are eligible for dilution and dilfrac give the number of these that should be omitted from the graph. This means that dilfrac should usually be grater for stratified dilution than in completely random dilution. Any smooths added to a diluted plot is based on undiluted data.

More graphical parameters may be passed to xpose.panel.default.

Author

E. Niclas Jonsson, Mats Karlsson, Andrew Hooker & Justin Wilkins

Examples


if (FALSE) {
## xpdb5 is an Xpose data object
## We expect to find the required NONMEM run and table files for run
## 5 in the current working directory
xpdb5 <- xpose.data(5)

## A spaghetti plot of DV vs TIME
xpose.plot.default("TIME", "DV", xpdb5) 

## A conditioning plot
xpose.plot.default("TIME", "DV", xpdb5, by = "SEX")
 
## Multiple x-variables
xpose.plot.default(c("WT", "SEX"), "CL", xpdb5)

## Multiple y-variables
xpose.plot.default("WT", c("CL", "V"), xpdb5)
xpose.plot.default("WT", c("CL", "V"), xpdb5, by=c("SEX", "HCTZ"))

## determining the interval for the conditioning variable
wt.ints <- matrix(c(50,60,60,70,70,80,80,90,90,100,100,150),nrow=6,ncol=2,byrow=T)
xpose.plot.default("TIME","DV",xpdb5,by="WT", by.interval=wt.ints)
}