xy_plot {opm}R Documentation

X-Y plot

Description

Customised plotting of a single PM plate or multiple plates, using xyplot from the lattice package.

Usage

  ## S4 method for signature 'MOPMX'
xy_plot(x, ...) 
  ## S4 method for signature 'OPM'
xy_plot(x, col = "midnightblue", lwd = 1,
    neg.ctrl = "A01", base.col = "grey10", base.lwd = lwd,
    main = list(), xlab = "Time [h]", ylab = "Value [OmniLog units]",
    theor.max = TRUE, draw.grid = TRUE,
    strip.fmt = list(), striptext.fmt = list(), rcr = 0.75,
    ...) 
  ## S4 method for signature 'OPMS'
xy_plot(x, col = opm_opt("colors"), lwd = 1,
    neg.ctrl = "A01", base.col = "black", base.lwd = lwd,
    main = list(), xlab = "Time [h]", ylab = "Value [OmniLog units]",
    theor.max = TRUE, draw.grid = TRUE, space = "top",
    strip.fmt = list(), striptext.fmt = list(),
    legend.fmt = list(), legend.sep = " ", draw.legend = TRUE, rcr = 0.75,
    ...) 
  ## S4 method for signature 'data.frame'
xy_plot(x, f, groups,
    col = opm_opt("colors"), lwd = 1, neg.ctrl = NULL, base.col = "black",
    base.lwd = lwd, main = groups, xlab = elem(f, 3L:2L), ylab = elem(f, 2L),
    draw.grid = TRUE, space = "top", strip.fmt = list(), striptext.fmt = list(),
    legend.fmt = list(), legend.sep = " ", draw.legend = TRUE, rcr = 0.75,
    ...)

Arguments

x

OPM, OPMS or MOPMX object.

col

For the OPM method, just a character scalar (colour name) determining the line colour.

For the OPMS method, either a character vector with colour codes or one of the arguments of select_colors (for picking one of the predefined colour sets). When col is the empty string, it is automatically replaced by the number of plate grouping levels. See select_colors for details.

It is an error if fewer colours are chosen than the number of plate grouping levels (see the ... argument below). For user-chosen colour sets, keep in mind that the sets are not checked for duplicates.

lwd

Numeric scalar determining the line width.

neg.ctrl

Determine the height of a horizontal baseline drawn in each panel.

  • If NULL or FALSE, no baseline will be drawn.

  • If TRUE, the baseline's height is the value of minmax.

  • If a character scalar, neg.ctrl is interpreted as the name of the wells regarded as negative control, and the baseline's height becomes the value of minmax applied to these wells only.

  • Set neg.ctrl to a numeric value for assigning the height directly (at your own risk).

base.col

Character scalar. Baseline colour (ignored if no baseline is drawn).

base.lwd

Numeric scalar determining the width of the baseline (ignored if no baseline is drawn).

main

The settings controlling the construction of the main title. If a list, a named list with the following entries (if missing, they are replaced by the respective defaults):

predef

Character scalar or expression. Predefined title. If set, the other entries are ignored.

use

Logical scalar. If FALSE, returns NULL.

...

Other arguments are passed to plate_type.

If settings is not a list but a character scalar or an expression, this is used as the predef entry of the above-mentioned list. If not a list but a logical scalar, it is used as the ‘use’ entry of this list. If not a list but a numeric value, it is used as the ‘max’ entry of this list.

xlab

Character scalar. Title of x-axis. Use NULL to turn it off.

ylab

Character scalar. Title of y-axis. Use NULL to turn it off.

theor.max

Logical scalar. Use the theoretical maximum as maximum of the y-axis? If FALSE, use the empirical maximum with a small offset. Can alternatively be a scalar of mode double, which is then directly used to set the upper limit of the y-axis.

draw.grid

Logical scalar. Insert background grid?

space

Character scalar indicating the position of the legend; either ‘top’, ‘bottom’, ‘left’ or ‘right’. Might be overwritten by legend.fmt.

