Stata output  –  How to include Stata output (or Stata code)

Contents of output sections

Several options are available to texdoc stlog to manipulate the contents to be included in an output section. Some of these options are illustrated in the following example:

/*** 
\documentclass[a4paper]{article}
\usepackage{stata}
\begin{document}

\section*{Some options of texdoc stlog}
\begin{itemize}
\item Default: input (commands) and output
***/

texdoc stlog
display "2 + 2 = " 2 + 2
display "sqrt(2) = " /// this is a comment
    sqrt(2)
texdoc stlog close

/*** \item \stcmd{cmdstrip}: output without input ***/

texdoc stlog, cmdstrip
display "2 + 2 = " 2 + 2
display "sqrt(2) = " /// this is a comment
    sqrt(2)
texdoc stlog close

/*** \item \stcmd{nooutput}: input without output ***/

texdoc stlog, nooutput
display "2 + 2 = " 2 + 2
display "sqrt(2) = " /// this is a comment
    sqrt(2)
texdoc stlog close

/*** \item \stcmd{lbstrip}/\stcmd{gtstrip}: remove 
     line-break comments and continuation symbols ***/

texdoc stlog, lbstrip gtstrip
display "2 + 2 = " 2 + 2
display "sqrt(2) = " /// this is a comment
    sqrt(2)
texdoc stlog close

/*** \item \stcmd{matastrip}: remove Mata begin and end commands ***/
texdoc stlog, matastrip
mata:
2 + 2
sqrt(2)
end
texdoc stlog close

/*** Without \stcmd{matastrip} the result would look as follows: ***/

texdoc stlog
mata:
2 + 2
sqrt(2)
end
texdoc stlog close

/***
\end{itemize}
\end{document}
***/

Displaying Stata code

If you want to display Stata code instead of Stata output, use the cmdlog option:

/*** 
\documentclass[a4paper]{article}
\usepackage{stata}

\usepackage{textcomp}
\makeatletter
\g@addto@macro\stLogSetup{\let\'=\textquotesingle}
\makeatother

\begin{document}

\noindent
The following program applies \stcmd{xtsum} to the specified variables and
collects the results in \stcmd{e()} so that they can be tabulated using 
\stcmd{esttab}:

***/

