*! version 1.0.1 5aug2015

Title

tabstat2 -- Version of tabstat extended for use by the aidsproj and aidsdif programs

Syntax

tabstat2
varlist
[if] [in]
[weight]
[, options]

Main
by(varname)
group statistics by variable

statistics:(statname [...])
report specified statistics. See tabstat for details.

Options (additional to those in tabstat)
describe
Add output of Stata's describe varlist command as a header for tabstat output

noheader
Omit the usual header at the top of tabstat's output.

Option (enhanced version of tabstat)
save
store summary statistics in r(), including the matrix r(StatAll)

Description

The AIDSCost programs aidsproj and aidsdif produce tables of results
using this slightly enhanced version of Stata's standard command tabstat.
Some users may find this enhanced version of tabstat2 useful for other purposes.

Because these two projection programs perform computations with a large number of
digits, they display results following the American convention of
using comma's to demarcate 1,000's, 1,000,000's etc.. To accommodate the 10's or
100's of millions in global or regional aggregates, the programs display results
in the %12.1fc format. However, when tabstat's results are formatted
to contain more than 9 characters, the columns of results are wider than the
column headers, making it hard to visually associate the right-most column
headers to the columns of statistics they label.

One of tabstat2's added features enables it to expand the header for each column
to match the width of the column's formatted statistical results. This behavior
is automatic and requires no user interventiion.

tabstat2 also adds two additional options to Stata's tabstat
command, the describe option and the noheader option,
and augments the results stored by the save option.

The AIDSCost programs aidsproj and aidsdif invoke tabstat2
with the describe and the noheader options
in order to provide a more attractive and informative
header for each table of results. If the AIDSCost programs are executed with the
option putexcel, they invoke tabstat2 with the save option in order
to transfer tables of projection results to Excel.

Options

Main

by(varname) specifies that the statistics be
displayed separately for each unique value of varname; varname
may be integer valued or string. For instance, tabstat height would present
the overall mean of height. tabstat height, by(sex) would present
the mean height of males, and of females, and the overall mean height.
Do not confuse the by() option with the by prefix; both may
be specified.

statistics:(statname [...])}
report specified statistics. See tabstat for details.

Other options tabstat2 accepts tabstat's options. See tabstat for details.

Additional or Enhanced Options

describe
Add output of Stata's describe varlist command as a header for tabstat output

noheader
Omit the usual header at the top of tabstat's output.

save specifies that the summary statistics be returned in
r(). As documented in tabstat,
the overall (unconditional) statistics are returned in row matrix
r(StatTotal) (rows are statistics, columns are variables). The conditional
statistics are returned in the matrices r(Stat1), r(Stat2), ..., and
the names of the corresponding variables are returned in the macros
r(name1), r(name2), .... .

In addition to these returned results, tabstat2 with the option save
also returns an additional matrix called r(StatAll).
This matrix has dimensions (s x v), where
s is the number of distinct values of the by() variable and
v the number of variables in varlist. This r(StatAll) matrix stacks the row
matrices r(Stat1), r(Stat2), r(Stat3), ..., so that all the tabstat2 conditional
results are in a single matrix. With aidsproj's putexcel option, this matrix
becomes a sheet in the specified Excel file.

Examples

Setup

. sysuse auto

Show the mean (by default) of price, weight, mpg, and
rep78

. tabstat2 price weight mpg rep78, describe noheader

Show the mean (by default) of price, weight, mpg, and
rep78 by categories of foreign

. tabstat2 price weight mpg rep78, by(foreign) save

. return list

. matrix list r(StatAll)

With the save option, the r(StataAll) matrix is available
and contains the results conditional on the by() variable.

In addition to mean, show standard deviation, minimum, and
maximum

. tabstat2 price weight mpg rep78, by(foreign)
stat(mean sd min max) save

. matrix list r(StatAll)

With the save option, the r(StataAll) matrix now has
s x S rows, where s is the number of distinct values of the by()
variable and S is the number of requested statistics.

Author

Mead Over,
Center for Global Development, Washington, DC 20036 USA. Email:
MOver@CGDev.Org if you observe any
problems.