help for latexlog (Johannes F. Schmieder)

Title

latexlog: Flexible command to build LaTeX reports from within Stata.

Syntax

latexlog filename : subcommand [, options]

where filename is the path and name of the log file and subcommand is one of the following:

subcommand description

Main
open [, options] Write the preamble of the LaTeX file.
close Write the closing commands of the LaTeX file.
pdf [, options] Compile the LaTeX file to a PDF and optionally view it.

Adding sections and text
title "str" Write the "str" as the title of the LaTeX file.
section "str" Write the "str" as a section heading into the LaTeX file.
sections "str" Write the "str" as an unnumbered section heading (\section*).
subsection "str" Write the "str" as a subsection heading into the LaTeX file.
writeln "str" Write the "str" as a line of text into the LaTeX file.

Figures
addfig [, options] Add a figure to the LaTeX file.
subfigure [, options] Add a figure with subfigures to the LaTeX file.

Tables
collect [, options] Export a table to the LaTeX file.

Description

The latexlog command builds LaTeX reports from within Stata.
It allows a variety of LaTeX objects to be added to the report.
The command uses different subcommands to add different types of objects to the log file.
If pdflatex is installed, the pdf subcommand can be used to automatically
compile the latex file to a PDF and optionally view it.

Requirements

latexlog requires Stata 18 or later. Version 18 is the oldest Stata
release certified for latexlog 0.5.0.

Creating a .tex document does not require a LaTeX installation. The
pdf subcommand requires pdflatex and the following LaTeX packages:
geometry, booktabs, longtable, pdflscape, rotating, threeparttable,
subcaption, graphicx, float, tabularx, colortbl, xcolor, and hyperref.

Subcommands and Options

Main

open [, options] This writes the preamble into the latex file.
It uses the document class article and various standard packages.
options are:
replace Overwrite the latex file if it already exists.
append Append to the latex file if it already exists.
geometry(str) Specify the geometry of the latex file. The default is a letter paper with 2.5cm margins.
predocopen(str) Specify additional commands to be added to the preamble of the latex file.
postdocopen(str) Specify additional commands to be added after the \begin{document} command.

close [, options] This writes the closing commands of the latex file.
options are:
predocclose(str) Specify additional commands to be added before the \end{document} command.

pdf [, options] Compile the latex file to a PDF and optionally view it.
options are:
view View the PDF file after it is compiled.
shellescape Opt in to pdflatex's unrestricted shell escape.
Shell escape is disabled by default because TeX content can execute operating-system commands when it is enabled.
pdflatex(path) Use a specific pdflatex executable. Paths containing spaces are supported.

latexlog runs one pdflatex pass with halt-on-error, verifies a fresh nonempty PDF,
and returns error 693 if compilation fails. On failure, the compiler log is retained
beside the requested PDF. On success, temporary auxiliary files are removed.
By default it uses /Library/TeX/texbin/pdflatex on macOS when present,
and otherwise resolves pdflatex through the operating-system path.
PDF source and compiler paths containing shell-expansion characters are rejected.

Adding sections and text

title "str" Write the str as the title of the latex file.
section "str" Write the str as a section heading into the latex file.
sections "str" Write the str as an unnumbered section heading (\section*) into the latex file.
subsection "str" Write the str as a subsection heading into the latex file.
writeln "str" Write the str as a line of text into the latex file.

Figures

addfig, filename(str) [options] Add the current graph as a figure to the latex file.
str is the path and name of the figure to be added.
The path is relative to the log file.
E.g. if the log file is in ./log/ and the "str" is in "./figures/myfigure.pdf"
then the figure will be stored in ./log/figures/myfigure.pdf

options are:
filename(str) Specify the file name of the figure to be added.
The filename must include an extension. Nested directories and spaces are supported.
float Place the figure in a floating figure environment.
title(str[, tabular]) Specify the title of a floating figure. Use tabular to wrap a long title.
notes(str[, center]) Specify notes for a floating figure. Use center to center the notes.
eol Add a \\ after an inline figure. eol may not be combined with float.
width(real) Specify the width of the figure. The default is 0.9.
width() must be greater than zero. title() and notes() require float.

