*! NJC 19mar2024/30mar2024

*! twoway__histogram_gen version 1.1.0 15nov2022

Title

twoway__whistogram_gen -- Histogram subroutine supporting aweights and iweights

Syntax

twoway__whistogram_gen
varname
[weight]
[if exp]
[in range]
[,
{discrete_options|continuous_options}
common_options]

where discrete_options are

discrete_options Description

discrete specify data are discrete
width(#) width of bins in varname units
start(#) theoretical minimum value

and where continuous_options are

continuous_options Description

bins(#) # of bins
width(#) width of bins in varname units
start(#) lower limit of first bin

and where common_options are

common_options Description

density draw as density (default)
fraction draw as fractions
percent draw as percents
frequency draw as frequencies

generate:(h x [, replace ]) generate variables

display display (bin) start and width

aweights and iweights are allowed; see weights.
For more detail, see Remarks below.

Description

twoway__whistogram_gen generates a variable containing densities,
fractions, percents, or frequencies of the occurrence of bins (class intervals) of
varname and a corresponding variable containing bin midpoints.
Its distinctive feature is support for aweights and iweights.

This tool was written for generating histograms: see
[G-2] graph twoway histogram.
In practice, you may wish to follow by calling up
[G-2] graph twoway bar.

On occasion, you may have estimated frequencies that have fractional
parts. Calling up histogram,
twoway histogram, or twoway__histogram_gen will not work with such weights. Frequency weights must be integers, with no exceptions.
A work-around for such a problem is to use this command with iweights
and the frequency option. Other way round, the frequency option is
not allowed with aweights.

The intent of this command is not to generalise twoway__histogram_gen
but to complement it. On the former, see also Harrison (2005).

Options

discrete_options affect the parameters needed to draw a discrete
histogram. See [R] histogram for more details.

continuous_options affect the parameters needed to draw a continuous
histogram. See [R] histogram for more details.

density,
fraction,
percent, and
frequency
are alternatives. They specify whether you want the histogram scaled to
density units, fractional units, percents, or frequencies.
density is the
default. See [R] histogram for more details.

generate(h x [, replace]) specifies the
names of the variables to generate. The height of each bin will be placed in
h and the center of each bin will be placed in x. The
replace option indicates that these variables may be replaced if they
already exist.

display indicates that a short note be displayed indicating the number of
bins, the lower limit of the first bin, and the width of the bins. The output
displayed is determined by whether the discrete option was specified.

Examples

. webuse nlswork, clear

. twoway__whistogram_gen grade [aweight=ttl_exp], percent discrete gen(percent grade_d)

. local note "note(Weighted by total experience)"

. twoway bar percent grade_d, fcolor(stc1*0.2) barw(0.8) xla(0/18) `note' name(G1, replace)

. twoway__whistogram_gen grade [iweight=ttl_exp], frequency discrete gen(frequency grade_f)

. twoway bar frequency grade_f, fcolor(stc1*0.2) barw(0.8) xla(0/18) ytitle(Total experience) name(G2, replace)

. graph combine G1 G2

Author

Nicholas J. Cox, Durham University, UK

n.j.cox@durham.ac.uk

Acknowledgments

This command is just a slightly modified cousin of official
command twoway__histogram_gen. I thank Jeff Pitblado for comments.
It is to be regarded as community-contributed.

Reference

Harrison, D. A. 2005.
Stata tip 20: Generating histogram bin variables.
Stata Journal 5: 280-281.

Stored results

twoway__whistogram_gen stores the following in r():

Scalars:

r(N) number of observations (aweights) or sum of weights (iweights)
r(bin) number of bins
r(width) common width of the bins
r(start) start() value or minimum value of varname
r(min) lower limit of the first non-empty bin
r(max) upper limit of the last bin
r(area) area of the bars

Macros:

r(type) "density", "fraction", "percent", or "frequency"