*! version 8.1.0 27Jun2023

help summtab2

Title

summtab2 -- Computes summary statistics overall and/or across levels of a categorical variable
(i.e., the results are stratified by this variable), and
compiles them into a nicely formatted, publication-quality table. This extension of the summtab
command allows for more control over placement of variables in the table, so that categorical and
continuous variables can be mixed.

Syntax

summtab2 [if] [in], vars(varlist) type(numlist) [by(varname) ]

Required
vars(varlist) Specify all variables you wish to summarize

type(numlist) Specify whether each variable in vars is continuous or categorical.
1 for continouous; 2 for categorical.

Column Options
by(varname) Variable by which to stratify the summaries; if not specified, defaults to providing only the overall summaries

bymiss Display missing values of the stratification variable as a separate category

bylabel Display the label of the stratification variable above the categories

total Display a total (overall) column

Statistic Options
mean Display the means and standard deviations for continuous variables

median Display the medians and quartiles (25th and 75th percentiles) for continuous variables

range Display the the minimum and maximum for continuous variables

pnonmiss Display the total number nonmissing and % nonmissing for continuous variables on a separate row

pmiss Display the total number nonmissing and % missing for continuous variables on a separate row. May not be specified at the same time as pnonmiss.

rowperc Provide row percentages for categorical variables, rather than (the default) column percentages

catmisstype(string) How to handle missing values for categorical variables. Three options, detailed in the explanation section below.

P-Value Options
pval Compute and display p-values

contptype(integer) Continuous p-value type

catptype(integer) Categorical p-value type

Format Options
mnfmt(integer) Number of digits to display after the decimal point for means and standard deviations; default is 2; maximum is 8

medfmt(integer) Number of digits to display after the decimal point for medians and quartiles; default is 1; maximum is 8

rangefmt(integer) Number of digits to display after the decimal point for minimums and maximums; default is 1; maximum is 8

pnonmissfmt(integer) Number of digits to display after the decimal point for % non-missing; default is 1; maximum is 8

pmissfmt(integer) Number of digits to display after the decimal point for % missing; default is 1; maximum is 8

catfmt(integer) Number of digits to display after the decimal point for categorical variable percentages; default is 1; maximum is 8

pfmt(integer) Number of digits to display after the decimal point for p-values; default is 3; maximum is 8

Output Options
labelnote Use the variable note to define the variable label; useful for long labels that should not be truncated at 80 characters

directory(string) The directory in which the results are saved; if not specified, defaults to current working directory

title(string) Table title, to put at the top of the output Word document; defaults to Table 1

footnote(string) Table footnote, to put below the table in the output Word document; defaults to no footnote

word If specified, a Word document will be output

wordname(string) Name of Word document; defaults to table1

excel If specified, an Excel document will be output

excelname(string) Name of Excel document; defaults to table1

replace Specify to overwrite the Word and/or Excel file

append Specify to add table to specified Word file; this option is non-functional if only an Excel file is requested

sheetname(string) Specify to add sheet to specified Excel file; specifying this option will automatically modify instead of
replace the Excel file. This option is non-functional if only a Word file is requested

Advanced Options
meanrow Report mean and standard deviation on the same row as the variable label. Only works if mean is specified and no other continuous variable summary statistics are specified.

catrow Report N (%) of the highest ordered category on the same row as the variable label for binary variables. Only works if catmisstype is set to none. See options explanations for more details.

clustpval Request p-values that take into account clustered nature of data; will only take effect if
the pval option is also specified. Clustered p-values are not reported for categorical variables.

clustid(varname) Cluster identifier; needed if clustpval is specified

wts(varname) Obtain weighted summary statistics

wtfreq(string) How frequencies are handled for weighted data. Three options, detailed in the explanation section below.

fracfmt(integer) Number of digits to display after the decimal point for frequencies when weights are specified and the fractional
option of wtfreq(string) is specified. Default is 2 digits.

Any additional options will be passed to putdocx begin. See the help file for putdocx.
For example, one option, landscape, will change the page orientation from portrait to landscape.

Description

summtab2 summarizes a list of continuous and/or categorical variables overall and/or by a categorical
stratification variable, and then outputs the results in a nicely-formatted, publication-quality
table in a Word document, using the Stata command putdocx. The program can also output
the results to an Excel document using putexcel. summtab2 requires
Stata version 15.

Options Explanations

contptype(integer) specifies the continuous p-value type.
The options are 1 = ANOVA; 2 = Kruskall-wallis test;
default is 1 = ANOVA, if the mean option is selected.
NOTE: If mean is not selected and median is selected, the continuous p-value type
will default to 2 = Kruskall-wallis test. This cannot be overridden by the
contptype(integer) option.

catptype(integer) specifies the categorical p-value type.
The options are 1 = chi-square test; 2 = Fisher's exact test;
default is 1 = chi-square test

catmisstype(string) specifies how to handle missing values for categorical variables.
The options are "none" = Missing values are not summarized (default); "missperc" = Missing values are treated as another
category and included in the percent of the total; "missnoperc" = Missing values are treated as another category, but
are not included in the percent of the total.

wtfreq(string) specifies how to handle cell frequencies for categorical variables when weights are used.
The options are "off" = Frequencies are not reported for weighted data (default); "fractional" = Frequencies are reported,
but are kept in their fractional form; "ceiling" = Frequencies are reported and are rounded up to the nearest whole number.

catrow specifies that the N (%) of the highest ordered category is reported on the same row as the variable label for binary variables.
For example, suppose the variable is depression and is coded as 1=yes and 0=no. This option will report the N (%) for the yes category on the
same row as the variable label "Depression", and will not report the N (%) for the no category. This option only works if catmisstype is set to none.
It is the program user's responsibility to make sure that the meaning of the N (%) for the highest ordered category lines up with the variable label.
In the previous example, if the variable had been coded as 1=yes and 2=no, then the no category would have been reported on the same line as the variable label.
In this case, the variable label should either be changed to something like "Not Depressed", or the categories should be recoded so that the yes category is the
highest ordered.

Examples

. sysuse auto, clear

Run summtab2, with summaries stratified by the "foreign" variable

. summtab2, by(foreign) vars(price mpg rep78 weight length) type(1 1 2 1 1) mean median pval landscape replace
word wordname(summary_table) title(My Table 1)

Run summtab2, with overall summaries only

. summtab2, vars(price foreign mpg rep78 weight length) type(1 2 1 2 1 1) word wordname(summary_table)
title(My Table 1) mean median replace

Run summtab2, generate Excel file

. summtab2, by(foreign) vars(price mpg rep78 weight length) type(1 1 2 1 1) mean median total
title(My Table 1) excel excelname(summary_table) replace

Run summtab2, more options

. summtab2, by(foreign) vars(price mpg rep78 weight length) type(1 1 2 1 1) mean median range total
medfmt(1) mnfmt(2) catmisstype(missnoperc) word wordname(summary_table) title(My Table 1) replace

Author

John A. Gallis
Duke University Department of Biostatistics and Bioinformatics
Duke Global Health Institute
Durham, NC
john.gallis@duke.edu

Please email John Gallis (john.gallis@duke.edu) to report bugs or provide suggestions for improvement of the program.

Acknowledgements

Special thanks to members of the Duke Global Health Institute Research Design &
Analysis Core for testing the code and providing recommendations for improving the original summtab program.
This includes Liz Turner, Alyssa Platt, Joe Egger, Ryan Simmons, and Amy Herring.