help statsto22also see: statout, graphsto, graphout

Title

statsto2 -- Collecting statistical results | 30May2012

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 matrix columns
6. Viewing, saving and exporting the collection matrix
7. Utility options
8. Global with a list of matrices
99. To do, questions, pending bugs

Overview

statsto2 lets you save numbers to a matrix in order to
summarize findings and create tables.
You can save information returned by Stata commands (e.g.,
estimates from models, results from tests, descriptive statistics)
and from a macro, scalar, or matrix in memory.
Columns of the matrix can easily converted to variables.
Row, column and equation names label the results and can be used to
specify the position in the matrix to save the numbers.
You can print the matrix with formatting. Or, use
statout to 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.

General syntax

statsto2 [collect_matrix]
,
options

collect_matrix is a new or exiting matrix where results are saved.
If no name is specified, StatSto is used.
collect_matrix can be a matrix in memory even if it was not
created by statsto2

Collecting scalars

Scalars can be collected from rreturns(), ereturns(),
and user created scalars.
By default, e-returns and r-returns are saved in columns
with the name of the return.
Alternatively, you can specify your own column name.
With user created scalars you must specify the column name where the
scalars are stored.
If a specified column does not exist it is added to the matrix.

If you specify a row name with row(), the scalars are put in a row
with that name.
If collect_matrix does not have a row with the specified name,
a row is added.
If you do not specify row(), results are put in a new row named
Row# where # is the row number.

Specifying the row to hold the scalar

row(row_name)
The scalars are placed in an existing row named row_name or a
new row with that name is added.
If row() is not specified, the results are placed in a new row with the
name Row#. The row where results are saved is called the active row.

Scalars returns without specifying column names