subfigure, options Add a figure with subfigures to the latex file.
options are:
Specify exactly one of open, addfig, or close on each call.
open Open a subfigure environment.
title(str[, tabular]) Specify the title of the figure, to be used with open. Use tabular sub-option to wrap title in tabular.
close Close a subfigure environment.
notes(str[, center]) Specify the notes of the figure, to be used with close. Use center sub-option to center the notes.
addfig filename(str) Add the current graph as subfigure to the latex file.
str is the path and name of the figure to be added.
The path is relative to the log file.
E.g. if the log file is in ./log/ and the "str" is in "./figures/myfigure.pdf"
then the figure will be stored in ./log/figures/myfigure.pdf
caption(str) Specify the caption of the subfigure.
width(real) Specify the width of the subfigure. The default is 0.9.
E.g. for 2x1 subfigures (2 rows, 1 column), a good width might be 0.9.
For 2x2 subfigures (2 rows, 2 columns), a good width might be 0.45.
eol Add a \\ after this subfigure, forcing the next subfigure onto a new line.
caption(), filename(), and eol apply only with addfig;
title() applies only with open; and notes() applies only with close.

Tables

collect [, options] Exports a table (i.e. a Stata collection) to the LaTeX file.
The command uses the collect export command to export the table, but adds some
additional LaTeX code to put the table in a float environment, to add a title and notes.
options are:
title(str) Specify the title of the table.
notes(str) Specify the notes of the table.
booktabs Use booktabs style for the table.
noverticallines (or novert) Do not draw vertical lines in the table.
threeparttable Use threeparttable style for the table.
fontsize(float) Specify the fontsize of the table. E.g. fontsize(10.5) will set the fontsize to 10.5pt.
landscape Use landscape mode for the table.
tabularx(col_nums[, width(width)]) Convert table to tabularx format for better column wrapping.
col_nums specifies which columns to make flexible (X columns).
E.g. tabularx(2 3) makes columns 2 and 3 flexible.
Use width() sub-option to set table width (default: \textwidth).

Example

Example : Latexfile with Figures and Table

Note: This will create a subfolder called "./log/" in your working directory
and save the log file there.

local log ./log/logtest.tex
cap mkdir ./log/
latexlog `log': open

latexlog `log': title "Illustrating the use of the latexlog package"
latexlog `log': writeln "A descriptive analysis of the nlsw88.dta data"
latexlog `log': section "Introduction"
latexlog `log': writeln "This file provides examples of the use of the latexlog package."

latexlog `log': section "Saving Figures"

sysuse nlsw88, clear
local var wage
scatter `var' ttl_exp
latexlog `log': addfig, filename(./figures/scatter_`var'.pdf) ///
float ///
title(A scatterplot of `var' vs. experience using the addfig subcommand) ///
notes(Based on the nlsw88.dta data) width(.8)

latexlog `log': subfigure , open ///
title(Four Scatterplots of different variables vs. experience using the subfigure subcommand)
foreach var in wage hours tenure grade {
scatter `var' ttl_exp , ylabel(,angle(vertical))
local cap : variable label `var'
latexlog `log': subfigure , addfig filename(./figures/scatter_`var'.pdf) ///
caption("`cap' vs. experience") width(.45)
}
latexlog `log': subfigure , close notes(Based on the nlsw88.dta data)
latexlog `log': writeln "\clearpage\pagebreak"

latexlog `log': section "Saving Tables with latexlog"
latexlog `log': subsection "Example of a twoway table:"
latexlog `log': writeln "The following example creates a twoway table using Stata's \textbf{table} command. "
latexlog `log': writeln "This table is then saved to the log file using the \textbf{collect export} subcommand."

table occupation union, nototals
latexlog `log': collect export , ///
title(Table using Stata "table" command and latexlog "collect export" subcommand) ///
booktabs novert notes(Command: table occupation union, nototals) three

latexlog `log': subsection "Example of a regression table:"
g logwage = log(wage)
estimates clear
capture which etable
if !_rc {
qui: regress logwage ttl_exp
estimates store model1
qui: regress logwage ttl_exp grade married
estimates store model2
etable, estimates(model1 model2) mstat(N) mstat(r2_a)
latexlog `log': collect export , ///
title(Regression Table using Stata "etable" command and latexlog "collect export" subcommand) ///
notes(Command: etable, estimates(model1 model2) mstat(N) mstat(r2\_a)) ///
threeparttable booktabs novert
}

latexlog `log': close
latexlog `log': pdf, view

(click to run)

Author

Johannes F. Schmieder, Boston University, USA

Email: johannes@bu.edu

Comments welcome!

Also see

On-line: help for table, collect export, graph export