*! version 1.0.1 23aug2014
help tbl2frmt

Title

tbl2frmt - Convert the output of Stata's table command to a MS Word or TeX file

Syntax

tbl2frmt
varlist
[using filename]
[if] [in]
,
row(varname)
[stat(string) options]

Description

This command, tbl2frmt, bridges the gap between Stata's table and
Luke Gallop's frmttable. For a subset of the tables that Stata's
table command can produce, tbl2frmt sends the resulting table
directly to a MS Word or TeX file.

Stata's table command is a powerful table creator,
with options to define super-rows and super-columns,
but it does not write its output to a MS Word or TeX file for use in
published documents. Nor does it save its results as Stata matrices.
Gallop's frmttable command is a powerful tool for formatting
Stata matrices as publication-ready tables and writing them to
MS Word or TeX files. This command connects table to
frmttable by first executing a specified table command
and then constructing the approriate
Stata matrices and feeding them as input to Gallop's frmttable.

This program first executes Stata's -table- command with the syntax:

table row , by(superow) contents(stat var1 stat var2 ... stat varN)

where var1 ... varN are the variables in varlist and designate the
columns of the table. The output of the table command is
normally suppressed by default, but can be
displayed in the results window with the showtables option.

Options categories description

table options
options to control Stata's table command

frmttable options
options to control Gallop's frmttable command

examples
examples of the execution of tbl2frmt

table options

varlist variables whose summary statistics will appear as the contents
of the tables cells.

The named variables are the ones that would be specified in the
contents(clist)
option of Stata's table command.

row(varname) The variable whose categories define the rows
of the table. Required

superrow(varname) The variable whose categories define the super
rows of the table. Optional

supercol(varname) The variable whose categories define the super
columns of the table. Optional

stat(string) statistics to appear in cells of the table.

This option specifies the summary statistics that will be computed of the variables
in varlist and appear as the contents of the cells of the table.
The user can specify any of the statistics that are available to
table's contents(clist)
option. The default is a table of means.

showtables Display the output of the table command in the results window. Optional

frmttable options

using filename Passed through to frmttbl as the name
of the Word or Tex file to be saved

replace Required if the Word or Tex file specified by using filename
is to be overwritten.

addtable Specifies that the created table is to
be added to a pre-existing MS Word or TeX file. Not specified with the replace option.

tex write a TeX file instead of the default Word file

title(textcolumn) a title to appear above the 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

substat(#) is zero by default.
If the user sets this option to 1, each cell of the table will contain
two stacked summary statistics instead of only one. The second statistic will
be the summary statistic for the second variable in varlist.
Values of this option greater than 1 are not supported by tbl2frmt.

sdec This option specifies the number
of decimals in each cell entry and is passed through to frmttable.

landscape MS Word or Tex table created in landscape
layout. Default is portrait layout.

hlines horizontal lines between rows.

hlstyle Change the style of horizontal lines.

nocenter The table written to a file in MS Word or TeX format
is left justified on the page and its title and notes are also left justified. This
option has no effect on the table's display in the Stata results window or in the Stata log.

coljust(cjstring[;cjstring ...])}
column justification: left, center, right, or decimal.
Applies only to the body of the table, not to the text sections,
such as the title above the table or the notes below it.
Passed through to frmttable.

Examples

Example 1: A table of a single variable

The basic role of tbl2frmt is to create a table using Stata's table
command and write it to a file as a Word table or a TeX table.

To see the
utility of tbl2frmt, consider a data file which includes the two categorical
variables nscen and scen. Suppose that for a given discount rate (of 3%)
and the "central" assumptions, there is one value in the file for each
combination of these variables. Using the tab command, we can see the
12 combinations in the data.

. tab nscen nsub if central & drate==3

| Sub-scenario
Scenario | SQ PE UE | Total
-----------+---------------------------------+----------
CG | 1 0 1 | 2
UTT | 1 0 1 | 2
500 | 1 0 1 | 2
DC | 1 1 1 | 3
PW | 1 1 1 | 3
-----------+---------------------------------+----------
Total | 5 2 5 | 12

