help statstoalso see: statout, graphsto, graphout

Title

statsto -- Collecting statistical results | 08June2012

Overview

statsto saves numbers to a matrix in order to summarize results,
create tables, and generate variables.
You can save results from Stata commands and from matrices and scalars you create.
Collection options specify what information to save and the the
columns where it is saved.
Row options indicate the rows where the information is saved.
The command statout lets you rearrange and select rows and columns;
print the matrix with formatting;
export the matrix as a TeX, csv, rtf or text file;
and many other things.

Information can be saved from scalars (i.e., single numbers) or from
matrices.
With scalars, rowselect() specifies the row where the information is saved.
ereturn(), rreturn(), and user() specify which scalars to save.
Matrices created by estimation commands (e.g., regress) are
saved with using ebreturn() and rbreturn() to specify which
statistics to save (e.g., the estimate, the z-value).
rowselect() specifies which estimates to save (e.g., the coefficient
for X1 and X2).
Non-estimation matrices are saved with matrix() using
rowselect() to select rows and colselect() to select columns.

Much of statsto power comes from being able to retrieve information that
is saved by Stata commands in what are called returns.
For example, summarize var1 displays summary statistics in the Results Window
and saves the statistics in r-returns.
These returns can be scalars, matrices, and macros.
To see the returns, use rreturn list.
Estimation commands return information in e-returns.
To see this, ereturn list.
For more information on returns, check here.

For more information and examples, please visit the Collect Website.

General syntax

statsto [collect_matrix], options

where collect_matrix is a new or exiting matrix where results are saved.
If no name is specified, StatSto is used.

Table of contents

1. Saving scalars
2. Saving estimates and related statistics
3. Using equation names
4. Saving values from a matrix
5. Generating variables from columns
6. Viewing and saving
7. Utility options
8. Global with a list of matrices

Options

Collecting scalars

Scalars in e-returns and r-returns are saved with rreturns() and ereturns().
Scalars created by the user are saved with user().

Scalars returns when specifying column names

rreturns([column_name1=] return_name1...)
Save r(return_name#) in column return_name#.
If column_name# is used, save the return in column column_name#.
For example, rreturns(Mean=mean Var) saves r(mean) in column
Mean and return r(Var) in column Var.
If the columns do not exist in collect_matrix, new columns are added.
If the column exists, information in that column is over-written.

ereturns([column_name1=] return_name1...)
Save scalar e-returns.

Scalars from lincom and nlcom

rreturns( [ est | estimate | lb | ub | z | t | p ] )
lincom and nlcom estimate linear and nonlinear combinations
of estimates.
You can save the estimates and related statistics.
For example, after lincom wc + hc, you save the estimate, the lower
and upper bounds, and the p values with
statsto, r(B_wchc=est LB=lb UB=ub p).

Scalars from test and testnl

rreturns( [ chi2 | F | df | df_r | p ] )
Test results from test and testnl are saved using
the return names listed as options above.
You can rename the columns where results are stored. For example,
statsto, r(pvalue=p)

User created scalars

user(column_name1=user_scalar1...)
User scalars can be local macros indicated as `local_name';
global macros indicated as $global_name,
scalars indicated as scalar_name,
or numbers.
For example, you can save local mylocal=1, global myglobal=2,
scalar myscalar=3, as:
statsto, u(MyLocal=`mylocal' MyGlobal=`myglobal' MyScalar=myscalar).

Combining scalar types

