help for docxtab (Roger Newson)

List variables to a .docx table with head or foot rows from characteristics

docxtab [ varlist ] [if] [in] , tablename(tablename) [

headchars(namelist) footchars(namelist)
headformat(cell_fmt_options) footformat(cell_fmt_options)
tcolchars(namelist)
trowseq(newvar)
table_options
]

where tablename is a table name for a generated table acceptable to putdocx table,
cell_fmt_options are cell format options recognized by putdocx table,
and table_options are any options acceptable to the command

putdocx table tablename = data(varlist) [ , table_options ]

Description

docxtab lists the variables in the varlist (or all variables, if the varlist
is absent) to an Office Open XML (.docx) table acceptable to putdocx table,
with added header rows above and footer rows below,
extracted from variable characteristics.
These characteristics may be multiple
(allowing multiple header and footer rows),
and each characteristic may be set for multiple variables by the SSC package chardef.
The generated .docx table can then be modified using other putdocx table commands,
to change the formatting of rows, columns, or cells.

Options for docxtab

tablename(tablename) must be specified.
It specifies a table name for the generated .docx table,
acceptable to putdocx table.
This .docx table can then be modified using further putdocx table commands,
to modify formats of rows, columns, and cells.

headchars(namelist) specifies a list of variable characteristic names,
used to create table header rows containing the values of these characteristics for the variables in the varlist.
These header rows appear before the first of the table rows containing the variable values,
and also before the variable names row specified by the varnames option,
if that option is specified.
This option enables the user to add column header labels for the variables in the varlist.

footchars(namelist) specifies a list of variable characteristic names,
used to create table footer rows containing the values of these characteristics for the variables in the varlist.
These header rows appear after the last of the table rows containing the variable values.
This option enables the user to add column footer labels for the variables in the varlist.
in multiple local macros.
For instance, the user might want two header rows,
one containing variable names, and the other containing variable labels.

headformat(cell_fmt_options) specifies a list of cell format options,
recognized by putdocx table,
to apply to the header rows.
For instance, headformat(italic) specifies that the header rows will all be in italic fonts.

footformat(cell_fmt_options) specifies a list of cell format options,
recognized by putdocx table,
to apply to the footer rows.
For instance, footformat(italic) specifies that the footer rows will all be in italic fonts.

tcolchars(namelist) specifies a list of variable characteristic names,
naming characteristics set to contain table cell format options
for the corresponding variables in the varlist.
For instance, if a characteristic in the namelist belonging to a variable in the varlist
has value halign(right),
then the column of the generated table containing that variable will be right-aligned.

trowseq(newvar) specifies the name of a generated variable,
to contain, in each observation,
the table row sequence corresponding to that observation.
If the observation does not correspond to a table row,
then the generated variable is set to missing.
A trowseq() variable can then be used to format a subset of table rows.
Note that, if the option varnames is specified,
then the table row sequence starts at the number of header rows plus 2,
but otherwise the table row sequence starts at the number of header rows plus 1.

Remarks

docxtab is intended to give the .docx user some of the functionality of listtab,
which is described in Newson (2012).
listtab and docxtab frequently use variable characteristics,
frequently set using the SSC package chardef,
to create header and footer rows for tables.
The packages listtab, chardef, and docxtab
are intended mainly for use with resultssets,
which are described in Newson (2022),
Newson (2012), Newson (2006),
Newson (2004), and Newson (2003).

Examples

The following example demonstrates the creation of a .docx document,
containing a table with one header row extracted from a characteristic
and column alignments extracted from another characteristic.
The table has 1 row for each of the 22 non-US car models in the auto data.

Set up:

. sysuse auto, clear

. keep if foreign

. describe, full

Assign characteristics varhandle and colfmt to variables make, mpg, and weight,
using the SSC package chardef:

. chardef make mpg weight, char(varhandle) values("Car model" "Miles per US gallon" "Weight (US pounds)")

. chardef make mpg weight, char(colfmt) values("halign(left)" "halign(right)" "halign(right)")

. char list

Create document in the file myword.docx,
with the first line of variable handles italicized,
and the table columns aligned left, right, and right:

. putdocx begin, pagesize(A4)

. docxtab make mpg weight, tablename(mytable) headchar(varhandle) headformat(italic) tcolchar(colfmt)

. return list

. putdocx describe mytable

. putdocx save "myword.docx", replace

The following more advanced example inputs odd-numbered car models from the auto data,
and creates a .docx document,
containing a table of car models,
with separate gap rows introducing the US and non-US cars.
To do this, we use the SSC packages
chardef, insingap, ingap, and sdecode.

Set up

. sysuse auto, clear

. keep if mod(_n,2)

. describe, full

Create document

. putdocx begin, pagesize(A4)

. preserve

. clonevar rowlab=make

. sdecode mpg, replace

. sdecode weight, replace

. chardef rowlab mpg weight, char(varhandle) values("Car model" "Miles per US gallon" "Weight (US pounds)")

. insingap foreign, row(rowlab) grdecode(foreign) prefix("Odd-numbered ") suffix(" Cars:") gapind(gapobs)

. docxtab rowlab mpg weight, tablename(theirtable) headchar(varhandle) headformat(italic) trowseq(rowseq)

. levelsof rowseq if gapobs, local(gaplist)

. putdocx table theirtable(`gaplist',.), bold

. putdocx table theirtable(.,.), halign(right)

. restore

. putdocx save "theirword.docx", replace

Note that we generate the table between a preserve statement and a restore statement,
because we modify existing variables and add new ones when generating the table.
We use clonevar and sdecode to create the variables be tabulated,
as string variables.
We use chardef as before, to set the characteristic varhandle
for these variables.
We use insingap to add gap rows to the dataset in memory,
containing gap row labels.
We then use docxtab to create the first version of the table,
with a trowseq() option to store the table row sequence numbers in the variable rowseq,
and then use putdocx table to modify the gap rows to be bold,
and to right-justify all cells in the table.

More complicated examples are possible,
generating more complicated tables with multiple head and/or foot rows
from multiple variable characteristics.

Saved results

docxtab saves the following in r():

Scalars

r(fbody) first row of table body

r(lbody) last row of table body

r(nbody) number of rows in table body

r(fhead) first row of table head

r(lhead) last row of table head

r(nhead) number of rows in table head

r(ffoot) first row of table foot

r(lfoot) last row of table foot

r(nfoot) number of rows in table foot

r(nrow) total number of rows in table

r(ncol) total number of columns in table

Macros

r(varlist) input varlist

r(tcolseq) list of table column sequences corresponding to input varlist

The total number of rows in the table r(nrow)
is equal to the sum of r(nhead), r(nbody), and r(nfoot)
(the numbers of rows in the table head, body, and foot, respectively),
plus one more row of variable names if the varnames option is specified,
plus one more row if the title() option is specified,
plus one more row if the note() option is specified.
The total number of columns in the table r(ncol)
is equal to the total number of variables in the input varlist,
plus one more column of table body row sequence numbers,
if the obsno option is specified.
The options varnames and obsno
will probably not be used very often.

Author

Roger Newson, King's College London, UK.
Email: roger.newson@kcl.ac.uk

References

Newson, R. B. 2022.
Resultssets in resultstables in Stata 16-plus.
Presented at the 2022 London Stata Conference, London, 8 September, 2022.

Newson, R. B. 2012.
From resultssets to resultstables in Stata.
The Stata Journal 12 (2): 191-213.
Download from The Stata Journal website.

Newson, R. 2006.
Resultssets, resultsspreadsheets and resultsplots in Stata.
Presented at the 4th German Stata User Meeting, Mannheim, 31 March, 2006.

Newson, R. 2004.
From datasets to resultssets in Stata.
Presented at the 10th United Kingdom Stata Users' Group Meeting, London, 29 June, 2004.

Newson, R. 2003.
Confidence intervals and p-values for delivery to the end user.
The Stata Journal 3(3): 245-269.
Download from The Stata Journal website.

Also see

Help for putdocx, putdocx table

Help for chardef, sdecode, ingap, insingap, listtab if installed