Graphs  –  How to include graphs

The texdoc graph command

To include a graph in the output document, simply type texdoc graph after the graph has been created. texdoc graph will store the graph on disk and place appropriate code in the LaTeX document to display the graph. By default, a PDF graph is produced and the \includegraphics command, provided by the graphicx package, is used to include the graph in the LaTeX document. Hence, command \usepackage{graphicx} needs to be added to the preamble of the document:

texdoc init, logall
/*** 
\documentclass[a4paper]{article}
\usepackage{graphicx}
\usepackage{stata}
\begin{document}

\noindent
Open the 1978 Automobile Data and draw a scatter plot of price against
milage using the \stcmd{twoway} command and include a linear fit.

***/

sysuse auto
twoway (scatter price mpg) (lfit price mpg)
texdoc graph, optargs(width=0.8\textwidth)

/***

\end{document}
***/

Option optargs() is used in the example to pass arguments through to the \includegraphics command; see the documentation of the graphicx package for information on available arguments (www.ctan.org/pkg/graphicx). For information on further texdoc graph options to specify how the graph is exported and how it is integrated into the LaTeX document see the graph options in the help file.

Graph name

texdoc graph automatically creates a name for the graph (based on the name of the relevant Stata output section). If you want your graph to have a specific name, you can type texdoc graph name, where name is the name to be used for the graph.

Placement of graphs

If, as in the example above, the logall option is specified, texdoc will stop the Stata output section at the position of the texdoc graph command, insert the graph, and then continue with a new output section. If you want to display a graph that has been produced within an explicit texdoc stlog section, it is usually better to call texdoc graph after the section has been closed, so that the graph is placed after the output section. That is, type

texdoc stlog
    ...
    graph command
    ...
texdoc stlog close
texdoc graph

instead of

texdoc stlog
    ...
    graph command
    texdoc graph
    ...
texdoc stlog close

Typing texdoc graph within a texdoc stlog section is allowed (and will be suppressed in the resulting output), but it will cause the graph to be included in the LaTeX document before the Stata output.

Hiding the graph commands

If you just want to include the graph in the LaTeX document without showing the commands generating the graph, place the commands in a texdoc stlog section and apply the nolog option. Placing the commands in a texdoc stlog section makes it possible to rerun the do-file later on without having to recreate the graph (i.e. applying the nodo option).

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

\noindent
The following graph displays a scatter plot including a linear fit of price against
milage using the 1978 Automobile Data.

***/

texdoc stlog, nolog
    sysuse auto
    twoway (scatter price mpg) (lfit price mpg)
texdoc stlog close
texdoc graph, optargs(width=0.8\textwidth)

/***

\end{document}
***/

The figure environment

By default, texdoc graph places the graph in a center environment. To create a floating figure, use the figure option:

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

\noindent
Figure~\ref{f1} displays a scatter plot including a linear fit of price against
milage using the 1978 Automobile Data.

***/

texdoc stlog, nolog
    sysuse auto
    twoway (scatter price mpg) (lfit price mpg)
texdoc stlog close
texdoc graph, optargs(width=0.8\textwidth) figure(h!) ///
     caption(A scatter plot) label(f1)

/***

\end{document}
***/

Option caption() has been added to provide a title for the figure, option label() has been added to set a cross-referencing label. Furthermore, note how the figure() option has been used to pass through optional arguments to the figure environment.

Custom inclusion code

As illustrated above, texdoc graph places the graph either in a center environment or in a figure environment. To use a different environment, specify nocenter and manually provide the appropriate LaTeX commands using texdoc write. For example, to display a right-aligned graph, you could type:

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

\noindent
Open the 1978 Automobile Data and draw a scatter plot of price against
milage using the \stcmd{twoway} command and include a linear fit.

***/

texdoc stlog
    sysuse auto
    twoway (scatter price mpg) (lfit price mpg)
texdoc stlog close
texdoc write \begin{flushright}
texdoc graph, optargs(width=0.6\textwidth) nocenter
texdoc write \end{flushright}

/***

\end{document}
***/

Using EPS

By default, texdoc graph generates a PDF and uses the \includegraphics command to include the graph in the LaTeX document. If you instead want to write an EPS file and use the \epsfig command, specify the epsfig option:

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

\noindent
Open the 1978 Automobile Data and draw a scatter plot of price against
milage using the \stcmd{twoway} command and include a linear fit.

***/

texdoc stlog
    sysuse auto
    twoway (scatter price mpg) (lfit price mpg)
texdoc stlog close
texdoc graph, optargs(width=0.8\textwidth) epsfig ///
    as(eps pdf)

/***

\end{document}
***/

Option as(eps pdf) has been added in the example because the LaTeX-to-PDF compiler used for this website does not support EPS. The effect of as(eps pdf) is that an EPS as well as a PDF is produced and that the file suffix is omitted in the \epsfig command. In this case, it will depend on the employed compiler whether the EPS or the PDF is used for the final document.