strip.fmt

List controlling the format of the description strip above each panel. For instance, the background colour is set using the bg key. For further details, see strip.custom from the lattice package. Note that the content of these descriptions is determined by arguments passed from xy_plot to wells; see there for details.

striptext.fmt

List controlling the textual description at the top of each panel. For instance, the relative text size is set using the cex key, the colour by ‘col’, the font by ‘font’ and the number of lines by ‘lines’. The latter might be of interest in conjunction with the paren.sep argument of wells. See the argument par.strip.text of xyplot from the lattice package for details.

legend.fmt

List controlling where and how to draw the legend. The content of the legend (mainly a description of the assignment of the colours to the curves) is determined automatically. See argument ‘key’ of xyplot from the lattice package for details.

legend.sep

Character scalar. Relevant only if more than one columns of metadata have been selected; will then be used as separator to join their names in the legend.

draw.legend

Logical scalar. If FALSE, no legend is drawn, and the two aforementioned arguments are ignored.

rcr

Numeric scalar (row-column-ratio) interpreted as number of rows per number of columns. Determines the arrangement of the subplots.

...

Arguments that are passed to flatten. For the OPMS method, include is particularly important: the selected metadata are joined into a single factor, and the assignment of plates to this factor's levels determines the curve colour for each plate. That is, each combination of metadata entries as chosen using include yields one colour. If no metadata are selected (the default), each plate gets a colour of its own. Also note that arguments passed via flatten to wells can be given here which determine the content of the panel description.

f

Formula (for the data-frame method).

groups

Character vector (for the data-frame method).

Details

The optimal number of rows and columns is estimated from the number of selected wells. An optimal font size of the panel headers is also chosen automatically, but can also be adapted by the user, much like most aspects of the resulting graphics output.

In the case of the OPMS method, if metadata are selected, curve colours are determined according to the combinations of these metadata entries, otherwise each plate gets its own colour.

The data-frame method is not intended for phenotype microarray data. It is currently undocumented and potentially subject to frequent changes or even removal. Users interested in the method should contact the authors.

Value

An object of class ‘trellis’ or list of such objects. See xyplot from the lattice package for details.

References

Sarkar, D. 2008 Lattice: Multivariate Data Visualization with R. New York: Springer, 265 p.

Vaas, L. A. I., Sikorski, J., Michael, V., Goeker, M., Klenk H.-P. 2012 Visualization and curve parameter estimation strategies for efficient exploration of Phenotype Microarray kinetics. PLoS ONE 7, e34846.

See Also

lattice::xyplot

Other plotting-functions: ci_plot, heat_map, level_plot, parallel_plot, parallelplot, radial_plot, summary

Examples

# OPM method
## Not run: 
##D xy_plot(vaas_1) # note the default main title built from the plate type
## End(Not run)

x <- vaas_1[, 11:22]
# Yields a warning message: we have deleted the default negative control.
xy_plot(x)

## Warning: cannot get negative control from selected position (deleted?);
## error was: subscript out of bounds

plot of chunk unnamed-chunk-1 

# Turn the baseline off => no warning:
xy_plot(x, neg.ctrl = NULL)

plot of chunk unnamed-chunk-1 

# Or guess a baseline:
xy_plot(x, neg.ctrl = 100)

plot of chunk unnamed-chunk-1 

# Some like it ugly:
xy_plot(x, neg.ctrl = 100, col = "pink", base.col = "yellow", main = "Ugly")

plot of chunk unnamed-chunk-1 

# OPMS method
## Not run: 
##D # Colour by species and strain; note default main title
##D xy_plot(vaas_4, include = c("Species", "Strain"))
##D # Use the largest of the negative-control maxima as baseline
##D xy_plot(vaas_4, include = c("Species", "Strain"),
##D   neg.ctrl = max(vaas_4, "A01"))
## End(Not run)
[Package opm version 1.3.63 Index]