help matstat

Title

matstat -- tabstat, with assembling of results in one matrix

Syntax

matstat varlist [if] [in] [weight] , mat(string) stats(string)
[ options ]

Options

mat(string) name for matrix to be constructed; required

stats(statnames) statistic(s) to be calculated for each variable in varlist; required

dist(string) requests percentage distribution of "by()" variable

by(varname) stratifying variable

layout(string) structure of matrix ("horizontal" vs. "vertical")

total(string) treatment of Total

missing treatment of missing on "by()" variable

xpose transpose matrix

tabshow(%fmt) display tabstat table, with format specified

outfile(string) write out matrix to Excel file

Description

matstat executes Stata procedure tabstat and then assembles results in one matrix - tabstat
table becomes matstat matrix. note: it is not necessary to first execute tabstat, matstat
does this.

Rationale: tabstat, with the "save" option, saves the results in a set of r() matrices, one
matrix for each category of the "by( )" variable. tabstat denotes these matrices "r(Stat1)",
"r(Stat2)", and so forth. matstat constructs one matrix that combines these separate matrices.
The goal is to make results from tabstat available in convenient form for further use
(for example putdocx, putexcel, estout, or author's procedure mswtable).

Standard Features

varlist are the variables for which stats() are to be
calculated. Separate by space (usual tabstat syntax). varlist is required.

[if] [in] specifies selection criteria (if any).

[weight] specifies weighting (if any). tabstat supports aweight and fweight.

Options

mat(string) provides a name for the matrix to be constructed. This option is required.

stats(statnames) specifies the statistic(s) to be calculated for each variable in varlist.
This can be any of the statistics available in tabstat.
More than one statistic can be requested; if so, separate by space or comma, and see layout() below.
This option is required.

dist(string) requests percentage distribution of by() variable, in addition to
statistics requested in stats(). This is not available for all matrix structures; see discussion
below Percentage Distribution Vector. Options are "first" and "last", to place this vector left/top or
right/bottom, respectively, depending on matrix orientation.

by(varname) identifies stratifying variable.
Standard Stata syntax for "by( )".

layout(string) defines the structure of the matrix.
This is applicable only if stats() requests more than one statistic.
Three layouts are available: "horizontal1" (default), "horizontal2", or "vertical".
See discussion below Matrix Structure.

total(string) determines the treatment of the Total vector.
"no" requests omission; default is inclusion. "top" requests placement as
top row; default is bottom row. Either, but not both, may be specified.

missing requests inclusion of missing on by() variable as a
separate category. The default is to discard this set of observations. matstat
labels this category "missing", and ordinarily it is placed at the bottom of the matrix.

xpose transposes the matrix once it is assembled.

tabshow(%fmt) asks for screen display of the tabstat table,
with the format of the cells specified within parentheses. (If dist() is
requested, this tabulation too is displayed.) Default is no display. This
option does not affect the format of the elements of the contructed matrix.

outfile(string) requests that the matrix be saved as an Excel file.
Provide full file specification (exact directory + file name), and within quotes, without
file extension (matstat imposes "xlsx"). matstat uses putexcel to accomplish this.
Row names and column names are preserved.
Matrix mat() remains available whether or not outfile is requested.

Matrix Structure

A by() variable is assumed under all scenarios below.

Possible requests are as follows:

One variable in varlist, one statistic in stats(): matstat will construct
a one-column vector, with categories of the by() variable constituting the rows.

One variable in varlist, two+ statistics in stats(): matstat will construct
either a multi-column matrix or a one-column vector, depending on whether specified layout() is
"horizontal" (default) or "vertical", respectively.

Two variables in varlist, one statistic in stats(): matstat will construct
a two-column matrix. Three variables in varlist will yield a three-column matrix. And so
forth. Option layout() is not available; effectively the layout is "vertical".

Two+ variables in varlist, two+ statistics in stats(): the matter is more
complicated. matstat offers three structures via option layout(): "horizontal1"
(default), "horizontal2", and "vertical". With the default placement of Total at the bottom,
these layouts are as follows:

horizontal1 (default)
-----------
Variable1 Variable2
Stat1 Stat2 Stat3 Stat1 Stat2 Stat3
Stratum1
Stratum2
Stratum3
Total

horizontal2
-----------
Variable1 Variable2
Stratum1 Stratum2 Stratum3 Total Stratum1 Stratum2 Stratum3 Total
Stat1
Stat2
Stat3

vertical
--------
Variable1 Variable2
Stratum1 Stat1
Stat2
Stat3
Stratum2 Stat1
Stat2
Stat3
Stratum3 Stat1
Stat2
Stat3
Total Stat1
Stat2
Stat3

Note that three further layouts are easily obtained by transposing (option xpose)
the above layouts:

horizontal1, transposed
-----------------------
Stratum1 Stratum2 Stratum3 Total
Variable1 Stat1
Stat2
Stat3
Variable2 Stat1
Stat2
Stat3

horizontal2, transposed
-----------------------
Stat1 Stat2 Stat3
Variable1 Stratum1
Stratum2
Stratum3
Total
Variable2 Stratum1
Stratum2
Stratum3
Total

vertical, transposed
--------------------
Stratum1 Stratum2 Stratum3 Total
Stat1 Stat2 Stat3 Stat1 Stat2 Stat3 Stat1 Stat2 Stat3 Stat1 Stat2 Stat3
Variable1
Variable2

Labeling of Matrix Rows/Columns

(i) varlist variables: variable names are used

(ii) stats(): statistic shorthands, as required by tabstat, are used

(iii) by() variable: value labels are carried over from tabstat; these
are the macros "r(Name1)", "r(Name2)", and so forth

(iv) dist vector is labeled simply "dist"

Composite labels:

- horizontal1: column labels are an amalgam of the variable name and the statistic shorthand

- horizontal2: column labels are an amalgam of the variable name and the stratum label (value label)

- vertical: row labels are an amalgam of the stratum label (value label) and the statistic shorthand

These labels often will be long and unwieldy, but they have the virtue of being precise and unambiguous.

note: Stata has a limit of 32 characters for value labels. There's a risk of exceeding
this limit, specifically:

- column label under the horizontal2 layout (variable name + stratum label)

- row label under the vertical layout (stratum label + statistic shorthand)

matstat checks whether these labels are too long and, if so, truncates the stratum label.

Percentage Distribution Vector

This vector is not available with "vertical" layout.

More specifically, dist() adds vectors as follows:

- One variable in varlist, one statistic in stats(): additional column

- One variable in varlist, two+ statistic in stats(): additional column
("horizontal1") or additional row ("horizontal2")

- Two+ variables in varlist, one statistic in stats(): additional column

- Two+ variables in varlist, two+ statistics in stats(): additional column (layout
must be "horizontal1")

Examples

matstat tfr unwant, stats(mean) by(Region) total(no) xpose mat(R)

matstat tfr unwant if v024==1 [aw=v005], stats(p50 n) by(Region) mat(A)

matstat tfr unwant, stats(mean,sd) by(Region) layout(vertical) total(top) mat(X) tabshow(%4.2f)

matstat tfr unwant, stats(mean) by(Region) dist(last) mat(X) tabshow(%4.2f)

Similar procedures

statsmat and tabstatmat are community-written procedures that offer some
of matstat's functionality. However:

- while both can be employed to construct matrix with either "horizontal" layout (this
entails successive executions, then joining matrices), neither command can be wielded to produce
matrix with "vertical" layout

- statsmat does not include Total category in the resulting matrix, and category labels
are not fully preserved

- neither offers the equivalent of dist option

Some matrix basics

List existing matrices: matrix dir

Examine contents of matrix: matrix list A

Create 5x3 matrix with cell contents ".": matrix A = J(5,3,.)

Create matrix from results: matrix A = r(table)

Combine matrices side-by-side: matrix C = A,B ("column join")

Stack matrices: matrix D = A \ B \ C ("row join")

Transpose matrix: matrix B = A'

Extract sub-matrix:
matrix B = A[2,1...] 2nd row, all columns
matrix B = A[1...,3] All rows, 3rd column
matrix B = A[2...,2] 2nd to last row, 2nd column
matrix B = A[3,3...] 3rd row, 3rd to last column
matrix B = A[1..3,1...] 1st through 3rd row, all columns
matrix B = A[2..4,1..3] 2nd through 4th row, 1st through 3rd column

Sub-matrix substitution:
matrix B[1,1] = A Copy in matrix A, upper left corner at row 1 and column 1
matrix B[2,3] = A Copy in matrix A, upper left corner at row 2 and column 3

Author

John Casterline, Ohio State University, casterline.10@osu.edu