You can combine scalar types in the same statsto command. For example,
statsto, u(Local1=`mylocal' Global2=$myglobal) r(Mean=mean Var)

Specifying the row for scalars

rowselect(row_name)
Scalars are saved in row row_name.
If it does not exist, it is added to collect_matrix.
If rowselect() is not specified, scalars are saved in a new row
Row# where # is the row number.
The row where results are saved is called the active row.

Collecting estimates

Estimation commands return estimates to the matrix e(b);
margins saves them to r(b) or e(b) when the post option
is used.
Variances and covariances are returned to the matrices e(V) or r(V).
statsto uses the returned information to estimate statistics you can save.

Specifying which statistics to save

ebreturns([new_name1=] statistic1...)
Save statistic# in column statistic#; if
new_name# is indicated, save it in that column.
You can rename some statistics and not others:
ebreturn(Beta=b pvalue=p z).
rbreturn() saves margins estimates using the same syntax.

The statistics that can be saved are:

statistics Description

b Estimates

est Same as b

estimate Same as b

expb Exponential of b

or Odds ratio; same as expb

orpct Percentage change in the odds: 100*(expb-1)

lb Lower bound of confidence interval

ub Upper bound of confidence interval

p p-value

se Standard error

t t-value

z z-value

level Level used for confidence interval

Selecting which estimates to collect

The elements in e(b) or r(b) have names that you can see with
matrix list e(b) or matrix list r(b).
rowselect() selects which estimates to save.

rowselect(estimate_name1...)
Saved the named estimates in rows named estimate_name#.

rowselect(new_name1=estimate_name1...[_rest])
Save the named estimates to rows named new_name#.
You can rename some estimates but not others:
rowselect(IQ=iq Weight=wt age).
To keep the rest of the estimates without renaming, use _rest:
rows(IQ=iq Weight=wt age _rest). iq is saved in row IQ and
wt in row Weight, with the rest of the estimates saved in rows with
the estimate's name.

Stacking estimates

Commands such as mlogit have multiple equations. By default the
estimates from all equations are "stacked" into a vector with the first
equation at the top, then the second, etc.
The unstack option arranges each equation from left to right.
An example should make this clear:

. statsto, ebreturn(b) list decimal(2) clear

| b
-------------+-----------
Menial |
white | -0.36
ed | -0.04
_cons | -0.24
-------------+-----------
BlueCol |
white | 0.84
ed | -0.15
_cons | 0.75

. statsto, ebreturn(b) list decimal(2) clear unstack

| Menial | BlueCol
| b | b
-------------+-----------+-----------
white | -0.36 | 0.84
ed | -0.04 | -0.15
_cons | -0.24 | 0.75

at() values from margins

margins returns values of the regressors at which predictions
are made in the matrix r(at) or e(at).
The columns have the names of the regressors.

atreturns([new_name1=] regressor1...[_rest])
Save column regressor# e(at)} to column regressor#;
if new_name1 is specified, save it to that column.
You can rename some columns and not others: atreturns(age=x1 income).
To select the remaining columns without renaming add option _rest.

The rowselect() option is used to select rows.

Equation names

The row and column names in matrices are known as simple names.
In addition, each row and column can have an equation name.
The equation name appears before the simple name and ends with a colon.
For example: Eq1:Row1.
Often e(b) uses the parameter name as the simple name
with the equation name describing the part of the model associated with
the parameter. For example, from ologit:

e(b)[1,9]
warm: warm: warm: cut1: cut2: cut3:
yr89 male white _cons _cons _cons
y1 .5239 -.7332 -.3911 -2.465 -.6309 1.261

warm: is the equation name for the estimates for yr89,
male, and white. The _cons estiamtes have equation names
indicating which cutpont they are.
If we save estimates with equation names and then list the matrix,
the equation name is in bold on the left margin.

You can add your own equation names when saving results as a way to
document what is in your matrix and to distinguish similar information.
For example, you can save means for men and women in separate columns
that are labeled by equation names:

sum income if female
statsto income, r(Women:Mean=mean) clear
sum income if male
statsto income, r(Men:Mean=mean) list

Equation names in statsto options

atreturns(eq_name#:new_name#=at_variable#...)
Save column at_variable# from r(at) in column
eq_name#:new_name#.

ebreturns(eq_name#:new_name#=return_name#...)
Save return_name# in column eq_name#:new_name#.
The same syntax works for rbreturns().

ereturns(eq_name#:new_name#=return_name#...)
Save return_name# in column eq_name#:new_name#.
This syntax also works for rreturns()

rowselect(eq_name:row_name)
Save the scalars in row eq_name:row_name.

rowselect(eq_name1:new_name1=name1...)
The estimate name# is saved in row eq_name#:new_name#.

Adding equation names to all new rows or columns

coleqstub(column_stub)
Add the equation name column_stub to all incoming columns.
For example, statsto, ebreturn(b p) coleqstub("Model 1")
adds add "Model 1" above columns "b" and "p."

roweqstub(row_stub)
Add the equation name row_stub to all incoming rows.
For example, statsto, ebreturn(b p) roweqstub("Model 1") adds "Model 1"
beside all incoming rows.

Saving information from matrices

Values from a matrix can be added to collect_matrix.
For example, you can add the correlation that correlate returns to r(C).
Or, you can add a matrix created with matrix commands.
Matrices from mata can be saved if they are moved from mata
to Stata with st_matrix().

Specifying the input matrix

matrix(input_matrix)
Add information input_matrix to the collect_matrix.
For example, matrix(r(C)) or mat(mymatrix).

Selecting rows from input_matrix

rowselect(row_number1...)
Save information from rows numbered row_number#.
Multiple rows can be selected with first_row-last_row.

rowselect([new_name1=] row_name1...)
Save information from the named rows.
If specified, the information is saved to row new_name#.
Multiple rows can be saved with first_name-last_name.

rowselect(stub=_all)
All rows are selected and placed in rows named
stub#.

You can mix selecting rows by number and name such as
row(1 3 r7-r8 5).
If row() is not specified, all rows are saved.

Selecting columns from input_matrix

colselect()
Select the columns of input_matrix to save.
Columns are selected with the same syntax as rows.

Where the selected matrix values are placed

By default input_matrix is placed in
rows and columns of collect_matrix with names corresponding to
names in input_matrix.
When the a row and column exist, information in collect_matrix is overwritten.
When a row or column does not exist, a new row and/or column
is added to collect_matrix.

Alternatively, you can specify the start row and column in collect_matrix
where the selected rows and columns from input_matrix are saved.
Element 1,1 of the selected portion of input_matrix is placed
in the specified start row and start column with
the remaining elements placed below and to the right.
New rows and columns are added to collect_matrix as needed.

rowstart(rowname | row#) This specifies the start row.
If rowstart() is not used by colstart() is, the start row is
1.

colstart(rowname | row#) This specifies the start column.
If colstart() is not used by rowstart() is, the start column
is a a new column on the right edge of collect_matrix.

Generating variables from columns

You can create variables from the columns of your matrix.
This is particularly useful with margins to save to plot.

generate(column_list | column_numbers | _all)
Variables are generated from the specified columns with names
corresponding to the column names.
_all selects all columns.
If the transpose option is used, variables are created from the rows.
If the matrix has equation names, refer to columns by their number rather than
their name.

Viewing and saving

You can view the collection matrix with formatting and save the matrix
with a new name.
You can also save the collection_matrix with a new name, for example, if
you want to save intermediate results.
More elaborate options for viewing, rearranging, renaming, and deleting rows and
columns are available with statout.

list List collect_matrix to the command window.

decimal(numlist) Set the number of decimal digits
for each column when listing the matrix.
Columns can have different numbers of decimal digits.
For example, statsto, list decimal(3 2).

format(string) Indicate the format to use for each
column when listing the matrix.
For example, statsto, list format(%9.2e %12.4e).

width(number) Specify the width of all columns.

title(title_string) Display title_string
above the matrix.

transpose Temporarily transpose the matrix
before it is displayed.

preview Display collect_matrix showing what the
matrix would like like after the current statistics are collected.
Those changes are not saved.

save(new_matrix_name) Save collect_matrix as a
matrix named new_matrix_name.
If transpose is used, the transposed matrix is saved.

Utility options

blank Add a blank row to collect_matrix.

clear Remove collect_matrix from memory
before saving results.
For example, to create a new matrix you could use
statsto mymat, eb(b) clear.
If mymat is a matrix in memory, it is removed before creating
a new mymat.

colstub(stub) Add stub to the front
of all column names. This is useful if you are saving the same type
of information from multiple sources.
For example, colstub(M1) puts M1 in front of the names of
the new columns.

rowstub(stub) Add the prefix stub to the front
of all row names.

level(number) Set the significance level used when calculating
upper and lower bounds. Must be between 10 and 99.999.

mv(. | .a | .b |...) Select the type of missing values to
using in blank cells of matrix_name.
When adding information to matrix_name, cells that do not have a
value assigned will contain missing values.
By default .z is used which displays as a blank space.
You can fill empty cells with other types of missing values.

verbose Show warnings if data in matrix is being
replaced with new values.

Global with list of matrices

Each matrix you work with using statsto is saved to a global
macro statsto_stored_matrices.
This global is used by statout to automate the creation of tables
from matrices.

drop Remove matrix names from global used by statout.

dir Lists matrix names stored in global.

Authors

Joseph D. Wolfe, Indiana University, jdwolfe@indiana.edu

Scott Long, Indiana University, jslong@indiana.edu

Also see

Manual: [M] matrix

Website: Collect Website