texdoc stlog, cmdlog
program myxtsum, eclass
    syntax varlist [if]
    marksample touse             // mark sample (listwise)
    local stats mean sd min max sd_b min_b max_b sd_w min_w max_w
    foreach s of local stats {   // prepare matrix tempnames
        tempname `s'
    }
    foreach v of local varlist { // run xtsum for each var and collect results
        quietly xtsum `v' if `touse'
        foreach s of local stats {
            matrix ``s'' = nullmat(``s''), r(`s')
        }
    }
    foreach s in N n Tbar { // overall stats; can take any, should all be the same
        local `s' = r(`s')
    }
    foreach s of local stats { // add column names
        matrix coln ``s'' = `varlist'
    }
    tempname b
    matrix `b' = `mean'  // copy means also to e(b); not strictly required
    eret post `b', obs(`N') esample(`touse')
    eret local cmd "myxtsum"
    eret scalar n = `n'
    eret scalar Tbar = `Tbar'
    foreach s of local stats {
        eret matrix `s' = ``s''
    }
end
texdoc stlog close

/*** 

\bigskip\noindent Example usage:

***/

texdoc stlog
webuse nlswork
myxtsum hours birth_yr age grade race
esttab, stats(N n Tbar) nomti nonum compress cells((mean sd min max sd_b sd_w)) 
texdoc stlog close

/***

\end{document}
***/

Note that, even though no output is displayed if cmdlog is specified, the commands are still executed. If you want to omit execution of the commands, additionally apply the nodo option (see below).

The LaTeX commands

\usepackage{textcomp}
\makeatletter
\g@addto@macro\stLogSetup{\let\'=\textquotesingle}
\makeatother

were included in the example above so that closing macro expansion quotes display as upright quotes, as in `...'. Without these commands the quotes would display as `... ́.

The nodo option

An indispensable option for lager projects is the nodo option. The option allows you to recompile your document without re-running the Stata commands. texdoc keeps the log files from previous runs so that re-running the Stata commands would be a waste of time if the Stata commands did not change. Therefore, once the commands in a Stata output section are all set, type

texdoc stlog, nodo

To apply nodo to all Stata output sections in the document, specify nodo with texdoc init or texdoc do. To turn the commands back on in a specific section, type

texdoc stlog, do

Note that you can also turn commands on and off between different parts of the document by applying the texdoc init command with the do or nodo option repeatedly within the do-file. Be aware that texdoc uses consecutive numbers to name the log files of the output sections. Thus, the name for a specific section will change if other (unnamed) sections are added or deleted in preceding parts of the document. In this case you may have to rerun all output sections. Hence, if a specific Stata output section contains time consuming commands it is always a good idea to assign a fixed name (that is, type texdoc stlog name, where name is your chosen name for the output section).

The nolog option

The nolog option of texdoc stlog can be used to exclude commands from being logged. For example, if the logall has been specified, you could type

texdoc stlog, nolog
commands
texdoc stlog close

to omit creating an output section from commands. Furthermore, the nolog option can be useful to include unlogged commands in your do-file that will not be executed if the nodo option has been specified.

The hardcode option

By default texdoc stlog writes the Stata log into an external file and then uses an \input{} statement in LaTeX to include the file. To embed the log directly into the LaTeX document, specify the hardcode option, as in the following example (click the "LaTeX" button to view the resulting output file):

/***
\documentclass[a4paper]{article}
\usepackage{stata}
\begin{document}

\noindent
This output is linked into the document:

***/

texdoc stlog
sysuse auto
summarize price
texdoc stlog close

/***

\bigskip\noindent
This output is copied into the document:

***/

texdoc stlog, hardcode
sysuse auto
summarize price
texdoc stlog close

/***

\end{document}
***/

To apply the hardcode option to all output sections, specify the option with texdoc init or texdoc do.

Setting the line size

The width of a Stata output section (i.e. the maximum number of characters per line) is determined by Stata's current screen width. Use the set linesize command to change the line width. Alternatively, use the linesize() option as illustrated in the following example:

/*** 
\documentclass[a4paper]{article}
\usepackage{stata}
\begin{document}

\noindent
Set the line width to 80 characters:

***/

texdoc stlog, linesize(80)
display "{hline}"
texdoc stlog close

/*** 

\bigskip\noindent Set the line width to 60 characters:

***/

texdoc stlog, linesize(60)
display "{hline}"
texdoc stlog close

/***

\end{document}
***/

Omitting selected output

To suppress output from individual commands, you can use the texdoc stlog oom command, as illustrated in the following example.

/*** 
\documentclass[a4paper]{article}
\usepackage{stata}
\begin{document}

\noindent
Run a regression of price on milage and repair record (categorical)
and perform an overall test for repair record using the \stcmd{testparm}
command.

***/

texdoc stlog, hardcode
sysuse auto
texdoc stlog oom ///
regress price mpg i.rep78
testparm i.rep78
texdoc stlog close

/***

\end{document}
***/

The "output omitted" message is created by the \oom command from the stata LaTeX package. Redefine \oom to change the message:

/*** 
\documentclass[a4paper]{article}
\usepackage{stata}
\begin{document}

\def\oom{\ \ \textrm{(\textit{this is my custom output omitted message})}}

\noindent
Run a regression of price on milage and repair record (categorical)
and perform an overall test for repair record using the \stcmd{testparm}
command.

***/

texdoc stlog, hardcode
sysuse auto
texdoc stlog oom ///
regress price mpg i.rep78
testparm i.rep78
texdoc stlog close

/***

\end{document}
***/

Alternatively, if you want to suppress output without inserting an "output omitted" message, you can use texdoc stlog quietly instead of texdoc stlog oom .

Adding page breaks

To insert a page break within a Stata output, you can use the texdoc stlog cnp command. LaTeX command \cnp, as defined by the stata package, will then be included in the output.

/*** 
\documentclass[a4paper]{article}
\usepackage{stata}
\let\cnp\onnextpage
\begin{document}

\noindent
Run some regressions.

***/

texdoc stlog, hardcode
sysuse auto
regress price mpg
texdoc stlog cnp
regress price mpg i.rep78
texdoc stlog close

/***

\end{document}
***/

By default, \cnp just includes a page break. In the example above \cnp is redefined to be equal to \onnextpage, which also prints a "Continued on next page" message.

The custom option

If you are not satisfied with the standard code that texdoc stlog writes to the LaTeX document to include the log file, you can specify the custom option and create your own variant. For example, \begin{stlog} has an auto option to pick up the font size settings (instead of using the default 8-point font). To use this feature you could apply the custom option and then write your own code to include the log as in the following example:

/***
\documentclass[a4paper]{article}
\usepackage{stata}
\begin{document}

\noindent The following output is displayed using an increased font size:

***/

texdoc stlog, custom
    display "This is displayed in 12-point font size!"
texdoc stlog close
texdoc write {\fontsize{12}{14}\selectfont
texdoc write \begin{stlog}[auto]\input{`s(texname)'}\end{stlog}}

/***

\end{document}
***/

The example makes use of s(texname), which is returned by texdoc stlog close and contains the name (and appropriate path) of the log file (see Stored results in the help file). If you want to change the font size for all Stata output sections in your document you should consider redefining the stlog environment instead of using the custom option (see next example).

Changing the font size

By default, the stlog environment uses an 8-point font. This is appropriate for a document with a 10-point text font. For documents that use a different font size, you may want to adjust the font for Stata output sections by redefining the stlog environment. For example, you may want to use a 10-point font for Stata output in a document with a 12-point text font:

texdoc init, logall
/***
\documentclass[a4paper,12pt]{article}
\usepackage{stata}

\let\oldstlog\stlog
\let\endoldstlog\endstlog
\renewenvironment{stlog}%
    {\bgroup\fontsize{10}{11}\selectfont\oldstlog[auto]}%
    {\endoldstlog\egroup}
 
\begin{document}

\section*{Exercise 1}
Compute a two-way table of repair record by car type.

***/

sysuse auto
tabulate rep78 foreign

/***

\end{document}
***/

Rescaling the output

When including Stata output in presentation slides it may be necessary to adjust the scaling of the output section so that it fits on the screen. This can be achieved by defining an appropriate LaTeX command and then use custom code to include the output sections. Here is an example:

/***
\documentclass{beamer}
\usetheme{Boadilla}
\usepackage{stata}

\newcommand{\stlogscaled}[2]{\scalebox{#1}{%
    \renewcommand{\baselinestretch}{1.0}%
    \begin{minipage}{\linewidth/\real{#1}}%
    \begin{stlog}[beamer]\input{#2}\end{stlog}\end{minipage}}}

\begin{document}

\begin{frame}\frametitle{My example}
    \begin{itemize}
    \item This size of this output has been decreased to fit the slide:
    
    ***/
    set linesize 130
    texdoc stlog, custom
        sysuse auto
        list in 1/30
    texdoc stlog close
    texdoc write \stlogscaled{.6}{`s(texname)'}
    /***
    
    \end{itemize}
\end{frame}

\end{document}
***/

The \stlogscaled command, as defined in the example, resets the line spacing within the output section to 1.0 and keeps the width of the output section at its original value. (Note that the \stlogscaled command relies on the calc package, which is automatically loaded by the stata style.)

Highlighting selected output

You can highlight selected pieces of the Stata output using the alert() option. All instances of the specified strings will then be included in an \alert{} command. Add a suitable definition of the \alert{} command to the preamble of the LaTeX document to achieve the desired result. For example, adding

\usepackage{color}
\def\alert#1{\textcolor{red}{#1}}

to the preamble of the LaTeX document will print the highlighted text in red. In addition you can apply custom tags to selected strings in the output using the tag() option. Within tag() you can specify multiple replacement sets, each consisting of the strings to be tagged, an equal sign, and the desired start and end tags. Here is an example using the beamer class (which already provides a definition for \alert{}):

/***
\documentclass{beamer}
\usetheme{Boadilla}
\usepackage{stata}
\begin{document}

\begin{frame}\frametitle{My example}

Regression of price on milage for \alert{foreign cars} with 
\textcolor{orange}{robust standard errors} and 
\textcolor{purple}{90\% confidence intervals}:

***/

texdoc stlog, beamer alert("if foreign==1") ///
    tag("robust" "Robust" "Std. Err."       = \textcolor{orange}{ } ///
        "level(90)" "[90\% Conf. Interval]" = \textcolor{purple}{ })
sysuse auto
regress price mpg if foreign==1, robust level(90)
texdoc stlog close

/***
\end{frame}
\end{document}
***/

Option beamer has been specified with texdoc stlog to typeset the output using \begin{stlog}[beamer] ... \end{stlog} instead of \begin{stlog} ... \end{stlog}.

Dynamic text (texdoc local)

If you want to add results from a Stata output section to the text body, an approach is to store the results as local macros and then insert the contents of these locals at appropriate places in the text body using texdoc write. A problem, however, is that these locals will no longer be available in later runs once the nodo option is applied. A solution to this problem is provided by the texdoc local command, which can be applied within or after a Stata output section. The command can be used just like Stata's regular local command, but it maintains a backup of the locals on disk and restores them if needed. Furthermore, the local macros defined by texdoc local will be expanded in subsequent /*tex tex*/ or /*** ***/ blocks (up until the next texdoc stlog command, which causes the macro library to be reset). The locals will be backed up in a library that has the same name as the Stata output section (using file suffix ".stloc"). Each output section has its own library, so that the names of the locals can be reused between sections. An example is as follows:

/***
\documentclass[a4paper]{article}
\usepackage{stata}
\parindent0pt \parskip0.6\baselineskip
\begin{document}

Open the 1978 Automobile Data and run a regression of price on
milage using the \stcmd{regress} command.

***/

texdoc stlog
    sysuse auto
    regress price mpg
texdoc stlog close
texdoc local r2 = strofreal(e(r2)*100, "%9.2f")
texdoc local tval = strofreal(abs(_b[mpg]/_se[mpg]), "%9.1f") 

/*** 
The $R^2$ of this regression is equal to `r2'\% and the effect of milage on
price is highly significant (absolute $t$-value of `tval').

What happens if we control for car type?

***/

texdoc stlog
    regress price mpg i.foreign
texdoc stlog close
texdoc local r2 = strofreal(e(r2)*100, "%9.2f")
texdoc local tval = strofreal(abs(_b[mpg]/_se[mpg]), "%9.1f") 

/*** 
Now the $R^2$ increased to `r2'\% and the absolute $t$-value of the effect
of milage on price increased to `tval'.

\end{document}
***/

Note that texdoc local also works in combination with the logall option. Furthermore, you can use texdoc write to write the locals to the output document instead of including them in a /*tex tex*/ or /*** ***/ block. Example:

texdoc init, logall

/***
\documentclass[a4paper]{article}
\usepackage{stata}
\parindent0pt \parskip0.6\baselineskip
\begin{document}

***/

sysuse auto
summarize price
texdoc local N = r(N)
texdoc local mean = strofreal(r(mean), "%9.1f")

/*** 

There are `N' observations in the data set. The mean of price is `mean'.
Let's look at another variable:

***/

summarize mpg
texdoc local mean = strofreal(r(mean), "%9.1f")
texdoc local sd = strofreal(r(sd), "%9.2f")

texdoc write The mean of milage is `mean', with a standard deviation of `sd'.

/*** 
\end{document}
***/