maghist | R Documentation |

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, ...)
```

`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 |

`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 |

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

`hist`

```
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)
```

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.