spikecomp {Hmisc}

spikecomp

Description

Compute Elements of a Spike Histogram

Usage

spikecomp(
  x,
  method = c("tryactual", "simple", "grid"),
  lumptails = 0.01,
  normalize = TRUE,
  y,
  trans = NULL,
  tresult = c("list", "segments", "roundeddata")
)

Arguments

x

a numeric variable

method

specifies the binning and output method. The default is 'tryactual' and is intended to be used for spike histograms plotted in a way that allows for random x-coordinates and data gaps. No binning is done if there are less than 100 distinct values and the closest distinct x values are distinguishable (not with 1/500th of the data range of each other). Binning uses pretty. When trans is specified to transform x to reduce long tails due to outliers, pretty rounding is not done, and lumptails is ignored. method='grid' is intended for sparkline spike histograms drawn with bar charts, where plotting is done in a way that x-coordinates must be equally spaced. For this method, extensive binning information is returned. For either 'tryactual' or 'grid', the default if trans is omitted is to put all values beyond the 0.01 or 0.99 quantiles into a single bin so that outliers will not create long nearly empty tails. When y is specified, method is ignored.

lumptails

the quantile to use for lumping values into a single left and a single right bin for two of the methods. When outer quantiles using lumptails equal outer quantiles using 2*lumptails, lumptails is ignored as this indicates a large number of ties in the tails of the distribution.

normalize

set to FALSE to not divide frequencies by maximum frequency

y

a vector of frequencies corresponding to x if you want the (x, y) pairs to be taken as a possibly irregular-spaced frequency tabulation for which you want to convert to a regularly-spaced tabulation like count='tabulate' produces. If there is a constant gap between x values, the original pairs are return, with possible removal of NAs.

trans

a list with three elements: the name of a transformation to make on x, the transformation function, and the inverse transformation function. The latter is used for method='grid'. When trans is given lumptails is ignored. trans applies only to method='tryactual'.

tresult

applies only to method='tryactual'. The default 'list' returns a list with elements x, y, and roundedTo. method='segments' returns a list suitable for drawing line segments, with elements ⁠x, y1, y2⁠. method='roundeddata' returns a list with elements x (non-tabulated rounded data vector after excluding NAs) and vector roundedTo.

Details

Derives the line segment coordinates need to draw a spike histogram. This is useful for adding elements to ggplot2 plots and for the describe function to construct spike histograms. Date/time variables are handled by doing calculations on the underlying numeric scale then converting back to the original class. For them the left endpoint of the first bin is taken as the minimal data value instead of rounded using pretty().

Value

when y is specified, a list with elements x and y. When method='tryactual' the returned value depends on tresult. For method='grid', a list with elements x and y and scalar element roundedTo containing the typical bin width. Here x is a character string.

Author(s)

Frank Harrell

Examples

spikecomp(1:1000)
spikecomp(1:1000, method='grid')
## Not run: 
On a data.table d use ggplot2 to make spike histograms by country and sex groups
s <- d[, spikecomp(x, tresult='segments'), by=.(country, sex)]
ggplot(s) + geom_segment(aes(x=x, y=y1, xend=x, yend=y2, alpha=I(0.3))) +
   scale_y_continuous(breaks=NULL, labels=NULL) + ylab('') +
   facet_grid(country ~ sex)

## End(Not run)