msPlot: General Plotting Utility
In zeehio/msProcess: Protein Mass Spectra Processing

Description Usage Arguments Value See Also Examples

This function facilitates a wide array of customized plots, enabling the user to easily combine matlines, matpoints, lines, points, image, abline, and text elements. An advantage of this technique is that the plot boundaries defined by xlim and ylim are automatically and correctly set using all sources of relevant input data to avoid "plot out of bounds" warnings. A second advantage is with the matlines and matpoints plots in that the optional offset function can be used to visually separate each series (column) of the supplied data matrix in the display, creating a waterfall-like plot. There are restrictions, however, in that the number of columns of the matlines and matpoints matrices must be the same if supplied. Also, currently a mix of matlines-matpoints with lines-points is not supported.

msPlot(matlines.=NULL, matpoints.=NULL, lines.=NULL, points.=NULL,
    image.=NULL, abline.=NULL, text.=NULL, offset=NULL, recenter=FALSE,
    offset.fun=function(x){3 * stdev(x, na.rm=TRUE)},
    xlab="", ylab="", yref=TRUE, main="", add=FALSE, ...)

`...`	additional arguments for `plot()`.
`abline.`	a list of named objects. This list must contain either of the objects `h` or `v`, containing the vector of coordinates at which to plot at the specifed ablines. Default: `NULL` (no ablines).
`add`	a logical value. If `TRUE`, the plot is added using the current `par()` layout. Otherwise a new plot is produced. Default: `FALSE`.
`image.`	a list of named objects. At the very least, the objects `x`, `y`, and `z` must exist, containing the x and y vectors and z matrix, respectively. Default: `NULL` (no image).
`lines.`	a list of named objects. At the very least, the objects `x` and `y` must exist, containing the x and y matrices, respectively. Default: `NULL` (no lines).
`main`	a character string representing the title label. Default: `""` (no label).
`matlines.`	a list of named objects. At the very least, the objects `x` and `y` must exist, containing the x and y matrices, respectively. Default: `NULL` (no matlines).
`matpoints.`	a list of named objects. At the very least, the objects `x` and `y` must exist, containing the x and y matrices, respectively. Default: `NULL` (no matpoints).
`offset`	a numeric scalar representing the vertical offset to apply between each line in `matlines` and each point in `matpoints`. If `NULL`, the offset is automatically calculated. Default: `NULL` (the offset between plots is set to one standard deviation calculated over the entire set of `matlines`-`matpoints` y data).
`offset.fun`	the function to use in calculating the `offset` if not supplied. This function should have a single input argument which operates over a vector assumed to contain a vectorized collection of all `matlines` and `matpoints` `y` matrices. Default: `function(x){3 * stdev(x)}`.
`points.`	a list of named objects. At the very least, the objects `x` and `y` must exist, containing the x and y matrices, respectively. Default: `NULL` (no points).
`recenter`	a logical value specifying whether or not to recenter the plot. Default: `FALSE`.
`text.`	a list of named objects. At the very least, the objects `x` and `y` must exist, containing the x and y coordinates, respectively, used to place the text. Default: `NULL` (no text).
`xlab`	a character string representing the x-axis label. Default: `""` (no label).
`ylab`	a character string representing the y-axis label. Default: `""` (no label).
`yref`	a logical value. If `TRUE`, a line connecting each y-offset value on the ordinate to the starting point of the corresponding series is drawn for `matlines` and `lines` plots. Default: `TRUE`.

the offsets applied to each column of existing matlines-matpoints y data. This vector is returned invisibly.

matlines, matpoints, lines, points, image, abline, text, par.

if (!exists("qcset")) data("qcset", package="msProcess")

## define range variables 
iz  <- seq(7500)
pts <- c(1500,2500,4500)

## plot matrix style objects 
offsets <- msPlot(
    matlines=list(x=qcset$mz[iz], y=qcset$intensity[iz,1:4],
       lty = 1),
    matpoints=list(x=qcset$mz[pts], y=qcset$intensity[pts,1:4],
       pch=1,cex=2),
    text=list(x=c(3,7)*1000, y=c(15,18)*1000,
       labels=c("cow","moon"), cex=2, adj=1, col=1:2),
    abline=list(v=qcset$mz[pts], h=10000),
    xlab="X Label", ylab="Y Label", main="Title",
    yref=TRUE)

## plot non-matrix style objects 
x <- y <- seq(-4*pi, 4*pi, len=27)
r <- sqrt(outer(x^2, y^2, "+"))
z <- cos(r^2)*exp(-r/6)

msPlot(
    lines=list(x=-60:-55, y=40:45, lwd=5, col=4),
    points=list(x=rnorm(30)-65, y=sin(1:30)+35, col=3, pch=2, cex=2),
    text=list(x=-65,y=39.5,"Sample text", cex=4, col=2),
    image=list(x=x/5-70, y=y/5+45, z=z),
    yref=FALSE)

## multiple matlines in a single call 
x <- matrix(seq(0,10,by=0.1))
y <- sin(x %*% t(1:4))
msPlot(matlines=list(
    list(x=x, y=y, lty=1, lwd=1),
    list(x=x, y=y + 0.2, lty=1, lwd=2),
    list(x=x, y=y - 0.2, lty=1, lwd=4)),
    yref=TRUE)