rreturns(return_name1 [return_name2]...)
Save r(return_name#) to column return_name# in the active row.
For example, rreturns(mean sd) saves r(mean) and r(sd)
from summarize to the active row in columns mean and sd.

ereturns(return_name1 [return_name2]...)
Save e(return_name#) to the active row in column return_name#.

Scalars returns when specifying column names

rreturns(column_name1 = return_name1 [column_name2 = return_name2]...)
Save r(return_name#) in column column_name#.
For example, rreturns(Mean=mean Var).
You can mix saving returns in columns with the return name
and others using a specified name.

ereturns(column_name1=return_name1 [column_name1=return_name1]...)
Save e(return_name#) in column column_name#.

User created scalars

user(column_name1=`local1' [column_name2=`local2']...)
The numeric local macros local# is saved in column_name#.
For example, with local La=1, local Lb=2:
statsto2, u(alocal=`La' blocal=`Lb').

user(column_name1=$global1 [column_name2=$global2]...)
The numeric global global# is saved in column column_name#.
For example, with global Ga=1, global Gb=2:
statsto2, u(aglobal=$Ga bglobal=$Gb).

user(column_name1=scalar1 [column_name2=scalar2]...)
Scalar scalar# is saved in column_name#.
For example, with scalar Sa=1, scalar Sb=2:
statsto2, u(ascalar=Sa bscalar=Sb).

user(column_name1=#1 [column_name2=#2]...)
Numbers are saved to column_name#.
For example, statsto2, u(anumber=1 bnumber=2).

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 along with statistics computed by
statsto2.
For example, after lincom wc+hc you can save the estimate, the lower
and upper bounds, and the p values with
statsto2, r(B_wchc=est LB=lb UB=ub p) row(MyEstimates).

Scalars from test and testnl

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

Combining scalar types

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

Collecting estimates

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

Selecting estimates to collect

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

rows(estimate_name1...)
Select the named estimates; the remaining estimates are not saved.
If row() is not specified, all estimates are saved.

rows(new_name1=estimate_name1...[_rest])
Save the estimate_name# estimates in rows of
collect_matrix named new_name#.
You can rename some estimates but not
others, such as: rows(IQ=iq Weight=wt age).
To keep the rest of the estimates without renaming them use _rest:
rows(IQ=iq Weight=wt age _rest).

Specifying which statistics to collect

The statistics that can be saved are:

Name 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.

These commands let you select the statistics to save:

ebreturns(statistic1...)
Each statistic is saved in a column named statistic#.
rbreturn() has the same syntax to retrieve estimates from r(b).

ebreturns(new_name1=statistic1...)
Save the statistics statistic# and save them in columns
named new_name#.
You can rename some statistics and not others:
eb(Beta=b pvalue=p z).
rbreturn() has the same syntax.

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 predictors.

atreturns(at_variable1...)
Save the columns at_variable# from r(at) or e(at) to
columns with the same name in collect_matrix.
For example, at(female) save column female from that at-matrix
to a column named female
with row names corresponding to the row names in r(at) or e(at).

atreturns(new_name1=at_variable1...[_rest])
You can select and rename the columns where the at_variables are saved.
You can rename some columns and not others: at(age=x1 income).
To select the remaining columns without renaming: at(age=x1 income _rest).

Using equation names

Row and column names, known as simple names, can also have
an equation name.
An equation name appears before the simple name and ends with a colon.
For example: Eq1:Row1.
Sometimes e(b) includes the parameter name as the simple name
with an 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 coefficients for yr89,
male, and white. The _cons have equation names that
indicate which cut-point they represent.
If we collected these estimates with statsto2, eb(b) list, the
output would list the equation names in bold on the left margin.
If a matrix return uses equation names, they will appear in collect_matrix.

You can also add equation names when you are collecting information which
is useful for labeling your printed matrix and distinguishing 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
statsto2 income, r(Women:Mean=mean) clear
sum income if male
statsto2 income, r(Men:Mean=mean) list

The statsto2 with equation names are:

rows(eq_name:row_name)
Place scalars in row eq_name:row_name.

rows(eq_name:new_name1=name1 new_name2=name2...)
With eb() and rb() this will do what?? Nothing with eb()??

rows(eq_name#:new_name#=number#...)
Row number# from the source matrix is saved in collect_matrix
in row new_name# with equation name eq_name#.

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

ebreturns(eq_name#:new_name#=return_name#...)
places return_name# in column eq_name#:new_name#.
The same applies for rbreturns().

atreturns(eq_name#:new_name#=at_variable#...)
Save the column at_variable# in a column named eq_name#:new_name#.

Saving information from matrices

Any matrix in memory can be added to the collect_matrix.
For example, you can add the correlation matrix returned to r(C) by pwcorr.
Or, you can add a matrix created with matrix commands.
Matrices from mata can be saved if they are moved from mata
to Stata using st_matrix().
To specify the matrix with information to place into collect_matrix:

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

Selecting rows from user_matrix

rows(rownumber1...)
Save information from these rows.
Multiple rows can be selected with firstrow-lastrow.

rows(rowname1...)
Save information from named rows.
Multiple rows can be saved with firstrowname-lastrowname.

rows(newname1=rowname1... newname2=rownumber2...)
Save the rows rowname# and row# to the rows newname# in the
collect_matrix.

rows(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 user_matrix

columns()
Specify the columns of user_matrix to save.
Columns are selected with the same syntax as rows.

Where the selected matrix values are placed

By default user_matrix is placed in
rows and columns of collect_matrix with names corresponding to
names in user_matrix.
When the a row and column exist, information in collect_matrix is
overwritten with a warning given.
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 user_matrix will be saved.
Element 1,1 of the selected portion of user_matrix is placed
in the specified start row and start column with
the remaining elements placed below and to the right.
If necessary, new rows and columns are added to collect_matrix.

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 the columns of collect_matrix

You can create variables from the columns of your matrix.
This is particularly handy when using margins to estimates
predictions that you want 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 be created from the rows.
If the matrix has equation names, refer to columns by their number rather than
their name.

Viewing and saving collect_matrix

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, statsto2, list decimal(3 2).

format(string) Indicate the format to use for each
column when listing the matrix.
For example, statsto2, 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
statsto2 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(missing_value) By default blank cells in the matrix
are filled with the missing value .z which is displayed as a blank.
To use other missing values, use mv().
For example, mv(.m).

Global with list of matrices

Each matrix you work with using statsto2 is saved to a global
macro statsto2_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: The collect web page with examples

Online help: statout
graphsto
graphout
matrix
mata

To do, questions, pending bugs

1. Is it possible to have rows() conflicts when adding scalars and eb() rb()'s?
2012-05-27 jsl

2. Does rows work with at()? 2012-05-27

3. unstack needs explanation. 2012-05-27

unstack When using eb() and rb(),
equations from multiple-equation models are placed in separate columns.

4. Equations: This needs to be added, I think... 2012-05-27 jsl

coleq(string) Adds a single equation name to each incoming column or
specifies and renames multiple column equations. For example, statsto2, eb(b p) coleq("Model 1") will add "Model 1" above columns "b" and "p." If you would like to rename an equation but still collect all equations in return, add _all.

roweq(string) Adds a single equation name to each incoming row or
specifies and renames multple row equations. For example, statsto2, eb(b p) roweq("Model 1") will add "Model 1" beside all incoming rows associated with the specified returns. If you would like to rename an equation but still collect all equations in return, add _all

coleq(string) Adds or specifies and renames equations for each incoming column. To rename an equation while still adding all available equations, simply specify _all in option.

roweq(string) Adds or specifies and renames equations for each incoming row. To rename an equation while still adding all available equations, simply specify _all in option.