*! version 1.2 03dec2012
help frmttable

Title

frmttable - A programmer's command to write formatted Word or TeX tables from a matrix of statistics

Syntax

frmttable
[using filename]
[, statmat(string) options]

Description

frmttable is a programmer's command that takes a Stata matrix of statistics and creates a fully-formatted Word or TeX table which can be written to a file.

The frmttable command normally either uses the statmat option with the name of a Stata matrix of statistics to be displayed, or the replay option,
which causes the existing table in memory to be redisplayed, and possibly written to disk.

frmttable makes available the capability to format Word or TeX tables of statistics in myriad ways without the programmer having to write the code necessary to do the formatting.
The programmer just needs to write code that calculates statistics, and can leave the formatting chores to frmttable.

Writing formatted tables directly to word processing files can save researchers a great deal of time.
What researcher has not found that they need to modify their sample in some way after they have already prepared the tables in their research paper?
frmttable provides the means to automatically create fully formatted tables within Stata, saving researchers laborious minutes or hours of manual reformatting each time they make modifications.
Automatically formatted tables save time principally because researchers usually tweak their tables many times before they are ready in their final form.

frmttable gives the user as complete control of the final document as possible.
Almost every aspect of the table's structure and formatting can be specified with options.
Users can change fonts at the table cell level, as well as cell spacing and horizontal and vertical lines.
frmttable can add various text around the table, including titles, notes below the table, and paragraphs of text above and below.
Footnotes or other text can be interspersed within the statistics.

frmttable is the main code behind the outreg command, which creates flexible tables of estimation results.

If a using filename is specified, frmttable will create a Microsoft Word file, or a TeX file using the tex option.
The table created by frmttable is displayed in the Results window (minus the fancy fonts) unless the nodisplay option is employed.

Successive sets of statistics can be merged or appended by frmttable into a single table.
Additional tables can be written to the same file using the addtable option, with paragraphs of text in between.
This makes it possible to create a .do file which writes an entire statistical appendix in final form to a single Word or TeX file, with no subsequent editing required.

frmttable converts the Stata matrix of statistics in statmat, along with various text additions like titles, into a Mata struct of string matrices which persists in memory.
The persistent table data can be reused to merge or append new results, or written to a Word or TeX file with new formatting directives.
The persistent frmttable data can be assigned names, so that multiple tables can be manipulated simultaneously.

This help file provides many examples of frmttable in use below the description of the options.

Options categories description

statistics
statistics and numerical formatting

text additions
titles, notes, added rows & columns

text formatting:

column formatting
column widths, justification, etc.

fonts
font specifications for table

lines & spaces
horizontal and vertical lines, cell spacing

file & display options
tex files, merge, replace, etc.

brackets options
change brackets around, e.g., t stats

Inline text formatting: superscripts, italics, Greek characters, etc.

Examples of frmttable in use

statistics Description

statmat(Stata matrix name) matrix of statistics for body of table

