plotClusters: plots cluster averages
In raim/segmenTools: Tools for Functional Genome Exploration

plotClusters

R Documentation

plots cluster averages

Description

plots average time series of clusters as calculated by clusterAverages, including variations around the average as transparent areas, or all individual data. The function is quite flexible and allows to normalize the data and set automatic y-limit selections.

Usage

plotClusters(
  x,
  cls,
  k,
  each = TRUE,
  type = "rng",
  fill = TRUE,
  border = 0,
  time,
  time.at,
  avg = "median",
  q = 0.9,
  norm,
  cls.col,
  cls.srt,
  axes = TRUE,
  xlab,
  xlim,
  ylab,
  ylab.size = TRUE,
  ylab.cex = 1,
  ylim = ifelse(each, "avg", "rng"),
  ylim.scale = 0.1,
  avg.col = "#000000",
  avg.lty = 1,
  avg.lwd = 3,
  avg.cex = 1,
  avg.pch = 1,
  lwd = 0.5,
  use.lty = FALSE,
  alpha = 0.2,
  embed = FALSE,
  plot.legend = FALSE,
  leg.xy = "topleft",
  leg.ids,
  vline = "",
  vl_col = 0,
  vl_lwd = 3,
  vl_lty = 1,
  ref.xy,
  ref.col = "#C0C0C080",
  ref.ylab = "",
  ref.log = FALSE,
  ...
)

Arguments

`x`	either a simple data matrix with time points (x-axis) in columns, or a processed time-series as provided by `processTimeseries`
`cls`	eiter a vector (`length(cls)==nrow(x)`) or a structure of class 'clustering' as returned by segmenTier's `clusterTimeseries`
`k`	integer or string specifiying the clustering (k: cluster numbers) to be used if cls is of class 'clustering'; if missing (default) the ‘selected’ clustering from `cls` is chosen (see `selected`).
`each`	logical value indicating whether to plot all cluster averages on one panel (`FALSE`) or each cluster on a separate panel (`TRUE`)
`type`	string specifying the type of plot: "rng" for plotting only data ranges (see argument `q`) or "all" to plot each individual time-course (as thin lines)
`fill`	fill data ranges with transparent version of cluster color
`border`	line width of border line at data ranges
`time`	optional numeric vector specifiying x-axis time coordinates
`time.at`	argument `at` for the x-axis (`axis(1, at=time.at)`)
`avg`	a function (or the name of a function as a string) for calculating an ‘average’ value for each cluster; default is the `median`
`q`	either numeric (0.5-1, or 0), or a string. If numeric it indicates the fraction of data shown as transparent ranges, e.g. `q=0.9` indicates that 90 ranges, i.e. the 5 borders, and for q=0.5 the ranges correspond to the box limits in a boxplot. If q is a string it must be a function name for calculating variance (eg. "sd", "var"), which will be added and subtracted from the average (argument `avg`) for high and low data cut-offs. Note that this parameter can also influence `ylim`, the limits of the y axis.
`norm`	normalization of the time-series data, must be a function that transforms the data, available via segmenTools are `lg2r`, `ash`, `log_1`, `meanzero` normalizations
`cls.col`	optional named cluster color vector, where names indicate the clusters (as.caracter(cls)); if cls is of class 'clustering' it is taken from there
`cls.srt`	optional cluster sorting, can be used for selection of subsets of clusters; if cls is of class 'clustering' it is taken from there
`axes`	add axes (bottom and left)
`xlab`	x-axis label (auto-selected if missing)
`xlim`	`xlim` parameter for plot
`ylab`	y-axis label (only used if `each==FALSE`)
`ylab.size`	add cluster size to cluster-wise ylab
`ylab.cex`	font size of ylab
`ylim`	either conventional range of the y-axis, or a string specifying whether ylim should be calculated from the average (`ylim="avg"`), for all data (`ylim="all"`), or from the lower/upper ranges (`ylim="rng"`); in the latter case the y-axis depends on argument `q`
`ylim.scale`	if `ylim=="avg"`, the calculated ylim will be extended by this fraction of the total range on both sides
`avg.col`	color for average line; used only if `type="all"`
`avg.lty`	line type for average plots
`avg.lwd`	line width for average plots
`avg.cex`	point size for average plots
`avg.pch`	point symbol for average plots
`lwd`	line width for indidiual time series plots (if `type=="all"`)
`use.lty`	use individual line types (if `type=="all"`); this is only useful for very small clusters and is mainly used in the `plotSingles` wrapper
`alpha`	set alpha value of range or individual time series colors (color opaqueness)
`embed`	logical, if TRUE and argument `each=TRUE` (one plot for each cluster), the automatic is suppressed allowing to embed multiple plots (for each cluster) into external `layout` or `par(mfcol/mfrow)` setups
`plot.legend`	add a legend, useful for very small clusters and mainly used in the `plotSingles` wrapper
`leg.xy`	position of the legend, see `legend`
`leg.ids`	a named vector providing alternative IDs for legends; the names should correspond to the rownames of clusterings in `cls`
`vline`	x coordinates for vertical lines, useful e.g. to mark replicates
`vl_col`	color for vertical line (default to cluster colour)
`vl_lwd`	vertical line width
`vl_lty`	vertical line type
`ref.xy`	reference data (either x or xy coordinates, see `xy.coords`) for reference data to be plotted in the background, e.g. light/dark phases or dissolved oxygen traces
`ref.col`	color for reference data plot
`ref.ylab`	y-axis label (right y-axis) for reference data
`ref.log`	logarithmic axis for reference data
`...`	further arguments to the basic setup call to `plot` ## TODO: clean up mess between plot.clustering, plot.clusteraverages and this ## plot.clusteraverages should become a function of plot.clustering, ## and clusterAverages can be a private function! ## make function ‘timeseriesPlot’ or ‘clusterPlot’, that takes ## either tset/cset or matrix/vector