PyXPlot Users' Guide
PyXPlot Users' Guide : Reference manual : Command reference : histogram

1.27 histogram

histogram [ <range> ] <function name>()
     ( <filename> | { <expression> } | { <vector obj> } )
     [ every { <expression> } ]
     [ index <value> ]
     [ select <expression> ]
     [ using { <expression> } ]
     ( [ binwidth <value> ] [ binorigin <value> ] |
       [ bins (x1, x2, ...) ] )

The histogram command takes a single column of data from a file and produces a function that represents the frequency distribution of the supplied data values. The output function consists of a series of discrete intervals which we term bins. Within each interval the output function has a constant value, determined such that the area under each interval – i.e. the integral of the function over each interval – is equal to the number of datapoints found within that interval. The following simple example 

histogram f() 'input.dat'

produces a frequency distribution of the data values found in the first column of the file input.dat, which it stores in the function $$f(x)$. The value of this function at any given point is equal to the number of items in the bin at that point, divided by the width of the bins used. If the input datapoints are not dimensionless then the output frequency distribution adopts appropriate units, thus a histogram of data with units of length has units of one over length. The number and arrangement of bins used by the {\tt histogram} command\index{histogram command@{\tt histogram} command} can be controlled by means of various modifiers. The {\tt binwidth}\index{binwidth modifier@{\tt binwidth} modifier} modifier sets the width of the bins used. The {\tt binorigin}\index{binorigin modifier@{\tt binorigin} modifier} modifier controls where their boundaries lie; the {\tt histogram} command\index{histogram command@{\tt histogram} command} selects a system of bins which, if extended to infinity in both directions, would put a bin boundary at the value specified in the {\tt binorigin} modifier. Thus, if {\tt binorigin 0.1} were specified, together with a bin width of~ 20, bin boundaries might lie at~ $20.1$, $40.1$, $60.1$, and so on. Alternatively global defaults for the bin width and the bin origin can be specified using the {\tt set binwidth} and {\tt set binorigin} commands respectively. The example \begin{verbatim} histogram h() 'input.dat' binorigin 0.5 binwidth 2 \end{verbatim} \noindent would bin data into bins between $0.5$ and $2.5$, between $2.5$ and $4.5$, and so forth. Alternatively the set of bins to be used can be controlled more precisely using the {\tt bins}\index{bins modifier@{\tt bins} modifier} modifier, which allows an arbitrary set of bins to be specified. The example \begin{verbatim} histogram g() 'input.dat' bins (1, 2, 4) \end{verbatim} \noindent would bin the data into two bins, $x=12$ and $x=24$. A range can be supplied immediately following the {\tt histogram} command, using the same syntax as in the {\tt plot} and {\tt fit} commands; if such a range is supplied, only points that fall within that range will be binned. In the same way as in the {\tt plot} command, the {\tt index}\index{index modifier@{\tt index} modifier}, {\tt every}\index{every modifier@{\tt every} modifier}, {\tt using}\index{using modifier@{\tt using} modifier} and {\tt select}\index{select modifier@{\tt select} modifier} modifiers can be used to specify which subsets of a data file\ should be used. Two points about the {\tt histogram} command are worthy of note. First, although histograms are similar to bar charts, they are not the same. A bar chart conventionally has the height of each bar equal to the number of points that it represents, whereas a histogram is a continuous function in which the area underneath each interval is equal to the number of points within it. Thus, to produce a bar chart using the {\tt histogram} command, the end result should be multiplied by the bin width used. Second, if the function produced by the {\tt histogram} command is plotted using the {\tt plot} command, samples are automatically taken not at evenly spaced intervals along the ordinate axis, but at the centers of each bin. If the {\tt boxes}\index{boxes plot style@{\tt boxes} plot style}\index{plot styles!boxes@{\tt boxes}} plot style is used, the box boundaries are be conveniently drawn to coincide with the bins into which the data were sorted. $

PyXPlot Users' Guide