Suppose we would like to tabulate the value of another variable, here CE_newhiv,
according to the categorical variables. Using tab, we see the values.

. tab nscen nsub if central & drate==3, sum(CE_newhiv) mean

Means of Incremental cost per incremental HIV infection averted

| Sub-scenario
Scenario | SQ PE UE | Total
-----------+---------------------------------+----------
CG | . . 6,884.9 | 6,884.9
UTT | 2,091.8 . 4,690.4 | 3,391.1
500 | 2,225.0 . 4,938.7 | 3,581.9
DC | -55,316.8 5,924.2 6,100.6 | -14,430.6
PW | 1,272.7 1,505.6 6,357.9 | 3,045.4
-----------+---------------------------------+----------
Total | -12,431.8 3,714.9 5,794.5 | -1,211.4

Since the subscenarios are nested within the scenarios,
Stata's table command produces a more attractive and informative
version of this table:

. table nsub if central & drate==3, by(nscen) contents(mean CE_newhiv)

--------------------------
Scenario |
and |
Sub-scena |
rio | mean(CE_new~v)
----------+---------------
CG |
SQ |
PE |
UE | 6,884.9
----------+---------------
UTT |
SQ | 2,091.8
PE |
UE | 4,690.4
----------+---------------
500 |
SQ | 2,225.0
PE |
UE | 4,938.7
----------+---------------
DC |
SQ | -55,316.8
PE | 5,924.2
UE | 6,100.6
----------+---------------
PW |
SQ | 1,272.7
PE | 1,505.6
UE | 6,357.9
--------------------------

The above table would be suitable for publication, but unfortunately the
results of Stata's table command are not easily output as a MS Word
or TeX document. Using the following syntax, the tbl2frmt command
converts this table to a MS Word or TeX table with the addition of column titles:

. tbl2frmt CE_newhiv if central & drate==3, row(nsub) superrow(nscen) ctitles("Scenario" "r = 3%")

which produces a MS Word or TeX table formatted as follows:

-----------------------
Scenario r = 3%
=======================
CG
CG:SQ
CG:UE 6,884.9
-----------------------
UTT
UTT:SQ 2,091.8
UTT:UE 4,690.4
-----------------------
500
500:SQ 2,225.0
500:UE 4,938.7
-----------------------
DC
DC:SQ -55,316.8
DC:PE 5,924.2
DC:UE 6,100.6
-----------------------
PW
PW:SQ 1,272.7
PW:PE 1,505.6
PW:UE 6,357.9
-----------------------

Example 2: A table containing multiple variables

Now to see a more complex example, suppose the variables narta16, nartc16,
narta33, nartc33 are
defined as the number of adults/children on antiretorviral therapy in the
years 2016 and 2033. Suppose that the data contains two categorical variables,
nscen and nsub, which designate the scenario and the subscenario. Then
Stata's table command can create a table of the mean values for each of
these four variables over these categories with the command:

. table nsub if central & drate==3, by(nscen) contents(mean narta16 mean nartc16 mean narta33 mean nartc33 )

----------------------------------------------------------------------
Scenario |
and |
Sub-scena |
rio | mean(narta16) mean(nartc16) mean(narta33) mean(nartc33)
----------+-----------------------------------------------------------
CG |
SQ | 2,401,552.5 202,067.1 3,402,878.5 135,423.6
PE |
UE | 3,724,236.5 236,470.7 5,266,076.5 103,788.5
----------+-----------------------------------------------------------
UTT |
SQ | 2,770,414.0 201,347.3 3,613,720.3 99,466.9
PE |
UE | 4,431,985.5 226,155.2 4,947,584.0 52,650.8
----------+-----------------------------------------------------------
500 |
SQ | 2,697,172.8 201,569.7 3,591,006.0 107,836.6
PE |
UE | 4,375,440.5 228,299.3 4,998,932.5 57,649.1
----------+-----------------------------------------------------------
DC |
SQ | 2,386,997.8 204,281.0 3,391,194.3 136,637.8
PE | 3,309,333.3 199,201.1 4,879,991.5 81,912.5
UE | 3,868,680.0 234,240.3 5,137,060.0 82,751.3
----------+-----------------------------------------------------------
PW |
SQ | 2,441,042.3 201,883.5 3,413,530.0 125,253.2
PE | 2,508,171.5 199,617.3 3,466,497.0 109,444.6
UE | 3,789,506.8 229,647.6 5,213,924.5 77,724.7
----------------------------------------------------------------------