substat(#) number of substatistics to place below first statistics

doubles(Stata matrix name) matrix indicating double statistics

sdec(numgrid) decimal places for all statistics

sfmt(fmtgrid) numerical format for all statistics

eq_merge merge multi-equation statistics into multiple columns

noblankrows drop blank rows in table

findconst put _cons in separate section of table

text additions Description

varlabels use variable labels as rtitles

title(textcolumn) put title above table

ctitles(textgrid) headings at top of columns

rtitles(textgrid) headings to the left of each row

note(textcolumn) put note below table

pretext(textcolumn) regular text placed before the table

posttext(textcolumn) regular text placed after the table

nocoltitl no column titles

norowtitl no row titles

addrows(textgrid) add rows at bottom of table

addrtc(#) number of rtitles columns in addrows

addcols(textgrid) add columns to right of table

annotate(Stata matrix name) grid of annotation locations

asymbol(textrow) symbols for annotations

column formatting Description

colwidth(numlist)* change column widths

multicol(numtriple[;numtriple ...]) have column titles span multiple columns

coljust(cjstring[;cjstring ...]) column justification: left, center, right, or decimal

nocenter Don't center table within page

* Word-only option

font specification Description

basefont(fontlist) change the base font for all text

titlfont(fontcolumn) change font for table title

ctitlfont(fontgrid[;fontgrid...]) change font for column titles

rtitlfont(fontgrid[;fontgrid...]) change font for row titles

statfont(fontgrid[;fontgrid...]) change font for statistics in body of table

notefont(fontcolumn) change font for notes below table

addfont(fontname)* add a new font type

plain plain text - one font size, no justification

table sections explanation of formatted table sections

* Word-only option

border lines and spacing Description

hlines(linestring) horizontal lines between rows

vlines(linestring) vertical lines between columns

hlstyle(lstylelist)* change style of horizontal lines (e.g. double, dashed)

vlstyle(lstylelist)* change style of vertical lines (e.g. double, dashed)

spacebef(spacestring) put space above cell contents.

spaceaft(spacestring) put space below cell contents.

spaceht(#) change size of spacebef & spaceaft.

* Word-only option

page formatting Description

landscape pages in landscape orientation

a4 A4 size paper (instead of 8 1/2” x 11”)

file and display options Description

tex write a TeX file instead of the default Word file

merge[(tblname)] merge as new columns to existing table

replace replace existing file

addtable write a new table below an existing table

append[(tblname)] append as new rows below an existing table

replay[(tblname)] write preexisting table

store(tblname) store table with name "tblname"

clear[(tblname)] clear existing table from memory

fragment** create TeX code fragment to insert into TeX document

nodisplay don't display table in results window

dwide display all columns however wide

** TeX-only option

brackets options Description

squarebrack square brackets instead of parentheses

brackets(textpair [ \ textpair ...]) symbols with which to bracket substatistics

nobrket put no brackets on substatistics

dbldiv(text) symbol dividing double statistics ("-")

Statistics and numerical formatting

statmat(Stata matrix name) names the Stata matrix containing the statistics making up the body of the table.

If the user has filled matrix rownames or colnames for the Stata matrix, they become the row titles and column titles of the table
(unless the rtitles or ctitles options are specified).
If the rownames and colnames of the statmat matrix are varnames, the option varlabels will replace the variable names with their variable labels, if they exist.

See an application of statmat in Example 1.

doubles(Stata matrix name) names the Stata matrix indicating which statistics are "double statistics".
Double statistics are statistics made up of two numbers like confidence intervals or minimum-maximum ranges.
The doubles option allows the lower and upper numbers to be placed in different columns of the statmat, to be combined in the formatted table.

The doubles matrix is a row vector with as many elements as columns in statmat.
A 0 specifies that the column is not a second double statistic, and a 1 indicates that it is.
Thus if statmat consists of a matrix with columns containing the means, lower confidence bounds, and upper confidence bounds, of some variables,
a doubles matrix of (0,0,1) would cause the lower and upper confidence bounds to be combined into a single confidence interval.
The default symbol to separate the lower and upper statistic of double statistics is a dash, but this can be changed with the dbldiv option.

sdec(numgrid) specifies the decimal places for the statistics in statmat.
The sdec numgrid correponds to the decimal places for each of the statistics in the table. The default number of decimal places is 3.

The numgrid can be a single integer applying to the whole table, or it can be a grid of integers specifying the decimal places for each cell in the table individually.
A numgrid is a grid of intergers 0-15 in the form used by matrix define.
Commas separate elements along a row, and backslashes ("\") separate rows: numgrid has the form (#[,#...] [\ #[,#...] [...]]).
For example, if the table of statistics has three rows and two columns, the sdec(numgrid) could be sdec(1,2 \ 2,2 \ 1,3). If you specify a grid smaller than the table of statistics,
the last rows and columns of the sdec numgrid will be repeated to cover the whole table.
So for a 3 by 2 statmat, sdec(1 \ 2) would have the same effect as sdec(1,1 \ 2,2 \ 2,2).
Unbalanced rows or columns will not cause an error.
They will be filled in, and frmttable will display a warning message.

sfmt(fmtgrid) specifies the numerical format for statistics in statmat.
The sdec fmtgrid is a grid of the format types (e, f, g, fc, or gc) for each statistic in the table.
The fmtgrid can be a single format applying to the whole table, or it can specify formats for each cell in the table individually.

A fmtgrid is fmt[,fmt...] [\ fmt[,fmt...] ...]] where fmt is either e, f, fc, g, or gc:

fmt code format type

e exponential (scientific) notation

f fixed number of decimals

fc fixed with commas for thousands, etc. - the default

g "general" format (see format)

gc "general" format with commas for thousands, etc.

The "g" formats are not likely to be useful for frmttable tables because they do not allow the user to control the number of decimal places displayed.

If the fmtgrid has dimensions smaller or bigger than the statmat matrix,
the fmtgrid is adjusted just as the numgrid is for sdec.

substat(#)} indicates the number of "sub"-statistics to be placed in separate rows below the principal statistic.
For example, if the statmat matrix has 3 rows and 4 columns, a substat(1) option would interlace the statistics in statmat column 2 below those of column 1,
and statistics in column 4 below those of column 3, resulting in a final table with six rows and two statistics columns.
This allows the programmer to create a statmat with sub-statistics in separate columns from the principal statistics and rely on frmttable
to interlace them (such as t statistics below regression coefficients or standard deviations below means).

See applications of substat in Example 4 and Example 5.

eq_merge merges the columns of a multi-equation statmat matrix into multiple columns,
one column per equation.
This option is used by outreg, for example, to put the coefficients of each sureg equation side by side instead of stacked vertically.
The equation statistics are merged as if each of the equations was sequentially combined with the merge option.

frmttable identifies the equations in statmat by roweq names.
All rows of stamat with the same roweq name is considered to be an equation.
If no roweqs are assigned, frmttable takes all rows to belong to the same (unnamed) equation.
eq_merge is an option whose main purpose is to help outreg reorganize multi-equation estimation results.

noblankrows deletes completely blank rows in the body of the formatted table.
A blank row is one where the data are missing in every column.

findcons finds table rows with a row title of "_cons" and assigns them to a separate row section which is kept below the other row sections.
This option is useful for merging statistical results like regression coefficients,
where you want to ensure that the constant coefficient estimates are reported below all other coefficients even when the user merges additional statistics containing new variables.

This option is rarely used.

Examples

1. Basic usage.
2. Merge and append.
3. Multi-column titles, border lines, fonts.
4. Add stars for significance to regression output: substatistics and annotate.
5. Make a table of summary statistics & merge it with a regression table.
6. Create complex tables using merge and append.
7. Double statistics.

Example 1: basic usage

The basic role of frmttable is to take statistics in a Stata matrix and organize them in a table
that is displayed in the Results window and can be written to a file as a Word table or a TeX table.

First, we create a 2x2 Stata matrix named A:

. mat A = (100,50\0,50)
. mat list A

A[2,2]
c1 c2
r1 100 50
r2 0 50

The simplest usage of the frmttable command is to display the matrix A:

. frmttable, statmat(A)

100.00 50.00
0.00 50.00

This doesn't get us very far.
The reason frmttable is useful is that it can make extensive adjustments to the formatting of the table, and write the result to a Word or TeX document.

The frmttable command below has a using statement followed by a file name ("xmpl1").
This causes the table to be written to a Word document "xmpl1.doc".
Word documents are the default; the table would be written as a TeX document with the tex option.

The frmttable statement below adds a number of options.
The first, sdec, sets the number of decimal places displayed for the statistics in statmat to 0.
The next three options, title, ctitle, and rtitle add an overall title to the table, titles above each column of the table, and titles on the left of each row of the table, respectively.
The column and row titles are designated with the syntax used for matrices: commas separate columns, and backslashes separate rows.

. frmttable using xmpl1, statmat(A) sdec(0) title("Payoffs") ///
ctitle("","Game 1","Game 2") rtitle("Player 1"\"Player 2")

Payoffs

Game 1 Game 2

Player 1 100 50
Player 2 0 50

Example 2: merge and append

Once frmttable is run, the table created stays in memory (as a struct of Mata string matrices).
Subsequent statistical results can be merged as new columns of the table or appended as new rows.
The merged columns are arranged so that the new row titles are matched with the existing table's row titles,
and rows with unmatched titles are placed below the other statistics (similar to the way the Stata merge command matches observations of the merged dataset).

The frmttable command below merges a new column of statistics for players 1 and 3 to the existing frmttable table, already created in the previous example.

. mat B = (25\75)

. frmttable, statmat(B) sdec(0) ///
ctitle("","Game 3") rtitle("Player 1"\"Player 3") merge

Payoffs

Game 1 Game 2 Game 3

Player 1 100 50 25
Player 2 0 50
Player 3 75

In this case, the new statistics in matrix B are arranged according to the row titles in the rtitle option.
The statistics in the first row of B for "Player 1" are lined up with the statistics for "Player 1" in the existing table, while the statistics for "Player 3" are placed below "Player 2" because "Player 3" is a new row title.

The text of the row titles must match exactly for the merged results to be placed in the same row.
Row titles of "Player 1" and "player 1" do not match, so they would be placed in different rows.

Next we add another column to the table for new game results.

. mat C = (90\10)

. frmttable, statmat(C) sdec(0) ///
ctitle("","Game 4") rtitle("Player 2"\"Player 4") merge

Payoffs

Game 1 Game 2 Game 3 Game 4

Player 1 100 50 25
Player 2 0 50 90
Player 3 75
Player 4 10

The statistics for "Player 2" and "Player 4" are merged: the statistics for "Player 2" are lined up with previous results for "Player 2" and statistics for the new row title, "Player 4", are placed below the other rows.

Finally, we append new rows to the table, for the total payoffs.

. mat D = (100,100,100,100)

. frmttable, statmat(D) sdec(0) rtitle("Total") append

Payoffs

Game 1 Game 2 Game 3 Game 4

Player 1 100 50 25
Player 2 0 50 90
Player 3 75
Player 4 10
Total 100 100 100 100

Whereas the merge option created new table columns, the append option places new statistics in rows below the existing table.
If the matrix D had had more or less than 4 columns, it would still be appended below the existing results, but with a warning message.
The arrangement of the appended results does not depend on the column titles (unlike the way merge depends on the row titles).
In fact, the ctitles of the appended data are ignored if they are specified.

An alternative way of adding rows and columns is with the options addrows and addcols.
merge and append add matrices of numbers to a previously created table; addrow and addcol add on rows and columns of text (which can include numbers) to the table currently being created.

The following set of commands will create the same table as above, but uses the addrows option to attach the column totals as text instead of appending a Stata matrix:

. mat E = (100,50,25,. \ 0,50,.,90 \ .,.,75,. \ .,.,.,10)

. frmttable, statmat(E) sdec(0) addrows("Total", "100", "100", "100", "100") ///
rtitles("Player 1" \ "Player 2" \ "Player 3" \ "Player 4")	///
ctitles("", "Game 1", "Game 2", "Game 3", "Game 4") ///
title("Payoffs")

Payoffs

Game 1 Game 2 Game 3 Game 4

Player 1 100 50 25
Player 2 0 50 90
Player 3 75
Player 4 10
Total 100 100 100 100

Example 3: multi-column titles, border lines, fonts

Many formatting options are available in frmttable.
This example makes some of the column titles span multiple columns, places a vertical line in the table, and changes the font size and typeface.

frmttable can change many other aspects of the tables it creates, such as footnotes and other annotations among the statistics, justification of columns, and spacing above and below table cells.
You can find additional information of several frmttable formatting options in examples of the outreg command related to fonts,
special characters, multiple tables in the same document, and footnotes.

In the Stata code below, the frmttable table is created from data in the matrix F.
Where F contains missing values, the table cells will be blank.

The table's column titles in the ctitles option have two rows and the first row of titles are meant to span two columns each.
They are made to span multiple columns with the multicol(1,2,2;1,4,2) option.
The two triples of numbers, 1,2,2 and 1,4,2, indicate which table cells span more than one column.
1,2,2 indicates that the first row, second column of the table should span two columns, and the 1,4,2 indicates that the first row, fourth column of the table should span two columns.

A dashed vertical line is placed in the table separating the row titles from the statistics.
The vlines(010) option where the vertical line or lines are placed.
A 0 indicates no line, and a 1 indicates a line.
The 010 means no line to the left of the first cell (or column), a vertical line between the first and second cell and no line between the second the third cell.
Since the table has more than two columns, the "no line" specification is extended to all the rest of the columns.
The vlstyle(a) option changes the line style from the default of a solid line to a dashed line.

The last option, basefont(arial fs10), changes the font of the Word table to be Arial font, with a base font size of 10 points (the table's title has larger text and the notes have smaller text).

. mat F = (100,50,25,. \ 0,50,.,90 \ .,.,75,. \ .,.,.,10 \ 100,100,100,100)

. frmttable using xmpl3, statmat(F) sdec(0) title("Payoffs") replace ///
ctitles("", "{\ul Day 1}", "", "{\ul Day 2}" ,"" \ ///
"", "Game 1", "Game 2", "Game 3", "Game 4") ///
multicol(1,2,2;1,4,2) ///
rtitles("Player 1" \ "Player 2" \ "Player 3" \ "Player 4" \ "Total") ///
vlines(010) vlstyle(a) basefont(arial fs10)
(output omitted)

The table created in this example is not shown because most of its features (font, vertical lines, etc.) appear correctly only in the Word table created, not in the Stata Results window.

Example 4: Add stars for significance to regression output: substatistics and annotate

The following Stata commands create a matrix, b_se, containing regression coefficients in the first column and standard errors of estimates in the second column:

. sysuse auto, clear
. regress mpg length weight headroom
(output omitted)

. matrix b_se = get(_b)', vecdiag(cholesky(diag(vecdiag(get(VCE)))))'
. matrix colnames b_se = mpg mpg_se
. mat li b_se

b_se[4,2]
mpg mpg_se
length -.07849725 .05699153
weight -.00385412 .00159743
headroom -.05143046 .55543717
_cons 47.840789 6.1492834

frmttable will then convert this matrix into a formatted table.
The substat(1) option informs frmttable that the second column of statistics, the standard errors, should be place below the first column of statistics, the coefficients, in the table.
If the option had been substat(2), the second and third columns of statistics would be interweaved below the statistics in the first column of statmat.

In the absence of rtitles and ctitles, frmttable uses the matrix rownames and colnames of b_se as the row and column titles for the table.

. frmttable, statmat(b_se) substat(1) sdec(3)

mpg

length -0.078
(0.057)
weight -0.004
(0.002)
headroom -0.051
(0.555)
_cons 47.841
(6.149)

Stars indicating significance levels can be placed next to the standard errors using the annotate option.
First it is necessary to create a Stata matrix indicating the cells to which the stars should be added.
The matrix, named stars below, has a 1 in the second row, second column, and a 2 in the fourth row, second column, since the second and fourth coefficients are statistically significant.

. local bc = rowsof(b_se)
. matrix stars = J(`bc',2,0)
. forvalues k = 1/`bc' {
. matrix stars[`k',2] = ///
(abs(b_se[`k',1]/b_se[`k',2]) > invttail(`e(df_r)',0.05/2)) + ///
(abs(b_se[`k',1]/b_se[`k',2]) > invttail(`e(df_r)',0.01/2))
. }
. mat list stars

stars[4,2]
c1 c2
r1 0 0
r2 0 1
r3 0 0
r4 0 2

The entries of 1 and 2 in stars correspond to the first and second entry of the asymbol(*,**) option, adding a single star to the cell where the 1 is, and a double star in the cell where the 2 is.
All the elements in stars equal to 0 will have no symbols added.
The dimensions of stars (4x2) corresponds to the dimensions of the statmat matrix, not the dimensions of the statistics in the final table (8x1),
which has a single statistics column due to the substat(1) option.

The option varlabels causes the variable labels for the variables mpg, length, weight, and headroom to be substituted for their names.

. frmttable using xmpl4, statmat(b_se) substat(1) sdec(3) ///
annotate(stars) asymbol(*,**) varlabels

Mileage (mpg)

Length (in.) -0.078
(0.057)
Weight (lbs.) -0.004
(0.002)*
Headroom (in.) -0.051
(0.555)
Constant 47.841
(6.149)**

The code above implements the most basic capabilities of outreg, so the same table can more easily be created by

. outreg, se varlabels

Example 5: make a table of summary statistics & merge it with a regression table

First we create a Stata matrix containing summary statistics for four variables, length, weight, headroom, mpg.
The first column of the matrix mean_sd contains the means and the second column contains the standard deviations.
The statistics are calculated by the summarize command, looping over the variables using the foreach command.

. mat mean_sd = J(4,2,.)
. local i = 1
. foreach v in length weight headroom mpg {
. summarize `v'
. mat mean_sd[`i',1] = r(mean)
. mat mean_sd[`i',2] = r(sd)
. local i = `i' + 1
. }
(output omitted)

. matrix rownames mean_sd = length weight headroom mpg
. matrix list mean_sd

mean_sd[4,2]
c1 c2
length 187.93243 22.26634
weight 3019.4595 777.19357
headroom 2.9932432 .84599477
mpg 21.297297 5.7855032

We can create a formatted table with this matrix of statistics, and we can also merge these statistics into any other table created by frmttable (or by commands which call frmttable, like outreg).
The command below merges the summary statistics with the table of regression coefficients created in the previous example.

. frmttable, statmat(mean_sd) substat(1) varlabels ///
ctitles("", Summary statistics) merge
(note: tables being merged have different numbers of row sections)

A Regression

Mileage (mpg) Summary statistics

Length (in.) -0.078 187.93
(0.057) (22.27)
Weight (lbs.) -0.004 3,019.46
(0.002)* (777.19)
Headroom (in.) -0.051 2.99
(0.555) (0.85)
Mileage (mpg) 21.30
(5.79)
Constant 47.841
(6.149)**
R2 0.66
N 74

* p<0.05; ** p<0.01

This example shows how frmttable works, but a user can already create a table similar to this with the following commands:

. regress mpg length weight headroom
. outreg, se varlabels
. mean length weight headroom mpg
. outreg, se varlabels merge

Example 6: create complex tables using merge and append

If you use frmttable to handle the output from a new command you write, users of your command can build quite complex tables by repeatedly executing your command,
along with frmttable's merge and append options.
In this exercise we use outreg as an example of a frmttable-based command to build a table from parts.

Say we wanted to create a table showing how a car's weight affects its mileage. We want the table to be broken down by foreign vs. domestic cars, and by three categories of headroom.
It is easy with a frmttable-based command like outreg to create six separate tables with all of these results.
It is also easy to create a single table with six columns (or six rows) of coefficients using straightforward application of the merge (or append) options.

It is more complicated to create a table with three columns of foreign estimates above three columns of domestic estimates.
The results for foreign cars must be merged across the headroom categories into one table, and the results for the domestic cars merged into a separate table. The two tables must then be appended one below the other.
Creating two separate frmttable tables simultaneously requires the use of table names.

The statistics for the table in this example are created in a double foreach loop, iterating first over foreign vs. domestic, and then over three categories of headroom.
Using data from auto.dta, we first recode the variable headroom into a new variable hroom with just 3 levels.

. sysuse auto, clear
(1978 Automobile Data)

. recode headroom (1.5=2) (3.5/5=3), gen(hroom)
(34 differences between headroom and hroom)

Ignore the outreg, clear commands below for the moment:

. outreg, clear(row1)
. outreg, clear(row2)

The heart of the table building occurs with a double foreach loop, iterating over foreign and hroom values.
We estimate the correlation of mpg with weight using the regress command for each category in the double loop.
The formatted table is built up using the outreg, merge command repeatedly.

. foreach f in 0 1 {
foreach h in 2 2.5 3 {
regress mpg weight if foreign==`f' & hroom==`h'
outreg, nocons noautosumm merge(row`f')
}
}
(output omitted)

The outreg command has options nocons to suppress the constant coefficient and noautosumm to suppress the R-squared and number of observations.
The merge(row`f') option is the interesting part.
This merges the coefficients into two separate tables, named row0 and row1, each of which contains three columns of estimates for the categories of hroom.

The first time the merge option is invoked for each table, we want it to create the first column: to merge the results onto a table which doesn't yet exist.
The merge option allows merging onto a non-existent table, for convenience in loops like this.
However, to make this work, it is important to clear out any pre-existing table of the same name.
Particularly, we want to clear out the table from the previous time we ran the same .do file.
Otherwise, the table would get larger and larger each time the .do file is run.
That is the reason for the two outreg, clear commands just before the loop.
An alternative to the outreg, clear command, especially if one needs to clear many frmttable tables, is mata: mata clear which clears all Mata memory structures, including the tables.

Now that the tables for each row are created, we want to append them one below the other.
We do this with a combination of the replay and append options.
The replay(row0) option displays the named table (and can write it to a word processing document if using is specified).
append(row1) option appends the table row1 containing the second row below the row0 results.
The rest of the outreg command below adds titles to the final table.
Note that the combined table now has table name row0.

. outreg, replay(row0) append(row1) replace ///
rtitle(Domestic \ "" \ Foreign) ///
ctitle("", "", "Headroom", "" \ "Origin", "<=2.0", "2.5", ">=3.0") ///
title(Effect of weight on MPG by origin and headroom)

Effect of weight on MPG by origin and headroom

Headroom
Origin <=2.0 2.5 >=3.0

Domestic -0.006 -0.007 -0.005
(3.62)** (7.63)* (8.00)**
Foreign -0.018 -0.008 -0.011
(1.87) (2.14) (2.64)*

This example shows how elaborate tables can be created by combining smaller parts using the merge and append options and table names.
Other useful options for this purpose are addrows and addcols, which add columns of text (which may include numbers) rather than statistics from Stata matrices.

Example 7: double statistics

Double statistics are statistics showing two numbers, such as a minimum-maximum range, or a confidence interval.
frmttable has the doubles option to make it easy to display them.
The lower and upper value of double statistics are held in neighboring columns of statmat, and the doubles option indicates which columns are the second column of a double statistic.
frmttable automatically combines the two numbers into as single cell of the formatted table, with a dash in between them.

The following code creates a Stata matrix conf_int, containing the mean of several variables in the first column, and the lower and upper confidence intervals in the second and third columns, respectively.
The details are similar to Example 5 above.

. mat conf_int = J(4,3,.)
. local i = 1
. foreach v in length weight headroom mpg {
summ `v'
mat conf_int[`i',1] = r(mean)
mat conf_int[`i',2] = r(mean) - invttail(r(N)-1,0.05/2)*sqrt(r(Var)/r(N))
mat conf_int[`i',3] = r(mean) + invttail(r(N)-1,0.05/2)*sqrt(r(Var)/r(N))
local i = `i' + 1
}
(output omitted)

. matrix rownames conf_int = length weight headroom mpg
. mat li conf_int

conf_int[4,3]
c1 c2 c3
length 187.93243 182.77374 193.09113
weight 3019.4595 2839.3983 3199.5206
headroom 2.9932432 2.7972422 3.1892443
mpg 21.297297 19.956905 22.63769

For frmttable to display double statisics, it requires a row vector indicating which columns contain the second numbers of double statistics.
In this example, there are second values of a double statistic in column 3, so the third element of the doubles option matrix dcols is set to 1.
The doubles(dcols) option causes the numbers in the second and third columns of conf_int (the lower and upper confidence limits) to be combined in the final table.

. matrix dcols = (0,0,1)
. frmttable, statmat(conf_int) substat(1) doubles(dcols) varlabels ///
ctitles("",Summary statistics) sdec(0 \ 0 \ 0 \ 0 \ 2 \ 2 \ 1 \ 1)

Summary statistics

Length (in.) 188
(183 - 193)
Weight (lbs.) 3,019
(2,839 - 3,200)
Headroom (in.) 2.99
(2.80 - 3.19)
Mileage (mpg) 21.3
(20.0 - 22.6)

Note that there is only one substatistic in substat(1) since the second statistic is a double statistic.

Confidence intervals have been integrated into the outreg command, making use of frmttable's doubles option, so that the particular table in this example is easily created with the following commands:

. mean length weight headroom mpg
. outreg, stats(b,ci) nostars varlabels ctitles("",Summary statistics) bdec(0 0 2 1)

Author

John Luke Gallup, Portland State University, USA
jlgallup@pdx.edu

Also see

outreg, outtable