*! Version 1.2.0 29 July 2014
help spechist

Title

spechist --
Specific histograms for continuous variables

Syntax

spechist varname [if] [in] [weight]
,
method(method_options)
[
metdisplay(display_options)
coptions(combine_options)
histogram_options
]

Description

spechist produces a histogram, or combination of histograms, for the
variable specified in varname where either the bin width or the number of
bins are calculated by the specified method(s).

You can specify one or more methods in the method() option, or
choose all. When you specify more than one option, or when you specify
all as your option, a combination of the histograms will be generated.

Options

method(method_options)

This is a required option. It specifies the method or methods you want to
use. You can specify more than one option by simply passing them separated
by spaces, e.g. method(wand doane). When you do,
spechist will create a combination of all the histograms generated
with the different methods that you specified. When you just specify
one method, spechist will generate just one histogram with the
specified method. If you specify all as your method, spechist
will produce a graph combining the histograms generated with all methods
available, which is why you can only specify all as a method on its
own.

method_options

sqrt
This uses the ceiling of the minimum of either the square root of the number
of observations or 50 as the number of bins. This is a technique used by
several software packages, for example by Microsoft Excel.

sturges
This uses Sturges (1926)'s method to calculate the number of bins.

rice
This uses the method suggested by Rice University in its
online statistics book,
chapter II, graphing distributions, section 5, histograms, to calculate the
number of bins.

doane
This uses Doane (1976)'s calculation of the number of bins.

scott
This uses Scott (1979)'s method to calculate the bin width.

freedman
This uses Freedman and Diaconis (1981)'s method to calculate the bin width.

wand
This uses Wand (1997)'s zero-stage rule to calculate the bin width.

stata
This uses Stata's default method of calculating the number of bins.

all
This option uses all of the previous mentioned methods to generate as many
histograms.

metdisplay(display_options)

This option is not required. It allows you to specify where to display the
method used in the histogram, or to specify that you don't want to display
it. If you don't set this option it will default to showing the method in
the subtitle.

If you pass any additional text for the textbox you set in this option, by
setting the option for the corresponding textbox, the method will be combined with the text
thus: the method is displayed first, followed by a colon, and then followed
by the text specified. For example, spechist varname,
me(sturges) metd(title) title(First Section) will display
"Sturges (1926): First Section" as the title (without the double quotes, of
course). See the examples below.

display_options

title
The method will be displayed as the title of the graph.

subtitle
The method will be displayed as the subtitle of the graph. This is the
default

note
The method will be displayed as a note in the graph.

caption
The method will be displayed as the caption of the graph.

none
The method will not be displayed.

coptions(combine_options)

This option is available so that you specify the options you want to set for
the graph combine command that will combine the histograms
when you specify more than one method of estimation. It is thus only allowed
when you either specify more than one method, or when you specify all
as your method option.

histogram_options

All the options for histogram are allowed except: bin(#)
width(#) and discrete.

The options nodraw, name(name, ...), and
saving(filename, ...) are valid when specifying only one method of
estimation. If you want to not display, to name the final combined graph, or
to save the final combined graph when specifying more than one method, you
should submit these options in the coptions(combine_options) option.

weight

Only fweights are allowed.

Examples

Load a dataset to use the command:

. sysuse citytemp, clear

Use the command:

. spechist tempjan, method(sturges)

. spechist tempjan, me(doane) metd(none)

. spechist tempjan, me(scott) subtitle(West Subsample)

. spechist tempjan, me(sqrt wand doane scott) metd(caption) kden

. spechist tempjuly, me(all) kden copt(imargin(small))

Stored results

spechist stores the following in r():

Scalars:

r(start) The start() value or minimum value of
varname.

r(N) The number of observations.

r(method_width) The common width of the bins for the
specified method.

r(method_bin) The number of bins for the specified
method.

r(method_max) The upper limit of the last bin for the
specified method.

r(method_min) The lower limit of the first non-empty bin for
the specified method.

r(method_area) The area of the bars for the specified
method.

Matrices:

r(method_bins) The boundaries for the different bins used in
the specified method. It includes the min as the first value, and the
max as the last value in the matrix.

The method specific scalars and matrices will only be available for those
method_options specified in the
method() option, and for all methods if all is specified for
method_options.

References

Doane, David P. 1976. Aesthetic Frequency
Classifications. The American Statistician 30(4): 181-183

Freedman, David and Diaconis, Persi. 1981. On the Histogram as a Density
Estimator: L2 Theory. Zeitschrift für Wahrscheinlichkeitstheorie und Verwandte Gebiete
57(4): 453-476

Scott, David W. 1979. On Optimal and Data-Based Histograms. Biometrika
66(3): 605-610

Sturges, Herbert A. 1926. The Choice of a Class
Interval. Journal of the American Statistical Association 21(153): 65-66

Wand, M. P. 1997. Data-Based Choice of Histogram Bin
Width. The American Statistician 51(1): 59-64

Acknowledgements/Comments

I would like to thank Joe Canner for several comments that helped in the
development of this program, and Nicholas J. Cox for comments on SMCL
formatting and spechist's functionality.

If you know of another method to calculate either the number of bins, or bin
width, please email to notify me about it and a reference for me to be able
to look it up at the address provided below. I would
love this program to grow and capture as many specific methods as possible
so that it makes all our lives much easier.

Author

Alfonso Sánchez-Peñalver

Lock Haven University of Pennsylvania

Lock Haven, PA USA

asp155@lhup.edu

Also see

Online: [R] histogram, [G-2] graph combine