The following tbl2frmt command writes to disc a fully labeled and annotated
version of the same table in either the MS Word or the TeX document file format.

*	Select values to appear in the annotations
. local drate = 3
. local e_u 0.1
. local e_r 0.5
. local kmax 6000
. local extstr "Quadratic"
. local sigma 0.8

. tbl2frmt narta16 nartc16 narta33 nartc33 using TasP_tables if central & drate==`drate', ///
replace row(nsub) superrow(nscen) sdec(0) ///
ctitles(" " "Adults on" "Children on" "Adults on" "Children on" ///
\ " " "ART by" "ART by" "ART by" "ART by" ///
\ "Scenario" " mid-2016" " mid-2016" " mid-2033" " mid-2033") ///
rtitles( ///
"Current Guidelines:" \ " Status quo (SQ)" \ " Uniform expansion (UE)" ///
\ "Universal test and treat (UTT):" \ " Status quo (SQ)" \ " Uniform expansion (UE)" ///
\ "Eligibility < 500 (500):" \ " Status quo (SQ)" \ " Uniform expansion (UE)" ///
\ "Discordant couples (DC):" \ " Status quo (SQ)" \ " Prioritised expansion" \ " Uniform expansion (UE)" ///
\ "Pregnant women:" \ " Status quo (SQ)" \ " Prioritised expansion" \ " Uniform expansion (UE)" ///
) ///
note("Note: Supply side: Sigma = `sigma', Kmax = `kmax', Scale-up pattern = `extstr'" ///
"	Demand elasticities: Urban = `e_u', Rural = `e_r' ") ///
title("Table 4. Number of patients on ART by scenario")

Example 3: Use of the substat option to stack two variables in one cell

Each variable provided to table generates its own column
of summary statistics. But sometimes one would prefer to stack the summary
statistics for two different variables in the same cell.
With the substat option, tbl2frmt will stack the summary statistics
for two variables in a single cell as follows:

. tbl2frmt CE_dalys CE_newhiv if central & drate==3, row(nsub) superrow(nscen) ///
ctitles("Scenario" "Benefit" "r = 3%") substat(1)

-----------------------------------
Scenario Benefit r = 3%
===================================
CG
CG:SQ CE_dalys
CE_newhiv
CG:UE CE_dalys 897.36
CE_newhiv 6,884.86
-----------------------------------
UTT
UTT:SQ CE_dalys 577.53
CE_newhiv 2,091.78
UTT:UE CE_dalys 771.42
CE_newhiv 4,690.39
-----------------------------------
500
500:SQ CE_dalys 535.04
CE_newhiv 2,225.01
500:UE CE_dalys 790.87
CE_newhiv 4,938.71
-----------------------------------
DC
DC:SQ CE_dalys 184.50
CE_newhiv -55,316.75
DC:PE CE_dalys 747.06
CE_newhiv 5,924.23
DC:UE CE_dalys 876.33
CE_newhiv 6,100.58
-----------------------------------
PW
PW:SQ CE_dalys 631.32
CE_newhiv 1,272.70
PW:PE CE_dalys 438.29
CE_newhiv 1,505.64
PW:UE CE_dalys 873.68
CE_newhiv 6,357.93
-----------------------------------

Author

Mead Over, Center for Global Development, USA
mover@CGDev.org

Also see

frmttable, outreg, outtable,
bivariate,
xml_tab