maghist: Magically pretty histograms
In asgr/magicaxis: Pretty Scientific Plotting with Minor-Tick and Log Minor-Tick Support
maghist R Documentation
Magically pretty histograms
Description
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.
Usage
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, ...)
Arguments
x
A vector of values for which the histogram is desired.
breaks
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.
freq
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).
include.lowest
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.
right
Logical; if TRUE, the histogram cells are right-closed (left open) intervals.
density
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.
angle
The slope of shading lines, given as an angle in degrees (counter-clockwise).
col
A colour to be used to fill the bars. The default of NULL yields unfilled bars.
border
The color of the border around the bars. The default is to use the standard foreground color.
xlim
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.
ylim
Vector; range of y limits to show in the histogram plot.
plot
Logical; draw the histogram (otherwise it just returns the count data).
verbose
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.
add
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
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.
unlog
Determines if axis labels should be unlogged. E.g. use 'x', 'y', 'xy' or 'yx' as appropriate. See magaxis.
scale
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.
cumsum
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).
p.test
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.
Details
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.
Value
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").
Author(s)
Aaron Robotham
See Also
hist
Examples
maghist(rnorm(1e4))
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:
testdata=10^(runif(1e3,0,4))
maghist(testdata)
maghist(testdata,log='x')
maghist(testdata,log='y')
maghist(testdata,log='xy')
maghist(testdata,freq=FALSE)
maghist(testdata,freq=FALSE,log='x')
maghist(testdata,freq=FALSE,log='y')
maghist(testdata,freq=FALSE,log='xy')
#Test of plotting histogram objects:
testhist=maghist(testdata,log='xy')
maghist(testhist)
maghist(testhist,log='x')
magplot(testhist,log='y')
magplot(testhist,log='xy')
#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 Oct. 21, 2024, 7:40 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| maghist | R Documentation |
Magically pretty histograms
Description
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.
Usage
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, ...)
Arguments
x |
A vector of values for which the histogram is desired. |
breaks |
One of:
In the last three cases the number is a suggestion only; the breakpoints will be set to |
freq |
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). |
include.lowest |
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. |
right |
Logical; if TRUE, the histogram cells are right-closed (left open) intervals. |
density |
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. |
angle |
The slope of shading lines, given as an angle in degrees (counter-clockwise). |
col |
A colour to be used to fill the bars. The default of NULL yields unfilled bars. |
border |
The color of the border around the bars. The default is to use the standard foreground color. |
xlim |
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 |
ylim |
Vector; range of y limits to show in the histogram plot. |
plot |
Logical; draw the histogram (otherwise it just returns the count data). |
verbose |
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. |
add |
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 |
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. |
unlog |
Determines if axis labels should be unlogged. E.g. use 'x', 'y', 'xy' or 'yx' as appropriate. See |
scale |
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. |
cumsum |
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). |
p.test |
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 |
... |
Arguments to be parsed to |
Details
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.
Value
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").
Author(s)
Aaron Robotham
See Also
hist
Examples
maghist(rnorm(1e4))
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:
testdata=10^(runif(1e3,0,4))
maghist(testdata)
maghist(testdata,log='x')
maghist(testdata,log='y')
maghist(testdata,log='xy')
maghist(testdata,freq=FALSE)
maghist(testdata,freq=FALSE,log='x')
maghist(testdata,freq=FALSE,log='y')
maghist(testdata,freq=FALSE,log='xy')
#Test of plotting histogram objects:
testhist=maghist(testdata,log='xy')
maghist(testhist)
maghist(testhist,log='x')
magplot(testhist,log='y')
magplot(testhist,log='xy')
#Nice to see a grid with large ranges:
maghist(rnorm(1e6), grid=TRUE)
maghist(rnorm(1e6), log='y', grid=TRUE)
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.