listtab [ varlist ] [ using filename ] [if] [in] [ , begin(string) delimiter(string) end(string) missnum(string) rstyle(rowstyle) vbegin(varname) vdelimiter(varname) vend(varname) headlines(string_list) footlines(string_list) headchars(namelist) footchars(namelist) nolabel type replace appendto(filename) handle(handle_name) ]
listtab_vars [ varlist ] [ , begin(string) delimiter(string) end(string) missnum(string) rstyle(rowstyle) substitute(variable_attribute) local(local_macro_name) ]
listtab_rstyle [ , begin(string) delimiter(string) end(string) missnum(string) rstyle(rowstyle) local(local_macro_name_list) ]
where rowstyle is a row style as defined below under Row Styles, variable_attribute is
name | type | format | vallab | varlab | char charname
and charname is a characteristic name.
Description
listtab lists the variables in the varlist (or all variables, if the varlist is absent) to the Stata log, or to a file (or files) specified by using, appendto() or handle(), in a table format, with one table row per observation and the values of different variables separated by a delimiter string. Optionally, the user may specify a list of header lines before the data rows and/or a list of footer lines after the data rows. The log or output file can then be cut and pasted, or linked or embedded (eg with the TeX \input command), into a TeX, HTML or word processor table. Values of numeric variables are output according to their display formats or value labels (if non-missing), or as the missing value string specified by missnum() (if missing).
The commands listtab_vars and listtab_rstyle are tools for programmers to use with listtab. listtab_vars generates a table row, containing, in each column, an attribute (such as the name) of the variable corresponding to the column. This generated table row is saved in r(vars) and (optionally) in a local macro, and is then typically used to specify a headlines() option for listtab. listtab_rstyle inputs a listtab row style, and saves the components of the row style in r() and (optionally) in local macros.
Options for listtab, listtab_vars, and listtab_rstyle
begin(string) specifies a string to be output at the beginning of every output line corresponding to an observation. If absent, it is set to an empty string.
delimiter(string) specifies the delimiter between values in an observation. If absent, it is set to an empty string.
end(string) specifies a string to be output at the end of every output line corresponding to an observation. If absent, it is set to an empty string.
missnum(string) specifies a string to be output for numeric missing values. If absent, it is set to an empty string.
rstyle(rowstyle) specifies a row style for the table rows. A row style is a named combination of values for the begin(), end(), delimiter() and missnum() options. It may be html, htmlhead, tabular, halign, settabs or tabdelim. Row styles are specified under Row styles below. The options set by a row style may be overridden by the begin(), end(), delimiter() and missnum() options.
Options for listtab only
vbegin(varname) specifies a string variable to be output before any variables in the varlist. If vbegin() is absent, then the begin() string is output instead.
vdelimiter(varname) specifies a string variable to be output as a delimiter between consecutive variables in the varlist. If vdelimiter() is absent, then the delimiter() string is output instead.
vend(varname) specifies a string variable to be output after all variables in the varlist. If vend() is absent, then the end() string is output instead.
Note that the option vbegin() overrides begin(), vdelimiter() overrides delimiter(), and vend() overrides end(). The vbegin(), vdelimiter() and vend() options allow the user to use different begin, delimiter and end strings for different observations.
headlines(string_list) specifies a list of lines of text to appear before the first of the table rows in the output. This option enables the user to add table preludes and/or headers.
footlines(string_list) specifies a list of lines of text to appear after the last of the table rows in the output. This option enables the user to add table postludes and/or footnotes.
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, prefixed, delimited and suffixed with the strings specified by the begin(), delimiter() and end() options. These header rows appear after the lines of text specified by headlines(), and before the first of the table rows containing the variable values. 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, prefixed, delimited and suffixed with the strings specified by the begin(), delimiter() and end() options. These header rows appear before the lines of text specified by footlines(), and 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.
nolabel specifies that numeric variables with variable labels will be output as numbers and not as labels.
type specifies that the output from listtab will be typed to the Stata log (or to the Results window). The data can then be cut and pasted from the Stata log (or from the Results window) to a TeX, HTML or word processor file.
replace specifies that any existing file with the same name as the using file will be overwritten.
appendto(filename) specifies the name of an existing file, to which the output from listtab will be appended.
handle(handle_name) specifies the name of a file handle, specifying a file that is already open for output as a text file, to which the output from listtab will be added, without closing the file. See help for file for details about file handles. This option allows the user to use listtab together with file as a low-level output utility, possibly combining listtab output with other output.
Note that the user must specify the using qualifier and/or the type option and/or the appendto() option and/or the handle() option.
Options for listtab_vars only
substitute(variable_attribute) specifies a variable attribute to be entered into the columns of the generated table row. This attribute may be name, type, format, vallab, varlab, or char charname, specifying the variable name, storage type, display format, value label, variable label, or a named variable characteristic, respectively. If substitute() is not specified, then substitute(name) is assumed, and variable names are entered in the columns of the generated table row. In the table row generated by listtab_vars, the attributes of the variables in the varlist (or of all the variables, if the varlist is absent) appear in the columns, and are separated by the delimiter() string, and prefixed and suffixed by the begin() and end() strings, specified by the row style.
Options for listtab_rstyle and listtab_vars
local(local_macro_name_list) specifies the name of a local macro in the program that calls listtab_vars, or the names of up to 4 local macros in the program that calls listtab_rstyle. In the case of listtab_vars, the macro will be set to the value of the row of variable attributes generated by listtab_vars, specified by the substitute() option. In the case of listtab_rstyle, these macros will be set to the begin(), delimiter(), end() and missnum() options, respectively, of the row style generated by listtab_rstyle. The local() option has the advantage that the user can save multiple header rows, or multiple row style specifications, in multiple local macros. For instance, the user might want two header rows, one containing variable names, and the other containing variable labels.
A row style is a combination of the begin(), end(), delimiter() and missnum() options. Each row style produces rows for a particular type of table (HTML, TeX or word processor). The row styles available are as follows:
------------------------------------------------------------------------------- Row style begin() delimiter() end() missnum() Description html "<tr><td>" "</td><td>" "</td></tr>" "" HTML table > rows htmlhead "<tr><th>" "</th><th>" "</th></tr>" "" HTML table > header rows tabular "" "&" `"\\"' "" LaTeX \tabu > lar environment table rows halign "" "&" "\cr" "" Plain TeX \ > halign table rows settabs "\+" "&" "\cr" "" Plain TeX \ > settabs table rows tabdelim "" char(9) "" "" Tab-delimit > ed text file rows -------------------------------------------------------------------------------
The tabdelim row style produces text rows delimited by the tab character, returned by the char() function as char(9). It should be used with using, or with the appendto() or handle() options, to output the table rows to a file. If it is used with the type option, then the tab character is not preserved in the Stata log or Results window. Any of these row styles may be specified together with begin() and/or delimiter() and/or end() and/or missnum() options, and the default options for the row style will then be overridden. For instance, the user may specify any of the above options with missnum(-), and then missing numeric values will be given as minus signs.
Row styles can also be created for output to tables in Rich Text Format (RTF) documents, using the rtfrstyle module of the rtfutil package, which can be downloaded from SSC. Row styles for RTF documents are more complicated than those for other documents, because the begin() and/or end() options used depend on the number of variables output, and on the spacing of these variables as columns in the table. It may also be necessary to use the vbegin(), vdelimiter) and vend() options, if the user requires borders and/or vertical alignment for some table rows and not for others.
More about plain TeX can be found in Knuth (1992). More about LaTeX can be found in Lamport (1994). More about HTML can be found at The W3C HyperText Markup Language (HTML) Home Page at http://www.w3.org/MarkUp/. More about RTF can be found in Burke (2003), or at Sean Burke's RTF web page.
Remarks
listtab is used with a group of other Stata packages to produce tables from Stata datasets, as described in Newson (2012). It creates (on disk and/or in the Stata log and/or Results window) a text table with up to 3 kinds of rows. These are headline rows, data rows and footline rows. Any of these categories of rows may be empty. The headline and footline rows can be anything the user specifies in the headline() and footline() options, respectively. This allows the user to specify TeX preambles, LaTeX environment delimiters, HTML table delimiters and header rows, or other headlines and/or footlines for table formats not yet invented. The data rows must contain variable values, separated by the delimiter() string, with the begin() string on the left and the end() string on the right. This general plan allows the option of using the same package to generate TeX, LaTeX, HTML, RTF, Microsoft Word, and possibly other tables. The rstyle() option saves the user from having to remember other options. The text table generated can then be cut and pasted, embedded, or linked (eg with the TeX \input command) into a document. The inccat command, available on SSC, can be used to embed a using file produced by listtab into a document. If all the variables are string, then title rows may sometimes be created using the ingap package, also on SSC, instead of using the headlines() option of listtab.
The ssc, findit or net commands can also be used to find the various alternatives to listtab, such as corrtex, estout, outtable, outtex, textab and sutex, which also produce tables from Stata.
Historical note
The listtab package is a revision of the listtex package, which can also be downloaded from SSC. In listtex, the delimiter() option defaults to the ampersand ("&"), which is used in most TeX tables, and often also for tables pasted manually into Microsoft Word documents and converted. This listtex option cannot be reset to an empty string (""). In listtab, the default delimiter is an empty string, which will probably only be used occasionally, but can be reset to any non-empty string.
For more about the use of listtab and listtex with other packages, see Newson (2012), Newson (2006), Newson (2004), and Newson (2003).
Examples
To type text table lines separated by & characters for cutting and pasting into a Microsoft Word table using the menu sequence Table->Convert->Text to Table:
. listtab make foreign weight mpg, type delim(&)
To output text table lines separated by tab characters to a text file for cutting and pasting into a Microsoft Word table using Table->Convert->Text to Table:
. listtab make foreign weight mpg using trash1.txt, rstyle(tabdelim)
To produce TeX table lines for a plain TeX \halign table:
. listtab make foreign weight mpg using trash1.tex, rs(halign) replace
To produce TeX table lines for a plain TeX \halign table with horizontal and vertical rules:
. listtab make foreign weight mpg using trash1.tex, b(&&) d(&&) e(&\cr{\noalign{\hrule}}) replace
To produce TeX table lines for a plain TeX \settabs table:
. listtab make foreign weight mpg using trash1.tex, rstyle(settabs) replace
To produce LaTeX table lines for the LaTeX tabular environment:
. listtab make foreign weight mpg using trash1.tex, rstyle(tabular) replace
To produce a LaTeX tabular environment with a title line, for cutting and pasting into a document:
. listtab make weight mpg if foreign, type rstyle(tabular) head("\begin{tabular}{rrr}" `"\textit{Make}&\textit{Weight (lbs)}&\textit{Mileage (mpg)}\\"') foot("\end{tabular}")
Note that the user must specify compound quotes `""' around strings in the head() option containing the double backslash \\ at the end of a LaTeX line. This is because, inside Stata strings delimited by simple quotes "", a double backslash is interpreted as a single backslash.
To produce HTML table rows for insertion into a HTML table:
. listtab make foreign weight mpg using trash1.htm, rstyle(html) replace
To produce a HTML table for cutting and pasting into a HTML document:
. listtab make weight mpg if foreign, type rstyle(html) head(`"<table border="1">"' "<tr><th>Make and Model</th><th>Weight (lbs)</th><th>Mileage (mpg)</th></tr>") foot("</table>")
To produce the same HTML table, using listtab_vars:
. listtab_vars make weight mpg, substitute(varlab) rstyle(htmlhead) local(headrow) . listtab make weight mpg if foreign, type rstyle(html) head(`"<table border="1">"' `"`headrow'"') foot("</table>")
To produce a HTML table of variable attributes using listtab_vars with the descsave package (an extended version of describe downloadable from SSC):
. preserve . descsave, norestore . list, noobs abbr(32) subvarname . listtab_vars, rstyle(htmlhead) substitute(char varname) . listtab, type rstyle(html) head("<table frame=box>" "`r(vars)'") foot("</table>") . restore
For examples using Rich Text Format (RTF), see on-line help for rtfutil, if installed. The rtfutil package can be downloaded from SSC.
Saved results
listtab_rstyle saves the following in r():
Macros r(begin) begin() string r(delimiter) delimiter() string r(end) end() string r(missnum) missnum() string
listtab_vars saves the above items in r(), and also the following:
Macros r(vars) generated table row
Author
Roger Newson, National Heart and Lung Institute, Imperial College London, UK. Email: r.newson@imperial.ac.uk
Burke S. M. 2003. RTF Pocket Guide. Sebastopol, CA: O'Reilly & Associates Inc. Download more information from Sean Burke's RTF web page.
Knuth D. E. 1992. The TeXbook. Reading, Mass: Addison-Wesley.
Lamport L. 1994. LaTeX: a document preparation system. 2nd edition. Boston, Mass: Addison-Wesley.
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
Manual: [D] describe, [P] file, [D] insheet, [D] list, [D] outsheet, [R] ssc, [D] type
Help: [D] describe, [P] file, [D] insheet, [D] list, [D] outsheet, [R] ssc, [D] type descsave, inccat, ingap, listtex, rtfutil, sdecode, corrtex, estout, outtable, outtex, textab, sutex if installed
Other: The W3C HyperText Markup Language (HTML) Home Page at http://www.w3.org/MarkUp/ Sean Burke's RTF web page