maghist: Magically pretty histograms

View source: R/maghist.R

maghistR Documentation

Magically pretty histograms


A fairly simple function that produces pretty histograms. The main difference to base hist is that it allows for easy truncation of the data provided via xlim and useful logging options.


maghist(x, breaks = "Sturges", freq = TRUE, include.lowest = TRUE, right = TRUE,
density = NULL, angle = 45, col = NULL, border = NULL, xlim = NULL, ylim = NULL,
plot = TRUE, verbose = TRUE, add = FALSE, log = '', unlog = log, scale = 1,
cumsum = FALSE, p.test = NULL, ...)



A vector of values for which the histogram is desired.


One of:

  • A vector giving the breakpoints between histogram cells,

  • A function to compute the vector of breakpoints,

  • A single number giving the number of cells for the histogram,

  • A character string naming an algorithm to compute the number of cells,

  • A function to compute the number of cells.

In the last three cases the number is a suggestion only; the breakpoints will be set to pretty values. If breaks is a function, the x vector is supplied to it as the only argument.


Logical; if TRUE, the histogram graphic is a representation of frequencies, the counts component of the result; if FALSE, probability densities, component density, are plotted (so that the histogram has a total area of one). Defaults to TRUE if and only if breaks are equidistant (and probability is not specified).


Logical; if TRUE, an x[i] equal to the breaks value will be included in the first (or last, for right = FALSE) bar. This will be ignored (with a warning) unless breaks is a vector.


Logical; if TRUE, the histogram cells are right-closed (left open) intervals.


The density of shading lines, in lines per inch. The default value of NULL means that no shading lines are drawn. Non-positive values of density also inhibit the drawing of shading lines.


The slope of shading lines, given as an angle in degrees (counter-clockwise).


A colour to be used to fill the bars. The default of NULL yields unfilled bars.


The color of the border around the bars. The default is to use the standard foreground color.


Vector; range of x values to use for both counting and plotting. The default NULL will span the range of histogram breaks. If length equals 1 then the argument is taken to mean the sigma range to select for plotting and the clipping is done by magclip. If this is set to 'auto' then the limits will be estimated from the data dynamically. See examples.


Vector; range of y limits to show in the histogram plot.


Logical; draw the histogram (otherwise it just returns the count data).


Logical; if TRUE and xlim is used then the followign is printed out: summary of the data selected, standard-deviation the 1/2-sigma implied quantiles, and number and fraction of displayed data. Note all numbers are computed for the logged values of the x input if log= x | xy | yx.


Logical, if TRUE the histogram will be added to the current plot. Be careful to match log properties if adding, else the comparison will be of little use and hard to interpret.


Log axis arguments to be passed to hist and plot. E.g. use 'x', 'y', 'xy' or 'yx' as appropriate. Default ” assumes no logging of any axes. If the x axis is logged then the histogram will be calculated in log-space.


Determines if axis labels should be unlogged. E.g. use 'x', 'y', 'xy' or 'yx' as appropriate. See magaxis.


Numeric scalar; an additional scaling parameter to apply to the frequnecy counts. This is useful if you want to get the y axis in to certain units, e.g. the counts represent objects in 10 square degrees of sky, so to get the y-axis into units of N/sq.deg you would set scale=1/10.


Logical; if FALSE (default) then counts and density are totals for the current bin (usual sense of a histogram), if TRUE then counts and density are cumulative totals of all counts up to and including the current bin (always from lowest x upwards).


Function; optionally the user can provide a standard (or custom) p-test to be computed on the display (i.e. trimmed) data. This might be e.g. a Normality test with the shapiro.test function etc. The results are printed to screen below the other standard summary information if verbose=TRUE.


Arguments to be parsed to magplot.


To better replicate the base hist plot you might consider setting frame.plot=FALSE, which will be parsed to magplot and turn off the outer box. The default behaviour might change in the future.


An object of class "histogram", basically the same output as produced by hist. Note where axes are logged, the corresponding hist list values will not be logged when returned. This is to make it easy to take a histogram object and plot it with different log scalings on the axes (see Examples). For the x axis this means the "breaks" and the "mids" items, and for the y axis this means the "counts" and the "density" items.

Appended to the end of the usual hist output are the summary of the sample (list element "summary") and the standard-deviation / 1 and 2-sigma quantile range (list element "ranges").


Aaron Robotham

See Also



maghist(rnorm(1e4), xlim=c(-2,4))

#Notice the x-limits are close to -3/3, since  if we ask for xlim=3 (a 3-sigma range)

maghist(rnorm(1e4), xlim=3, verbose = FALSE)

#The 'auto' option allows magclip to dynamically estimate a clip value (which is similar
#in this case, but need not be in general).

maghist(rnorm(1e4), xlim='auto', verbose = FALSE)

#Test of log histograms:



#Test of plotting histogram objects:


#Nice to see a grid with large ranges:

maghist(rnorm(1e6), grid=TRUE)
maghist(rnorm(1e6), log='y', grid=TRUE)

asgr/magicaxis documentation built on March 26, 2024, 9:50 p.m.