help mswtable

Title

mswtable -- Wrapper for putdocx table

Syntax

mswtable , colwidth(string)
[ options
]

Core Options

colwidth(string) width of each column (in inches) (required option)

mat(string) matrix input: identifies matrix

est(string) estimates input: identifies stored equations

est_stat(string) estimates input: requests equation statistics (N, AIC, etc.)

est_star(string) estimates input, coefficient tests: requests asterisks

est_se(string) estimates input, coefficient precision: requests standard error, etc.

sdec(string) number of decimal places, column-specific

font(string) font: type of font, font sizes

title(string) title for table

subtitle(string) subtitle for table

note#(string) notes placed at foot of table (maximum nine)

ct(string) column titles

cst_set(string) column-spanning titles: set font (bold, underline, neither)

cst#(string) column-spanning titles: lower level (maximum ten)

cst1#(string) column-spanning titles: higher level (maximum five)

rt(string) row titles

rst_set(string) row-spanning titles: set font (bold, underline, neither) and indentation

rst#(string) row-spanning titles: text and location (maximum sixteen)

extra#(string) extra information rows (maximum nine), placed below coefficients and statistics

outfile(string) MSWord table: directory where it is to be written

Additional Options

est_means(string) add column of means of right-hand-side variables

est_mat(string) add matrix

est_no(string) equations omitted from coefficient precision (options est_star and est_se)

extra_place reverse placement of rows for est_stat and extra#

tline(string) top line in table: format (bold, double, neither)

bline(string) bottom line in table: format (bold, double, neither)

firstX top row in table: extra space after

lastX bottom row in table: extra space before

slim eliminate rows without information (rows inserted for aesthetics only)

tabname(string) name for putdocx table

Multiple Panels (max 5)

mat#(string) matrix input: identifies matrices panel-by-panel

est#(string) estimates input: identifies stored equations panel-by-panel

est_stat#(string) estimates input: requests equation statistics panel-by-panel

pline draw line separating panels

pt_set(string) panel titles: set font (bold, underline, neither) and justification

pt#(string) panel titles, panel-specific

rt#(string) row titles, panel-specific

rst##(string) row-spanning titles, panel-specific

extra##(string) extra information rows, panel-specific

est_means(string) add means of right-hand-side variables, panel-specific

est_mat(string) add matrices, panel-specific

Description

mswtable is a wrapper for putdocx table. It produces a table in MSWord format.

As input, mswtable requires either:

1. Stata matrix, identified in mat().

2. Equations stored via estimates store, identified in est().

Source #2 can be augmented with:

3. Means of right-hand-side variables (est_means).

4. Matrix of additional values (est_mat).

Option colwidth() is required. And either mat() OR est().

Row and column labels: the default are the row and column names in the input matrix/equations, but these can be replaced (options ct and rt).

mswtable will construct a table with multiple panels (five panels maximum). See discussion below of multi-panel syntax.

The constructed table can be saved as a MSWord table (option outfile).
Alternatively, if outfile is not specified but tabname instead, the
table (as named in tabname) is available for further development and polishing via putdocx table.

mswtable applies the table aesthetics of the author (e.g. line spacing, justification).
Some of this is modifiable, most is not. (Note that option slim eliminates lines that are inserted for visual appearance only.)

Options

core options

colwidth(string) specifies the width of each column, in inches.
This includes column for row titles (first column on left).
colwidth contains an array of numbers (decimals are permitted), separated by comma or space.
colwidth is required.

Examples: colw(1.2,0.8,0.8,1)

colw(1.5 1 1 1 1.2)

mat(string) identifies the input matrix.

est(string) identifies equations that have been stored via estimates store. Separate the names
by comma or space. Note that estimates store can be
applied after margins if the post option is specified in the margins command.

Examples: est(mod1 mod2 mod3 mod4)

est(eq1,eq2,eq3)

est_stat(string) requests equation "statistics" (N, aic, etc).
These are placed at the bottom of the table, following the coefficients.
(Some are renamed, e.g. "r2_a" becomes "Adjusted R-squared". For further renaming, insert at lines 279ff in mswtable.ado. Also, note that statistics names can be included in row titles; see rt below.)

Contents of est_stat are as follows:

(i) name of the statistic (Stata naming convention)

(ii) number of decimal places for the statistic

Separate (i) and (ii) with comma or space. Multiple statistics can be requested - separate with "!".

Examples: est_stat(N,0! r2_a,2! bic,1)

est_stat(N 0! r2_a 2)

