# SCM Repository

[latticeextra] Annotation of /pkg/man/panel.xblocks.Rd
 [latticeextra] / pkg / man / panel.xblocks.Rd

# Annotation of /pkg/man/panel.xblocks.Rd

 1 : felix 148 \name{panel.xblocks} 2 : \alias{panel.xblocks} 3 : \alias{panel.xblocks.default} 4 : \alias{panel.xblocks.ts} 5 : \alias{panel.xblocks.zoo} 6 : \title{ 7 : Plot contiguous blocks along x axis. 8 : } 9 : \description{ 10 : Plot contiguous blocks along x axis. A typical use would be to 11 : highlight events or periods of missing data. 12 : } 13 : \usage{ 14 : panel.xblocks(x, ...) 15 : 16 : \method{panel.xblocks}{default}(x, y, ..., col = NULL, border = NA, 17 : height = unit(1, "npc"), 18 : block.y = unit(0, "npc"), vjust = 0, 19 : name = "xblocks", gaps = FALSE, 20 : last.step = median(diff(tail(x)))) 21 : 22 : \method{panel.xblocks}{ts}(x, y = x, ...) 23 : \method{panel.xblocks}{zoo}(x, y = x, ...) 24 : } 25 : \arguments{ 26 : \item{x, y}{ 27 : In the default method, \code{x} gives the ordinates along the x axis and 28 : must be in increasing order. \code{y} gives the color values to plot as 29 : contiguous blocks. If \code{y} is numeric, data coverage is plotted, 30 : by converting it into a logical (\code{!is.na(y)}). Finally, if 31 : \code{y} is a function, it is applied to \code{x} (\code{time(x)} in 32 : the time series methods). 33 : 34 : If \code{y} has character (or factor) values, these are interpreted 35 : as colors -- and should therefore be color names or hex 36 : codes. Missing values in \code{y} are not plotted. The default 37 : color is taken from the current theme: 38 : \code{trellis.par.get("plot.line")\$col}. If \code{col} is given, 39 : this over-rides the block colors. 40 : 41 : The \code{ts} and \code{zoo} methods plot the \code{y} values 42 : against the time index \code{time(x)}. 43 : } 44 : \item{\dots}{ 45 : In the default method, further arguments are graphical parameters 46 : passed on to \code{\link{gpar}}. 47 : } 48 : \item{col}{ 49 : if \code{col} is specified, it determines the colors of the blocks 50 : defined by \code{y}. If multiple colors are specified they will be 51 : repeated to cover the total number of blocks. 52 : } 53 : \item{border}{ 54 : border color. 55 : } 56 : \item{height}{ 57 : height of blocks, defaulting to the full panel height. Numeric 58 : values are interpreted as native units. 59 : } 60 : \item{block.y}{ 61 : y axis position of the blocks. Numeric values are interpreted as 62 : native units. 63 : } 64 : \item{vjust}{ 65 : vertical justification of the blocks relative to \code{block.y}. See 66 : \code{\link{grid.rect}}. 67 : } 68 : \item{name}{ 69 : a name for the grob (\pkg{grid} object). 70 : } 71 : \item{gaps}{ 72 : Deprecated. 73 : Use \code{panel.xblocks(time(z), is.na(z))} instead. 74 : } 75 : \item{last.step}{ 76 : width (in native units) of the final block. Defaults to the median of 77 : the last 5 time steps (assuming steps are regular). 78 : } 79 : } 80 : \details{ 81 : Blocks are drawn forward in "time" from the specified x locations, 82 : up until the following value. Contiguous blocks are calculated using 83 : \code{\link{rle}}. 84 : } 85 : \author{ 86 : Felix Andrews \email{felix@nfrac.org} 87 : } 88 : \seealso{ 89 : \code{\link{xyplot.ts}}, 90 : \code{\link{panel.rect}}, 91 : \code{\link{grid.rect}} 92 : } 93 : \examples{ 94 : ## Example of highlighting peaks in a time series. 95 : set.seed(0) 96 : flow <- ts(filter(rlnorm(200, mean = 1), 0.8, method = "r")) 97 : 98 : ## using an explicit panel function 99 : xyplot(flow, panel = function(x, y, ...) { 100 : panel.xblocks(x, y > mean(y), col = "lightgray") 101 : panel.xyplot(x, y, ...) 102 : }) 103 : ## using layers; this is the ts method because > keeps it as ts. 104 : xyplot(flow) + 105 : layer_(panel.xblocks(flow > mean(flow), col = "lightgray")) 106 : 107 : ## Example of alternating colors, here showing calendar months 108 : flowdates <- as.Date("2000-01-01") + as.numeric(time(flow)) 109 : xyplot(flow ~ flowdates, type = "l") + 110 : layer_(panel.xblocks(x, months, 111 : col = c("lightgray", "#e6e6e6"), border = "darkgray")) 112 : 113 : ## highlight values above and below thresholds. 114 : ## blue, gray, red colors: 115 : deepayan 194 bgr <- hcl(c(0, 0, 260), c = c(100, 0, 100), l = c(90, 90, 90)) 116 : dflow <- cut(flow, c(0,15,30,Inf), labels = bgr) 117 : xyplot(flow) + layer_(panel.xblocks(time(flow), dflow)) 118 : felix 148 119 : ## Example of highlighting gaps (NAs) in time series. 120 : ## set up example data 121 : z <- ts(cbind(A = 0:5, B = c(6:7, NA, NA, 10:11), C = c(NA, 13:17))) 122 : 123 : ## show data coverage only (highlighting gaps) 124 : xyplot(z, panel = panel.xblocks, 125 : scales = list(y = list(draw = FALSE))) 126 : 127 : ## draw gaps in darkgray 128 : xyplot(z, type = c("p","s")) + 129 : layer_(panel.xblocks(x, is.na(y), col = "darkgray")) 130 : 131 : ## Example of overlaying blocks from a different series. 132 : ## Are US presidential approval ratings linked to sunspot activity? 133 : ## Set block height, default justification is along the bottom. 134 : xyplot(presidents) + layer(panel.xblocks(sunspot.year > 50, height = 2)) 135 : } 136 : \keyword{ dplot }