est_star(string) requests that asterisks be placed on the regression coefficients.
The asterisks are placed immediately to the right.
"string" is a listing of p-value thresholds (maximum three), separated by comma or space.
They must be listed in descending order.
In the MSWord table, the first p-value will be denoted by one asterisk, the second by two asterisks, and the third by three asterisks.
mswtable does not automatically generate a footnote indicating what the asterisks represent, this must be done manually (e.g. as note1).

Examples: est_star(0.05,0.01,0.001)

est_star(0.10 0.05)

est_se(string) requests inclusion of statistical tests of the regression coefficients.
"string" can contain:

(i) "se" or "t" or "p" or "ci" or "ci()", to request:

"se" standard error

"t" t-statistic (ratio of coefficient to standard error)

"p" p-value for t-statistic (two-sided test)

"ci" confidence interval (95%)

"ci()" confidence interval, with p-value and size of font within parentheses

(ii) "below" or "beside" - place below or immediately to the right of the coefficient

(iii) "paren" or "noparen" - whether enclosed in parentheses (or not). (Confidence intervals are placed in brackets instead of parentheses.)

Separate with comma or space. Any or all of the three items can be specified, in any order.

The defaults are "se", "below", and "paren". est_se without arguments requests the three
defaults. Note that "beside" is incompatible with est_star.

"ci()" is syntax for specifying, within the parentheses, p-value and size of font.
These are numeric values.
If <.50, the value is assumed to be p-value; default is .05.
If larger than 4, the value is assumed to be font size; default is 2.0-point less than body-of-table font.
One or both can be specified; if both, either order is allowed, and separate by comma or space.

Examples: est_se standard error, below, in parentheses

est_se(t beside)

est_se(ci) 95% confidence interval

est_se(ci(.10,11)) 90% confidence interval, font size 11

sdec(string) specifies number of decimal places for each column of data
(i.e. excepting left-hand column of row titles). Decimal places for equation statistics are specified
separately (see est_stat above). sdec(string) contains integers, separated by comma or space.
Every column need not be represented - mswtable will fill in based on the last number specified.
That is, sdec(1) is equivalent to sdec(1,1,1), and sdec(1 1 0) is equivalent to sdec(1 1 0 0 0).
The default is one decimal place.

font(string) identifies the name of the font (must be font available in MSWord) and font sizes.
Current default font is Cambria, with font sizes (in points):

12.5 title

12 subtitle

12 column and row titles

11.5 body of table

10.5 notes

Fonts for statistics (N, aic, etc) and "extra" information are 0.5-point less than body-of-table font; font for
standard errors (including t and p) is 1.0-point less than body-of-table font. These font settings can be modified
at lines 184ff in mswtable.ado.

"string" can take two forms:

(i) name of font only

(ii) name of font and font sizes (in points)

If (ii), then the name of font is specified followed by the five font sizes; all five sizes must be specified
and ordered as shown above. Separate the elements by comma or space. Some font names are multiple words; place these
names within quotation marks.

Examples: font(Garamond,12.5,12,12,12,10.5)

font("Lucida Sans")

font(Arial 12 12 11 10 10)

title(string) adds a title above the table, and subtitle(string) adds
a subtitle (further line under the title). The title (and subtitle) are separated from remainder
of table by one empty line. Place title/subtitle text within quotation marks. Multiple
lines in either title is indicated by using "\" as separator; maximum is two lines. After text,
horizontal justification optionally can be specified as "left", "center" (default), or
"right"; separate this option from title/subtitle text with comma or space.

note1(string) . . . note9(string) adds notes to the foot of the table (maximum is nine).
These should be text in quotes.
A blank line can be inserted by, for example, note3(" "); blank lines are allocated less height.
(Option slim eliminates blank lines.) Notes
are separated from the table by one empty line.

ct(string) are column titles.
Often it is convenient to construct this separately as local macro.
Use "!" to separate elements in this string, and do not embed quotation marks.
Spaces between words in the title are allowed.
Titles are applied column-by-column in sequential order, beginning with the far left column
(column for row titles) and including columns added via est_means or est_mat. Column
titles can be left blank by specifying successive "!" ("!!" or "! !"). Multiple
lines in each column title are indicated by using "\" as separator; maximum is three lines.
If ct is not specified, default is input matrix column names.

Example: ct("`ctitles'")

cst_set(string) formats the font for the column-spanning titles (cst# and cst1#).
Options are "bold", "underline" (default), and "none".

cst1(string) . . . cst10(string) are column titles that span multiple columns.
They are placed in a row above the main column-by-column titles and centered, and by default underlined (see cst_set).
Contents of cst# are as follows, in this order and separated by commas or spaces:

(i) text for title, in quotes

(ii) starting column for spanning title

(iii) number of columns to be spanned

Item(i): multiple lines in the title are indicated by using "\" as separator in the text; maximum is
two lines.

Item(ii): "starting column" refers to the data matrix; columns added for est_means or est_mat
are counted, but row title column (1st column) and columns inserted for est_star or est_se are not
counted.

Examples: cst1("Means" 1 3)

cst2("Demographic\Variables",2,3)

cst11(string) . . . cst15(string) are higher-level column-spanning titles.
These titles are placed above cst1-cst10.
The syntax is identical to cst1-cst10.
cst11-cst15 presume cst1-cst10 has been specified.

rt(string) are row titles. It is
convenient to make "string" a local macro that contains the set of row titles, in order.
The titles for each successive row must be separated by "!", and do not embed quotation marks.
Spaces between words in the title are allowed. Row
titles can be left blank by specifying successive "!" ("!!" or "! !"). Multiple
lines in each row title are indicated by using "\" as separator, maximum two lines. Row
titles can include the requested statistics (conforming to the order in est_stat).
If rt is not specified, default is input matrix row names.

rst_set(string) specifies two optional features of the row spanning titles (see rst#):

(i) format for font: "bold", "underline", "none" (default)

(ii) "indent" the rows encompassed by row spanning title by three spaces; default is no indent

Separate with comma or space.

Example: rst_set(bold,indent)

rst1(string) . . . rst16(string) are row-spanning titles, i.e. titles that apply to multiple
rows. The rows might be, for example, categories of a variable (e.g. for place of residence, "rural" "small city"
"large city"). The row-spanning titles are inserted above the rows to which they apply - text as specified, with
the remainder of the row blank. The spanning title may be bold or underlined, or neither
(default); see rst_set. Each rst# must consist of the following, separated by commas or spaces:

(i) text for title, in quotes (row spanning titles cannot contain multiple lines)

(ii) starting row for spanning title

(iii) number of rows encompassed by spanning title

Note that starting row is without taking into account inserted rows for previous row spanning titles.
Note also that the row spanning title is inserted above the row specified by (ii).
Further note: the rst# must be ordered top to bottom of the table.

Example: rst1("Place of Residence",4,3)

extra1(string) . . . extra9(string) are additional rows of information (maximum nine).
These are added to the foot of the table, following data specified in mat or est
and also following equation statistics (if est_stat is requested) but prior to note.
Each "string" contains column-by-column text, starting with the first column on left (row title column).
Columns inserted for est_means or est_mat are included.
Separate the column entries with "!", and do not embed quotation marks.
Spaces within entries are allowed.
Cells can be left blank by specifying successive "!" ("!!" or "! !").

Examples: extra1(State fixed effects !No !No !Yes !Yes)

extra1(State fixed effects ! ! Yes ! !Yes)

outfile(string) specifies where MSWord table is to be written.
If not specified, then putdocx table remains open (and the table can be referred to as named in tabname).
Full file specification should be provided (exact directory + file name), and within quotes.
"replace" or "append" are options; these follow the file specification (in quotes), with comma or space as separator.
The default is "replace". If "append", each table is started on a new page (putdocx option "pagebreak").
A further option is "landscape"; this requests landscape orientation (portrait orientation is the default).

additional options

est_means(string) requests addition of column of mean values of the right-hand-side variables.
"string" contains two items, in this order and separated by comma or space:

(i) "left" or "right" - whether the column of means is the far left or far right column

(ii) equation name (must be among the equation names in est())

"left" is the default for item (i), which may be omitted.

The following options must account for the est_means column:
colwidth, sdec, ct, cst#, cst1#, extra#

Examples: est_means(eq1)

est_means(right,eq1)

est_mat(string) requests addition of a matrix. This enables one to augment a table of
estimation results with other numerical values. (Requesting both est_means and est_mat
is not allowed.) "string" contains two items, in this order and separated by comma or space:

(i) "left" or "right" - whether the matrix will become the far left or far right columns of the table

(ii) matrix name

"left" is the default for item (i), which may be omitted.
The matrix will be inserted at the top row of the table. It may have fewer rows than the remainder of the table.
And the matrix may contain missing values (".") - mswtable replaces these with " ".

The following options must account for the est_mat columns:
colwidth, sdec, ct, cst#, cst1#, extra#

Examples: est_mat(SUM)

est_mat(right ZZ)

est_no(string) singles out equations for which est_star and est_se are not applied.
"string" is integers, separated by comma or space, specifying columns in the equation matrix:
from the left, the first equation is "1", the second equation is "2", and so forth.
(Columns inserted due to est_means or est_mat are not counted.)
The default is to apply est_star and est_se to all equations.

Example: est_no(4,5)

extra_place reverses the placement of the est_stat and extra# rows.
The default order is est_stat rows followed by extra# rows.

tline(string) and bline(string) control the appearance of the lines:

tline: at the top of table (above column titles but below title and subtitle)

bline: at the bottom of table (immediately before any notes)

Options are "double" (double line) and "bold" (single bold line).
Both options cannot be requested together - must be one or the other.
The default is non-bold single line.

firstX and lastX request insertion of low-height row between:

(i) first data row and next row [firstX]

(ii) last data row and previous row [lastX]

This might be appropriate if, for example, the first or last row is "Total", or
to provide some separation for the intercept.
In multi-panel tables, this request is carried out panel-by-panel.
note: option slim overrides these two options.

slim eliminates rows that contain no information.
These are rows inserted only to improve visual appearance.

tabname(string) gives a name to the table, for putdocx use.
The name can be used post-mswtable if the table is not saved (i.e. no outfile option),
allowing for additions or other enhancements to the table via putdocx table.

Examples

Matrix input
------------

#d ;

local ctitles
"Region !
Mean\DFS !
Mean\IFS !
N\Surveys ! ";

local regions
"East & Southern Africa !
Middle & West Africa !
Latin America & Caribbean !
South & Southeast Asia !
West Asia & North Africa !
Total ";

mswtable, mat(TAB11)
colw(2.1,0.8,0.8,1)
sdec(1,1,0)
title("Table 1. Mean DFS and Mean IFS")
subt("Estimates by Region")
ct("`ctitles'")
cst1("Means",1,2)
rt("`regions'")
lastX
note1("Sample: currently-in-union women ages 15-49")
note2(" ")
note3("DFS = Desired Family Size")
note4("IFS = Ideal Family Size")
outfile("$D/analysis/tab1", replace);

Estimates input
---------------

#d ;

local cols
"Explanatory Variables !
1 !
2 !
3 !
4 !";

local xvars
"Total Fertility Rate !
Contraceptive prevalence !
% births unwanted !
Mean ideal number !
Cure fraction !
East & Southern Africa !
Middle & West Africa !
Latin America & Carib !
South & Southeast Asia !
West Asia & North Africa !
Intercept !
Number of surveys !
R-squared (adjusted) !
BIC";

mswtable, colwidth(2.0,1.0,0.8,0.8,0.8)
est(eq1 eq2 eq3 eq4)
est_stat(N,0! r2_a,2! bic,1)
est_star(.05,.01,.001)
est_se(se,below,paren)
title("Table 2. Modeling DFS")
subtitle("OLS Estimates")
extra1(State fixed effects !No !No !Yes !Yes)
extra2(Ridiculous model !Yes !No !Yes !No)
note1("Significance: * p<.05 ** p<.01 *** p<.001")
sdec(2)
cst("Equations",1,4)
ct("`cols'")
rt("`xvars'")
outfile("$D/analysis/tab2", append);

multiple panels (max 5)

Note that column titles (ct) and decimal points (sdec) cannot be panel-specific - mswtable
assumes these two specifications are fixed across panels.

mat1(string) . . . mat5(string) identifies the input matrices, panel-by-panel.
The suffix indexes the panel.
These are stacked in sequential order, hence all matrices must have the same number of columns.

est1(string) . . . est5(string) identifies the names of equations available via estimates store, panel-by-panel.
See est above.
The suffix indexes the panel. These are stacked in sequential order, hence each panel must contain the same number of equations.

Examples: est1(mod11 mod12 mod13 mod14)

est2(mod21 mod22 mod23 mod24)

est_stat1(string) . . . est_stat5(string) requests equation "statistics" (N, aic, etc), with the suffix indexing the panel.
See est_stat above.
If only est_stat is specified, then the same set of statistics is provided for every panel (these will be panel-specific values).

pline draws single lines separating the panels.
The line is drawn immediately above the panel title (if any).

pt_set(string) formats the panel titles (see pt#):

font: "bold", "underline" (default), "none"

horizontal justification: "left" (default), "center", "right"

Both font and justification can be requested, and both "underline" and "bold". Separate with comma or space.

pt1(string) . . . pt5(string) are text labels for the panels.
The suffix indexes the panel.
Text should be enclosed in quotes.
Multiple lines are allowed, using "\" as separator; maximum is two lines.
In the MSWord table, each panel title is inserted as a separate row, and by default is underlined and
left-justified (see pt_set). Panel titles are optional: titles may be provided for all, some,
or none of the panels.

rt1(string) . . . rt5(string) identify text labels for the rows, with the suffix indexing the panel.
See rt above.

rst11(string) - rst112(string) . . . rst51(string) - rst512(string) are
panel-specific row spanning titles, maximum twelve per panel (as against sixteen in one-panel table).
Suffixes 11-112 are for the first panel, suffixes 21-212 for the second panel, etc.
For syntax, see rst1 - rst16 above.
Numbering of rows is within-panel (i.e. the first row of each panel is 1).
rst1(string) - rst12(string) can be specified, in which case the same row spanning titles are applied to every panel.
Either rst1 - rst12 OR rst11 - rst112 must be chosen, they cannot be mixed.
If the row spanning titles are panel-specific, they may be specified for some but not all panels (as indicated by suffixes 11-112, 21-212, etc.)

extra11(string) - extra19(string) . . . extra51(string) - extra59(string) are additional rows of information, panel-by-panel.
Suffixes 11-19 are for the first panel, suffixes 21-29 for the second panel, etc.
For syntax, see extra1 - extra9 above.
extra1(string) - extra9(string) can be specified, in which case one set of extra rows is
inserted at the bottom of the table (not panel-by-panel), and option extra_place has no effect.

est_means(string).
An equation name for every panel must be specified, in order.
These must be consistent with the names in est#. Separate with comma or space.
The panel-by-panel equation names follow "left" or "right", unless this is omitted ("left" is default).
Note that placement "left" or "right" is the same in every panel.

Examples: est_means(mod1 mod2 mod3)

est_means(right,eq1_1,eq2_1,eq3_1}

est_mat(string).
The matrices must be panel-specific, and ordered from first to last panel. Separate with comma or
space. The panel-by-panel matrix names follow "left" or "right", unless this is omitted ("left" is
default). Note that the placement "left" or "right" is the same in every panel. Also
note that all est_mat matrices must have the same number of columns.

Example: est_mat(right,X1,X2,X3}

Example

mswtable, colwidth(2.0,1.0,0.8,0.8,0.8)
est1(eq1_1 eq1_2 eq1_3 eq1_4)
est2(eq2_1 eq2_2 eq2_3 eq2_4)
est_stat(N,0! r2_a,2! bic,1)
est_star(.05,.01,.001)
est_se(t,below,paren)
title("Table 3. Modeling DFS")
subtitle("OLS Estimates")
extra11(State fixed effects !No !No !Yes !Yes)
extra12(Ridiculous model !Yes !No !Yes !No)
extra21(State fixed effects !No !No !Yes !Yes)
extra22(Ridiculous model !Yes !No !Yes !No)
note1("Significance: * p<.05 ** p<.01 *** p<.001")
sdec(2)
cst1("Equations" 1 4)
ct("`cols'")
rt1("`xvars'") rt2("`xvars'")
pt1("Low fertility (TFR < 4.5)")
pt2("High fertility (TFR >= 4.5)")
pt_set(center,bold)
pline
outfile("$D/analysis/tab3", replace);

Technical odds and ends

Cell justification (horizontal), defaults:

- row titles (first column on left), panel titles, and notes are left-justified;

- title/subtitle and column-spanning titles are center-justified;

- remaining columns are right-justified: column titles, all data cells,
and row titles for the rows at the foot of the table (statistics, extra info)

- except left-justification for est_se in the "beside" location

Table width:

mswtable constrains the width of the table to be the sum of the column widths (colwidth),
plus columns inserted for est_star, est_se, est_means, and est_mat.
Although MSWord does not always perfectly comply.

est_se formatting:

Decimal points:

- standard errors: one decimal point more than the coefficients (see sdec)

- t-statistics: two decimal points

- p-values: three decimal points

- confidence intervals: same as coefficients (see sdec)

Font sizes:

- standard errors, t-statistic, p-value: 1.0-point less than body-of-table font

- confidence interval: 2.0-point less than body-of-table font (but can be adjusted in "ci()")

These two settings (and other fonts) can be modified at lines 184ff in mswtable.ado.

fonts and row heights:

Some fonts are by their nature taller (or shorter). mswtable accounts for this in setting
row heights. Specifically, default row heights are inflated for Arial and
LM Roman 12. The same adjustment could be applied to other fonts by inserting code at lines 226ff in mswtable.ado.

rt row titles and row heights:

mswtable is not smart about row heights. Rows with multi-line titles are set higher,
but only those rows, resulting in non-uniform row heights if the row titles are not entirely one line or two lines.
Keeping all row titles to one line is recommended.

extra#:

extra rows can be used for quantitative values not available in the statistics Stata provides following regression estimation, if these values are placed in macros.
These might be, for example, mean values of the dependent variables.

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'

Sub-matrix extraction:
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