\documentclass[article,oneside]{memoir} \usepackage[T1]{fontenc} \usepackage{mathptmx,upquote,alltt} \IfFileExists{helvet.sty}{\usepackage[scaled=0.92]{helvet}}{\relax} \IfFileExists{couriers.sty}{\usepackage[scaled=0.95]{couriers}}{\relax} \usepackage{float,graphicx,xspace,framed,xcolor} \definecolor{shadecolor}{rgb}{0.97,0.97,0.97} \definecolor{lightblue}{rgb}{0.93,0.95,1.0} \definecolor{darkblue}{rgb}{0,0,0.6} \definecolor{darkred}{rgb}{0.6,0,0} \setlength{\parindent}{0pt} \nonzeroparskip \usepackage[ bookmarks=true, hyperindex = true, pdfpagemode = useoutlines, pdfpagelabels = true, plainpages = false, colorlinks = true, linkcolor=darkblue, filecolor=darkblue, citecolor=darkblue, urlcolor=darkblue, ]{hyperref} \usepackage{attachfile} \usepackage{memhfixc} \raggedbottom \hyphenation{StatRep} \chapterstyle{article} \DeclareTextFontCommand{\Code}{\ttfamily} \newcommand*{\StatRep}{\textsf{StatRep}\xspace} \newcolumntype{P}[1]{>{\raggedright\arraybackslash}p{#1}} \setlength{\FrameSep}{1pt} \title{The \StatRep System for Reproducible Research} \author{Tim Arnold and Warren F. Kuhfeld\\SAS Institute Inc.} \makeindex \begin{document} \maketitle \tableofcontents*%\listoftables\listoffigures %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \part{User's Guide} \chapter{Synopsis} The \StatRep system consists of a \LaTeX\ package and a suite of SAS macros that support SAS users who want to create documents with reproducible results. The \LaTeX\ package provides two environments and two tags that work together to display your SAS code and results and to generate the SAS program that produces those results. The two environments (\Code{Datastep} and \Code{Sascode}) display SAS code. The two tags (\cs{Listing} and \cs{Graphic}) display SAS output. The generated SAS program includes calls to the \StatRep macros that use the SAS Output Delivery System (ODS) document to capture the output as external files. These SAS macros are included in the package file \Code{statrep\_macros.sas}. The \StatRep package is available at \url{http://support.sas.com/StatRepPackage} By default, \StatRep displays SAS output tables as generated by the ODS Listing destination; that is, the output tables are displayed as plain text. However, you can specify that \StatRep display \LaTeX\ outputs, generated by SAS, instead (see appendix \ref{latexoutput} for details). You can use \StatRep with a standalone SAS installation on your PC, or you can use it in conjunction with \textbf{SAS Studio} and \textbf{SAS University Edition} (see appendix \ref{sasstudio} for details). Bundled with the \StatRep package is the \Code{longfigure} package for multipage figures. You can use the \Code{lonfigure} package in other \LaTeX\ documents. The \StatRep system was designed to be flexible enough to support serious publishing systems. It can handle many different situations and it is very customizable. This document covers all aspects of \StatRep; however, for most users, the \textit{User's Guide} portion will suffice. For those who need more advanced techniques and customization, please see the \textit{Reference Manual}. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Introduction} At the end of a research project, one of the most difficult tasks remains: documentation. The task is especially difficult with computational research because you must ensure that the displayed program code works as expected and exactly produces the displayed output. The \StatRep package, a single-source document system, is an open-source software project that you can use for your own research documentation to ensure that the results you display can easily be reproduced by your readers. The \StatRep package is based on the \LaTeX\ typesetting system. You write your paper using both the usual \LaTeX\ markup and the customizations and SAS macros that this package provides. The system reads the code and markup from the single source (your document) and creates a SAS program. This automatically generated SAS program produces the results that are displayed in your document. Comparable projects such as Sweave (Leisch 2002) and SASweave (Lenth 2007) address the problem of reproducibility through the use of a special intermediate language. Although similar in spirit to those systems, \StatRep differs in that it is a normal \LaTeX\ package; no special steps are needed to create the \LaTeX\ file or the SAS program. In addition, \StatRep provides both a complete, customizable system for automatic handling of multiple outputs and page breaking and an easy-to-use, flexible method for output selection. When you use the \StatRep \LaTeX\ package, you follow a four-step process to create an executable document that enables you to create reproducible research results: \begin{enumerate} \item Create your \LaTeX\ source file so that it contains your text, data, and SAS code. \item Compile the document with pdf\LaTeX. You can use a LaTeX-aware editor such as \TeX works, or you can use the command-line command \Code{pdflatex}. This step generates the SAS program that is needed to produce the results. If the name of your document is \textit{myarticle.tex}, the name of the generated SAS program is \textit{myarticle\_SR.sas} by default. \item Execute the SAS program to capture your output. During execution of the SAS program, for each code block in your document, SAS creates a SAS Output Delivery System (ODS) document that contains the resulting output. For more information about ODS documents, see the \textit{SAS Output Delivery System User's Guide}. For each output request (the included \cs{Listing} and \cs{Graphic} tags) in your document, SAS replays the specified output objects to external files. All of your requested output is generated and captured when you execute the generated SAS program. \item Recompile the document with pdfLaTeX. This step compiles your document to PDF, this time including the SAS results that are generated in the preceding step. In some cases listing outputs may not be framed properly after this step. If your listing outputs are not framed properly, repeat this step so that LaTeX can remeasure the listing outputs. \end{enumerate} When you need to make a change in your data or SAS code, you make the change in one place (the \LaTeX\ source file) and repeat steps 2 through 4. Your changes are automatically displayed in your code and in your results. You perform the steps only as needed---when you change your data or code. You can share your \LaTeX\ source with colleagues and be sure that your results are reproducible. Any SAS user can reproduce your analysis with your \LaTeX\ document and the supplemental files that are described in this manual. \section{Requirements for the \StatRep Package} \index{package!requirements} To use the \StatRep package, you need SAS 9.2 or later, the \LaTeX\ typesetting system (the pdf\LaTeX\ typesetting engine must be version 1.30 or later), and the \StatRep package itself. For complete step-by-step instructions for installation, see appendix \ref{install}. \section{Package Usage} \index{package!usage} To use the \StatRep package, include it in your document preamble after you declare the \Code{documentclass}. Figure \ref{fig:usage} displays an example of how you can use the \StatRep package. \begin{figure}[H] \begin{shaded} \begin{verbatim} \documentclass{book} \usepackage[figname=output,resetby=chapter]{statrep} \end{verbatim}% \end{shaded} \caption{Example of Using the \StatRep Package}\label{fig:usage} \end{figure} The \StatRep package supports the following options:\index{package!options} \begin{itemize} \item \Code{color} specifies color support for SAS output tables. This option is only used in conjunction with the ODS LaTeX tagset (see appendix \ref{latexoutput}). \item \Code{generate} specifies whether a SAS program is generated at compile time. \index{generate option} It can have a value of \Code{true} or \Code{false}; the default is \Code{true}. \item \Code{figname=} specifies the name of a \LaTeX\ counter that is used for numbering outputs\index{figname option}. The default is \Code{figure}. If you specify a value for the \Code{figname} option for which no counter exists, a counter is created.\index{figure names}\index{figname option} \item \Code{resetby=} specifies that the counter for output numbering be reset with each change in the specified counter value. For example, if \Code{resetby=chapter}, all output numbering is reset when the chapter value changes.\index{resetby= option} \end{itemize} The options \Code{figname=} and \Code{resetby=} are not used directly by the \StatRep package but are passed to the \Code{longfigure} package, which is provided with the \StatRep package. The \Code{longfigure} package supports display and page breaking within a stream of outputs, and it can be used independently of the \StatRep package. See chapter{longfigure} for more information. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Getting Started}\label{gs} This section provides a simple example of how you can use the \StatRep package to produce a document with reproducible results. You can follow along with the actual code: extract this \textattachfile[color=0 0 0.6]{example.tex}{example \LaTeX\ file} that contains the code in this section if your PDF viewer supports file annotations. Two code environments (\Code{Datastep}, shown in Figure \ref{fig:d1}, and \Code{Sascode}, shown in Figure \ref{fig:s1}) and two output tags (\cs{Listing} and \cs{Graphic}, shown in Figure \ref{fig:slg}) are used to generate a SAS program that produces the necessary output files. The code from the \Code{Datastep} environment is passed unchanged to the generated SAS program.\index{Datastep environment} \begin{figure}[H] \begin{snugshade} \begin{verbatim} \begin{Datastep} proc format; value $sex 'F' = 'Female' 'M' = 'Male'; data one; set sashelp.class; format sex $sex.; run; \end{Datastep} \end{verbatim} \end{snugshade} \caption{Example of \texttt{Datastep} Environment}\label{fig:d1} \end{figure} The code in the \Code{Sascode} environment is parsed by the \StatRep package before it is written to the generated SAS program.\index{Sascode environment} \begin{figure}[H] \begin{snugshade} \begin{verbatim} \begin{Sascode}[store=class] proc reg; model weight = height age; run; \end{Sascode} \end{verbatim} \end{snugshade} \caption{Example of \texttt{Sascode} Environment}\label{fig:s1} \end{figure} The \cs{Listing} and \cs{Graphic} tags convey information to \LaTeX\ and to SAS. The tags specify the names of the output files to insert into the document and the captions for the output. Additionally, the tags specify the names of the output files to create and they can specify which ODS objects to capture. In this example, no objects are specified so all objects are captured. \index{Listing tag}\index{Graphic tag}% \begin{figure}[H] \begin{snugshade} \begin{verbatim} \Listing[store=class, caption={Regression Analysis}]{rega} \Graphic[store=class, scale=0.9, caption={Graphs for Regression Analysis}]{regb} \end{verbatim} \end{snugshade} \caption{Example of \texttt{Listing} and \texttt{Graphic} Tags}\label{fig:slg} \end{figure} Figure \ref{fig:sgp} shows the SAS code that is generated from the preceding \LaTeX\ source when you compile the document. \begin{figure}[H] \begin{framed} \begin{snugshade} {\hfil\emph{generated from }\textbf{Datastep Block}\hfil} \begin{verbatim} proc format; value $sex 'F' = 'Female' 'M' = 'Male'; data one; set sashelp.class; format sex $sex.; run; \end{verbatim} \end{snugshade} \begin{snugshade} {\hfil\emph{generated from }\textbf{Sascode Block}\hfil} \begin{verbatim} %output(class) proc reg; model weight = height age; run; %endoutput(class) \end{verbatim} \end{snugshade} \begin{snugshade} {\hfil\emph{generated from }\textbf{Listing \& Graphic Tags}\hfil} \begin{verbatim} %write(rega,store=class,type=listing) %write(regb,store=class,type=graphic) \end{verbatim} \end{snugshade} \end{framed} \caption{Generated SAS Code}\label{fig:sgp} \end{figure} When you generate the SAS program by compiling your \LaTeX\ document, the lines in the \Code{Datastep} environment are passed unchanged to the program and the lines in the \Code{Sascode} environment are wrapped between two SAS macros (\Code{\%output} and \Code{\%endoutput}), whose definitions accompany this package (\texttt{statrep\_macros.sas}). \index{statrep\_macros.sas}\index{SAS macros!output}\index{SAS macros!endoutput} The macros and their options are discussed in detail in section \ref{macros}. The \cs{Listing} tag results in a call to the \Code{\%write} macro that selects all notes and tables from the ODS document.\index{SAS macros!write} The \cs{Graphic} tag results in a call to the \Code{\%write} macro that selects all graphs from the ODS document. When you execute the generated SAS program that is displayed in Figure \ref{fig:sgp}, the SAS results created in the \Code{Sascode} block are contained in the ODS document \Code{class}. The \Code{\%write} macro writes the requested results from the ODS document to the specified external files. When you compile your \LaTeX\ document again, the \cs{Listing} and \cs{Graphic} tags insert the requested SAS results, handling page breaks automatically. The first listing in the example document is shown in Figure \ref{exfig}. \definecolor{shadecolor}{rgb}{0.93,0.95,1.0} \begin{figure}[H] \caption{Example listing output}\label{exfig} \begin{snugshade} \centering \includegraphics[width=0.8\textwidth]{images/example_output} \end{snugshade} \end{figure} \definecolor{shadecolor}{rgb}{0.97,0.97,0.97} By default, \StatRep generates listing output from the SAS ODS Listing destination. The preceding figure provides an example of how the SAS output is displayed in your LaTeX document. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Syntax} The \StatRep package provides two environments and two tags that work together to display your SAS code and results and generate the SAS program that produces those results. The environments: \begin{itemize} \item The \Code{Datastep} environment contains SAS code blocks that produce no output. Its purpose is to read in data. \item The \Code{Sascode} environment contains SAS code that generates output to be captured. It supports line-based commands to identify code lines that should only be displayed, only passed to the generated program, or both displayed and passed to the generated program. \end{itemize} The tags: \begin{itemize} \item The \cs{Listing} tag provides information to the generated program about which tabular SAS output should be captured. It also provides information to \LaTeX\ about how that output should be displayed. \item The \cs{Graphic} tag provides information to the generated program about which graphical SAS output should be captured. It also provides information to \LaTeX\ about how that output should be displayed. \end{itemize} The environments and tags are described in detail in the following sections. \section{Code Environments} \subsection{Datastep Environment}\index{Datastep environment} The purpose of the \Code{Datastep} environment is to read in data. It produces no SAS results. The \Code{Datastep} contents are passed unchanged to the generated program. The \Code{Datastep} block is indented by three spaces in the PDF file. You can adjust the amount that the block is indented; see section \ref{custom} for details. The block indent is provided automatically so that your data and program lines can begin in the first column in your \LaTeX\ source. Because you begin the \Code{Datastep} data lines in the first column, formatted or column input statements will work correctly when pasted into a SAS session.\index{copy and paste}\index{interactive SAS session} Although the purpose of the \Code{Datastep} environment is to read in data, \index{reading data}% it can contain any SAS code that does not generate output to be captured. Additional statements typically include TITLE and OPTIONS statements and PROC FORMAT steps. See Figure \ref{fig:sd2} on page \pageref{fig:sd2} for an example. Table \ref{dsopt} summarizes the \Code{Datastep} environment options. \index{Datastep environment!options} \index{program option}\index{display option}\index{first= option}\index{last= option}% \index{fontsize= option} \begin{table}[H] \caption{Commonly Used \Code{Datastep} Environment Options}\label{dsopt} \begin{tabular}{lP{3.75in}} \hline \textbf{Option} & \textbf{Action} \\ \hline & By default, all lines are displayed and written to the program. \\[0.5\baselineskip] \Code{program} & Specifies that all lines in the environment be written to the generated program only (that is, no lines are displayed). This option is useful when you need to produce a data set that is not central to the topic being discussed and does not need to be displayed. \\[0.5\baselineskip] \Code{display} & Specifies that all lines in the environment be displayed only (that is, no lines are written to the program). This option is useful when you need to show code fragments that will not run as is or example code that is not needed for later output generation. A \Code{Datastep} environment that specifies the \Code{display} option is similar to a plain \Code{verbatim} environment except that it is automatically indented when displayed. \\[0.5\baselineskip] \Code{first=\textit{n}} & Specifies that the first \textit{n} lines in the environment be displayed. The option affects only the displayed code block. This option is useful when you have many data lines that do not need to be displayed, but that must be available to the program. After the \textit{n}th line is displayed, the following text line is written in the displayed code block: \par\texttt{... more data lines ...}\par% You can specify different text to be used; see section \ref{custom} for details. \\[0.5\baselineskip] \Code{last=\textit{m}} & Specifies that the last \textit{m} lines in the environment be displayed. The option affects only the displayed code block. This option is used in conjunction with the \Code{first=} option to show the ending lines of the \Code{Datastep} environment. Without the \Code{first=} option, the \Code{last=} option has no effect. \\[0.5\baselineskip] \Code{fontsize=} & Specifies the \LaTeX\ font size used to display the code block. For exampe, \Code{fontsize=small} or \Code{fontsize=footnotesize}. \\ \hline \end{tabular} \end{table} See the section \titleref{dsex} for an example. \subsection{Sascode Environment}\index{Sascode environment} The purpose of the \Code{Sascode} environment is to generate output. In addition to the environment options, it supports line commands that enable you to specify certain lines as display-only or program-only. The \Code{Sascode} environment is parsed for line commands, and the appropriate lines are passed to the program and displayed. The displayed code block is indented by three spaces. You can adjust the amount the block should be indented; see section \ref{custom} for details.\index{display option} The block indent is provided automatically so that your program lines can begin in the first column in your \LaTeX\ source. Because all line commands are valid SAS statements, you can copy \Code{Sascode} blocks and paste them directly into a SAS session.\index{copy and paste}\index{interactive SAS session} Table \ref{scopt} summarizes the \Code{Sascode} environment options. \index{Sascode environment!options}\index{store= option}\index{program option}% \index{display option}\index{fontsize= option}% \begin{table}[H] \caption{Commonly Used \Code{Sascode} Environment Options}\label{scopt} \begin{tabular}{lP{3.75in}} \hline \textbf{Option} & \textbf{Action} \\ \hline & By default, all lines are displayed and written to the program. \\[0.5\baselineskip] \Code{store=} & Specifies the name of the ODS document to contain the SAS output. \\[0.5\baselineskip] \Code{program} & Specifies that all lines in the environment be written to the program only (that is, no lines are displayed). This option is useful when you need to execute code that is not central to the topic being discussed and need not be displayed. \\[0.5\baselineskip] \Code{display} & Specifies that all lines in the environment be displayed only (that is, no lines are written to the program). This option is useful when you need to show example code fragments that will not run as is or that are not needed for later output generation. A \Code{Sascode} environment that specifies the \Code{display} option is similar to a plain \Code{verbatim} environment except that it is automatically indented when displayed. \\[0.5\baselineskip] \Code{fontsize=} & specifies the \LaTeX\ font size used to display the code block (for example, \Code{fontsize=small} or \Code{fontsize=footnotesize}). \\ \hline \end{tabular} \end{table} The \Code{Sascode} environment also supports a finer degree of control with line-based commands to identify lines that should be only displayed or only passed to the generated program. Table \ref{lcmd} summarizes the line commands you can use in the \Code{Sascode} environment. \index{Sascode environment!line commands} \index{program line command}\index{display line command} \begin{table}[H] \caption{\Code{Sascode} Line Commands}\label{lcmd} \begin{tabular}{lP{3.5in}} \hline \textbf{Option} & \textbf{Action} \\ \hline \Code{\%* program} \textit{n} \Code{;} & The next \textit{n} lines are only written to the program and not displayed.\\[0.5\baselineskip] \Code{\%* display} \textit{n} \Code{;} & The next \textit{n} lines are only displayed and not written to the program.\\[0.5\baselineskip] \Code{\%*;} \textit{code line} & The current line is only written to the program and not displayed.\\ \hline \end{tabular} \end{table} The \Code{Sascode} environment is parsed for line commands before being written to the generated program file. See the sections \titleref{scex} and \titleref{scexlc} for examples. By using a combination of environment options and line commands, you have complete control over the displayed code and the generated program contents. \section{Outputs} \index{SAS ODS outputs}\index{Listing tag}\index{Graphic tag} The \cs{Listing} and \cs{Graphic} tags specify the outputs to be displayed. The purpose of the \cs{Listing} tag is to display tabular output and notes. The purpose of the \cs{Graphic} tag is to display graphical output. All figures are centered. If the figure width is narrower than the text block, the figure is centered with respect to the text block. Otherwise, the figure is centered with respect to the page. The \cs{Listing} and \cs{Graphic} tags support a set of options and have one mandatory argument, which specifies the filename prefix for the output to be generated and displayed. The prefix must be unique; otherwise the output from one example will overwrite another. Furthermore, the prefix must not end in a numeral so that the prefix name does not interfere with SAS-generated output file names. When SAS generates a set of files from one ODS selection, it follows a pattern: the first file that is generated is identical to the filename, the next file that is generated has the same name with a ``1'' appended to it, the next file has the same name with a ``2'' appended, and so on. The options supported by the \cs{Listing} and \cs{Graphic} tags are used by the \StatRep \LaTeX\ package and by the \StatRep SAS macros. The following table lists all options. Subsequent tables provide descriptions for each option and how it is used in LaTeX and in SAS. \begin{table}[H] \caption{Master List of Output Tag Options} \begin{tabular}{lll} \toprule \textbf{Option Name} & \textbf{Used by} & \textbf{Output Tag}\\ \midrule \Code{caption=} & LaTeX & Listing, Graphic \\ \Code{dest=} & LaTeX, SAS & Listing \\ \Code{dpi=} & SAS & Graphic \\ \Code{firstobj=} & SAS & Listing, Graphic \\ \Code{fontsize=} & LaTeX & Listing (ODS Listing destination) \\ \Code{height=} & SAS & Graphic \\ \Code{lastobj=} & SAS & Listing, Graphic \\ \Code{linesize=} & LaTeX, SAS & Listing (ODS Listing destination) \\ \Code{objects=} & SAS & Listing, Graphic \\ \Code{options=} & SAS & Listing, Graphic \\ \Code{pagesize=} & SAS & Listing \\ \Code{pattern=} & SAS & Listing, Graphic \\ \Code{scale=} & LaTeX & Graphic \\ \Code{store=} & LaTeX, SAS & Listing, Graphic \\ \Code{style=} & SAS & Listing (ODS LaTeX destination), Graphic \\ \Code{type=} & SAS & Listing, Graphic \\ \Code{width=} & LaTeX, SAS & Graphic \\ \bottomrule \end{tabular} \end{table} \subsection{Options Used by the \textsf{StatRep} \LaTeX\ Package} \index{Listing tag!options}\index{Graphic tag!options} The following options are used by the \StatRep \LaTeX\ package. \index{caption= option}\index{fontsize= option}\index{linesize= option}% \index{scale= option}\index{store= option}\index{width= option} \begin{description} \item[\Code{caption=}] specifies the caption to use for an output. \item[\Code{dest=}] specifies the ODS destination to use for generating the output. The default value is \Code{listing}. The other possible value is \Code{latex}, which specifies that Listing output be generated and displayed as LaTeX tables. \item[\Code{fontsize=}] specifies the \LaTeX\ font size to use to display an output (for example, \Code{fontsize=small} or \Code{fontsize=footnotesize}). \item[\Code{linesize=}] specifies the line size used to generate and display \Code{Listing} output. By default, the value is 80 columns. This specification lasts for the duration of this step. The current line size is restored at the end. Typical values are \Code{80}, \Code{96}, or \Code{120}. For extremely wide output tables, you can use the \Code{linesize} and \Code{fontsize} options together (for example, \Code{linesize=120} and \Code{fontsize=scriptsize}). The \Code{linesize} option affects how SAS captures the table. The \Code{fontsize} option specifies how \LaTeX\ displays the table.\index{linesize= option}% \index{fontsize= option}\index{wide output} \item[\Code{scale=}] specifies a factor by which to scale a \Code{Graphic} image. For example, specify \Code{scale=0.5} to scale the image to half its original size, or specify \Code{scale=2} to scale it to double its original size. \item[\Code{store=}] specifies the name of the ODS document that is created in a \Code{Sascode} environment. When you specify the \Code{store=} option, the \StatRep package adds the appropriate SAS macro calls to the generated program. \item[width=] specifies the width to generate and display \Code{Graphic} output The default is 6.4 inches, which is the standard width for ODS graphs. \end{description} \subsection{Options Passed to the \textsf{StatRep} SAS Macros}\label{sasopts} \index{SAS macro options} The \Code{store=}, \Code{linesize=}, and \Code{width=} options described in the previous section are passed to the \StatRep SAS macros. \index{dpi= option}\index{firstobj= option}\index{height= option}\index{lastobj= option} \index{linesize= option}\index{objects= option}\index{options= option} In addition, the following options are passed to the \StatRep SAS macros: \begin{description} \item[\Code{dest=}] specifies the ODS destination to use for generating the output. The default value is \Code{listing}. The other possible value is \Code{latex}, which specifies that Listing output be generated and displayed as LaTeX tables. \item[\Code{dpi=}] specifies dots per inch (DPI) to use in generating graphs. The default is \Code{dpi=300}. A typical alternative is \Code{dpi=100}. \item[\Code{firstobj=}] specifies the first data object to capture in an output stream. All objects after and including the specified object are displayed, up to the final object (or optionally up to the object specified in \Code{lastobj=}). You can use \Code{options=skipfirst} to begin with the object after the one specified in \Code{firstobj=}. See section \ref{selection} for details. \item[\Code{height=}] specifies the height of graphs. The default is 0.75 times the width. \item[\Code{lastobj=}] specifies the last data object to capture in an output stream. All objects starting with the first object (or optionally the object specified in \Code{firstobj=}) are displayed up to and including the specified object. You can use \Code{options=skiplast} to end with the object before the one specified in \Code{lastobj=}. \item[\Code{linesize=}] specifies the line size used to generate and display \Code{Listing} output. By default, the value is 80 columns. This specification lasts for the duration of this step. The current line size is restored at the end. Typical values are \Code{80}, \Code{96}, or \Code{120}. \item[\Code{objects=}] specifies a space-separated list of ODS objects to capture in an output stream. The names that are used for selection come from the ODS document. If you specify \Code{objects=}, then you can also specify object breaking rules (where page breaks can occur). See section \ref{selection} for details. \item[\Code{options=}] specifies binary options. Specify one value or a space-separated list of values (for example, \Code{options=skipfirst skiplast}). You can specify the following values (the default is \Code{options=autopage}): \begin{description} \item[\Code{autopage}] specifies that the first \cs{Listing} command or \Code{\%write} macro start a new output stream with titles, procedure titles, and so on. Page breaks also occur at other places where the procedure explicitly sets a page break. The \Code{autopage} value is the default. See also the \Code{nopage} and \Code{newpage} values. \index{autopage option} \item[\Code{graph}] specifies that only graphs be selected. You can alternatively specify \Code{type=graph}.\index{graph option} \item[\Code{list}] specifies that the contents of the ODS document be listed in the SAS log. This value does not run PROC DOCUMENT to replay the output.\index{list option} \item[\Code{newpage}] specifies that SAS force a new page for the first object. \index{newpage option} \item[\Code{nopage}] suppresses page breaks.\index{nopage option} \item[\Code{onebox}] groups all tables, notes, reports, and so on into a single piece of SAS output. You cannot specify this option to group graphs. See section \ref{selection} for more information about grouping.\index{onebox option} \item[\Code{skipfirst}] modifies the \Code{firstobj=} option so that the first object in the list is not selected. This enables you to select all objects after the one specified in \Code{firstobj=}.\index{skipfirst option} \item[\Code{skiplast}] modifies the \Code{lastobj=} option so that the last object in the list is not selected. This enables you to select all objects before the one specified in \Code{lastobj=}.\label{skiplast}\index{skiplast option} \item[\Code{table}] selects all objects (tables, notes, reports, and so on) except graphs. You can alternatively specify \Code{type=listing}.\index{table option} \end{description} \item[\Code{pagesize=}] specifies the page size. The default is the page size currently in effect. This specification lasts for the duration of this step. The current page size is restored at the end.\index{pagesize= option} If you have not changed the page size, the default page size set by the \StatRep package is 500. This large page size is the default so that output is generated with minimal new pages caused by page boundaries. For large tables, you can specify a smaller page size to force more page breaks. See section \ref{custom} for information about how to change the \StatRep default. See section \ref{large} for information about how to use the \Code{pagesize=} option with large tables. \item[\Code{pattern=}] provides an optional and additional selection criterion. Specify part of a path (for example, a group name).\index{pattern= option} Only objects whose name includes the specified value are selected. \item[\Code{store=}] specifies the name of the ODS document that is created in a \Code{Sascode} environment. When you specify the \Code{store=} option, the \StatRep package adds the appropriate SAS macro calls to the generated program.\index{store= option} \item[\Code{style=}] specifies the ODS style to use in generating output. The default is \mbox{\Code{style=Statistical}}. You can change the default style (for example, to \Code{HTMLBlue}) by inserting the following line into a \Code{Sascode} or \Code{Datastep} environment:\index{style= option} \begin{snugshade} \begin{verbatim} *; %let defaultstyle=HTMLBlue; \end{verbatim} \end{snugshade} This option affects ODS graphs only when used in a \cs{Graphic} tag. You can specify this option in the \Code{\%output} macro to set the style for GRSEG graphs (graphs that are produced by legacy SAS/GRAPH procedures such as the GPLOT, GMAP, and GCHART procedures). GRSEG graphs are stored in catalogs and cannot be changed after they are generated. In contrast, style, DPI, and so on for ODS graphis can be changed after the graph is initially created. See section \ref{grseg} for more information. \item[\Code{type=\emph{listing}|\emph{graph}}] specifies that only listings or only graphs be selected. You can alternatively specify \Code{options=table} or \Code{options=graph}. \item[\Code{width=}] specifies the width to generate and display \Code{Graphic} output The default is 6.4 inches, which is the standard width for ODS graphs. \end{description} \chapter{Examples} \section{Using the Datastep Environment}\label{dsex} \index{Datastep environment} Figure \ref{fig:sd2} displays an example \Code{Datastep} environment. The left margin for the environment is in the first column, which is where the data lines themselves begin. This ensures that the variables will be read correctly. \begin{figure}[H] \begin{snugshade} \begin{verbatim} \begin{Datastep}[first=9, last=3] title 'Probit Analysis, Newspaper Survey'; proc format; value subscrib 1 = 'accept' 0 = 'reject'; run; data news; input sex $ 1-6 age 12-13 subs 18 ; datalines; Female 35 0 Male 45 1 Female 51 0 Male 54 1 Female 35 0 Female 48 0 Male 46 1 Female 46 1 Male 38 1 Male 49 1 Male 50 1 Female 47 0 Female 39 0 Female 45 0 Male 39 1 Female 39 0 Female 52 1 Male 58 1 Female 32 0 Female 35 0 ; \end{Datastep} \end{verbatim} \end{snugshade} \caption{\texttt{Datastep} Environment with Options}\label{fig:sd2} \end{figure} In Figure \ref{fig:sd2}, the options to the \Code{Datastep} environment specify that only a portion of the code block be displayed. All lines in the environment are written to the generated program. The option \Code{first=9} specifies that the displayed code block contain the TITLE, the PROC FORMAT code, and the DATA step block through the second line of data (the first nine input lines). After these lines, the following text is displayed:\par\texttt{... more data lines ...} The option \Code{last=3} specifies that the displayed code block will contain the last three lines of the environment. Figure \ref{fig:sd3} shows the display resulting from the preceding \Code{Datastep} environment. \begin{figure}[H] \begin{snugshade} \begin{verbatim} title 'Probit Analysis, Newspaper Survey'; proc format; value subscrib 1 = 'accept' 0 = 'reject'; run; data news; input sex $ 1-6 age 12-13 subs 18 ; datalines; Female 35 0 Male 45 1 ... more data lines ... Female 32 0 Female 35 0 ; \end{verbatim} \end{snugshade} \caption{Displayed \texttt{Datastep} Environment with Options}\label{fig:sd3} \end{figure} \section{Using the Sascode Environment}\label{scex}\index{Sascode environment} Figure \ref{sb} displays an example \Code{Sascode} environment. \begin{figure}[H] \begin{snugshade} \begin{verbatim} \begin{Sascode}[store=mdoc] proc reg data=h38 plots=predictions(X=Year); model Population = Year Yearsq; quit; \end{Sascode} \end{verbatim} \end{snugshade} \caption{Sascode Block}\label{sb} \end{figure} The code displayed in Figure \ref{sb} contains SAS code that performs a regression analysis. Because no line commands are given, the code block is written as-is to the generated SAS program, as shown in Figure \ref{figsb}. \begin{figure}[H] \begin{snugshade} \begin{verbatim} %output(mdoc); proc reg data=h38 plots=predictions(X=Year); model Population = Year Yearsq; quit; %endoutput(mdoc); \end{verbatim} \end{snugshade} \caption{Generated Code from Sascode Block }\label{figsb} \end{figure} \section{Using the Sascode Environment with Line Commands}\label{scexlc} \index{Sascode environment!line commands} Figure \ref{sblc} displays an example \Code{Sascode} environment that contains line commands. \begin{figure}[H] \begin{snugshade} \begin{verbatim} \begin{Sascode}[store=mdoc] * program 2; libname mylib 'c:/mylibs'; filename in1 'h38.ssp'; * display 2; libname mylib 'path to your library directory'; filename in1 'path to data directory/h38.ssp'; proc reg data=mylib.h38 plots=predictions(X=Year); model Population = Year Yearsq; quit; \end{Sascode} \end{verbatim} \end{snugshade} \caption{Sascode Block with Line Commands}\label{sblc} \end{figure} The code displayed in Figure \ref{sblc} contains two line commands that delineate two specifications for the \Code{libname} and \Code{filename} SAS statements. The line command \Code{\mbox{\%* program 2;}} specifies that the location-specific definitions be passed to the generated program, as shown in Figure \ref{fig:gsblc}. \begin{figure}[H] \begin{snugshade} \begin{verbatim} output(mdoc); libname mylib 'c:/mylibs'; filename in1 'h38.ssp'; proc reg data=mylib.h38 plots=predictions(X=Year); model Population = Year Yearsq; quit; endoutput(mdoc); \end{verbatim} \end{snugshade} \caption{Generated Code from Sascode Block with Line Commands}\label{fig:gsblc} \end{figure} The line command \Code{\%* display 2;} in Figure \ref{sblc} specifies that the generic version of the \Code{libname} and \Code{filename} statements be displayed, as shown in Figure \ref{dsblc}. \begin{figure}[H] \begin{snugshade} \begin{verbatim} libname mylib 'path to your library directory'; filename in1 'path to data directory/h38.ssp'; proc reg data=mylib.h38 plots=predictions(X=Year); model Population = Year Yearsq; quit; \end{verbatim} \end{snugshade} \caption{Displayed Code from Sascode Block with Line Commands}\label{dsblc} \end{figure} \section{Selecting ODS Objects by Default}\label{odsdefault} \index{ODS object selection} When you use the \cs{Graphic} tag, all graph objects are automatically selected. When you use the \cs{Listing} tag, all non-graph objects such as tables and notes are automatically selected. When you use the \Code{\%write} macro, you can specify the \Code{options=graph} option to select graphs or the \Code{options=table} to select tables and notes. The following statements select all of the tables for the \cs{Listing} display and all of the graphs for the \cs{Graphic} display: \begin{figure}[H] \begin{snugshade} \begin{verbatim} \begin{Sascode}[store=docgs1] ods graphics on; proc corresp data=PhD short; var y1973-y1978; id Science; run; \end{Sascode} \Listing[store=docgs1, caption={Inertia and Chi-Square Decomposition}]{crsi1a} \Graphic[store=docgs1, caption={Correspondence Analysis of Ph.D. Data}]{crsi1b} \end{verbatim} \end{snugshade} \caption{Object Selection with the \cs{Listing} and \cs{Graphic} Tags}\label{optionoption} \end{figure} The log information tables display the selected objects for each block of output. The first information table corresponds to the ODS selection that is produced by the \cs{Listing} tag. All ODS objects of type `Table' are selected (more precisely, all objects that are not of type `Graph'). Each object is contained in its own selection group, so a page break might occur between any of the tables. \begin{figure}[H] \begin{snugshade} \begin{verbatim} Objects Type Status Group Corresp.Inertias Table Selected 1 Corresp.Rows.RowCoors Table Selected 2 Corresp.Columns.ColCoors Table Selected 3 Corresp.Configuration.ConfigPlot Graph . \end{verbatim} \end{snugshade} \caption{SAS Log Information Table from the Listing Tag}\label{loglstinfo} \end{figure} The second information table corresponds to the ODS selection that is produced by the \cs{Graphic} tag. The single ODS object of type `Graph' is selected. \begin{figure}[H] \begin{snugshade} \begin{verbatim} Objects Type Status Group Corresp.Inertias Table . Corresp.Rows.RowCoors Table . Corresp.Columns.ColCoors Table . Corresp.Configuration.ConfigPlot Graph Selected 1 \end{verbatim} \end{snugshade} \caption{SAS Log Information Table from the Graphic Tag}\label{loggraphinfo} \end{figure} \section{Specifying and Capturing ODS Objects by Name} \index{ODS object selection} To capture particular ODS objects or ODS group output, you must specify the appropriate names in the \cs{Listing} tag, the \cs{Graphic} tag, or the \Code{\%write} macro. The options that support specific ODS names are the \Code{pattern=}, \Code{firstobj=}, \Code{lastobj=}, or \Code{objects=} options. If an object appears more than once in a particular ODS document (which typically means in one \Code{Sascode} block), you must specify additional name levels to differentiate the objects. The log information table displays the fully qualified ODS names; you use the information from the log to specify the appropriate name for the ODS objects to capture. For example, if there are multiple residual panels, you must specify the additional level to select a particular ODS object. \begin{snugshade} \begin{verbatim} objects=residualplot \end{verbatim} \end{snugshade} \begin{snugshade} \begin{verbatim} objects=residualplot\#2 \end{verbatim} \end{snugshade} \textbf{Note:} When you have a pound character (\#) in a pattern or object name, you must escape it in \LaTeX\ tags. The pound character is a special \LaTeX\ control character and must be escaped with a backslash. In other words, specify \Code{Group\textbackslash{}\#2} instead of \Code{Group\#2} in a \LaTeX\ tag. Do not escape the \# when you use the \Code{\%write} macro. Comparisons are not case sensitive. For example, if you specify \Code{pattern=fit}, the following objects will be selected if they occur in the output stream: \begin{snugshade} \begin{verbatim} Fit.Population.ANOVA MODEL1.Fit.Population.ANOVA Reg.MODEL1.Fit.Population.ANOVA reg#1.model1#1.fit#1.population#1.anova#1 reg#1.model1.fit.population#1.anova#1 reg.model1.fit.population.anova \end{verbatim} \end{snugshade} Typically\footnote{When deciding on names to specify, be sure to consult the table of names from the ODS document that appears in the SAS log. It contains the proper pattern of \# characters. See Figure \ref{loginfo} for an example.}, you need only to specify the last level of an ODS name. For example, for one model and one ANOVA table, all of the following specifications for the ANOVA object are equivalent. \begin{snugshade} \begin{verbatim} anova ANOVA ANOVA\#1 Fit.Population.ANOVA MODEL1.Fit.Population.ANOVA Population.ANOVA Reg.MODEL1.Fit.Population.ANOVA reg.model1.fit.population.anova reg\#1.model1.fit.population\#1.anova\#1 reg\#1.model1\#1.fit\#1.population\#1.anova\#1 \end{verbatim} \end{snugshade} When you run the SAS program that is generated by the \StatRep package, the SAS log contains a table with information about each ODS object. For example, Figure \ref{capturelist} shows a \Code{Sascode} environment that is parsed and written to the generated SAS program when the \LaTeX\ document is compiled. \begin{figure}[H] \begin{snugshade} \begin{verbatim} \begin{Sascode}[store=Ex31] proc probit data=news; class subs sex; model subs=sex age / d=logistic itprint; run; \end{Sascode} \Listing[store=Ex31, objects=ClassLevels IterHistory ModelInfo LastGrad LastHess ParameterEstimates, caption={Logistic Regression of Subscription Status}]{prb31a} \end{verbatim} \end{snugshade} \caption{Example of Capturing Listing Output}\label{capturelist} \end{figure} The \cs{Listing} tag results in a call to the \Code{\%write} macro in the automatically generated SAS program. When you execute the program, the \Code{\%write} macro generates the log information table shown in Figure \ref{loginfo}. \begin{figure}[H] \begin{snugshade} \begin{verbatim} Objects Type Status Group Probit.IterHistory Table Selected 1 Probit.ModelInfo Table Selected 2 Probit.NObs Table . Probit.ClassLevels Table Selected 3 Probit.ParmInfo Table . Probit.ResponseProfile Table . Probit.Note Note . Probit.LastGrad Table Selected 4 Probit.LastHess Table Selected 5 Probit.ConvergenceStatus Table . Probit.Type3Analysis Table . Probit.ParameterEstimates Table Selected 6 \end{verbatim} \end{snugshade} \caption{SAS Log Information Table}\label{loginfo} \end{figure} The table of information displays the fully qualified name for each generated ODS object, its type, whether it is selected, and its selection group. Page breaks can occur only between selection groups. You can control the grouping as described in the section \ref{pagebreak} on page \pageref{pagebreak}. For example, if you specify \Code{LastGrad LastHess} as \Code{}, the two tables would be in the same group. The order in which objects are created is determined by the order in which they are generated, not the order in which they are specified in the \Code{objects=} option. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \part{Reference Manual} \chapter{Overview} The preceding pages should provide the information to use the package in most scenarios. For more in-depth descriptions and methods for customization, see the following chapters. \begin{description} \item[Customizing \StatRep] describes several hooks for customizing the package and setting system-wide defaults. \item[About the Program Preamble] provides an overview of how the \StatRep package works with the SAS macros; a special file (the program preamble) provides a method of communication between the two. \item[Two Methods of Writing] describes how you can bypass the automatic code generation and use the \StatRep SAS macros directly. \item[\StatRep SAS Macros] describe in detail each SAS macro in the \StatRep package. You can use these macros yourself for maximum flexibility in creating a custom \StatRep document. \item[ODS Object Selection] describes how you can use options in the \cs{Listing} and \cs{Graphic} tag to specify exactly what output you want to display. \item[ODS Graphics] describes differences between ODS graphics and GRSEG graphics. \end{description} \chapter{Customizing \StatRep}\label{custom} \index{customizing}\index{configuration} You can modify the configuration file \Code{statrep.cfg} to change the following settings used by the \StatRep package. See section \ref{secdefaults} for more information about macro variable defaults. \begin{description} \item[\cs{SRcaptionfont}] specifies the font for the output captions. The default is \cs{sffamily} (\textsf{sans serif}). \index{caption font} \item[\cs{SRcaptioncontinuedfont}] specifies the font for the \Code{continued} name for outputs that break across pages. The default is \cs{sffamily}\cs{itshape} (\textsf{\textit{sans serif, italic}}). \item[\cs{SRcontinuedname}] specifies the name that indicates that an output block is continued. The name is used when an output stream breaks across a page. The default is \Code{continued}. \item[\cs{SRdefaultdests}] specifies the default ODS Destination for tabular outputs. The default is \Code{listing}. You can specify \Code{latex} to produce SAS-generated LaTeX tabular output. See appendix \ref{latexoutput} for details. \index{LaTeX output} \item[\cs{SRdpi}] specifies the default dots per inch (DPI) for SAS to use in generating graphical output. The default is \Code{300}. \index{dpi} \item[\cs{SRgraphicdir}] specifies the name of the directory that contains the SAS generated graphical output files. The default is \Code{png}. \index{graphic directory} \item[\cs{SRgraphtype}] specifies the format of the SAS generated graphical output. You can specify either \Code{png} or \Code{pdf}. The default is \Code{png}. \index{graphics type}\index{PNG graphics}\index{PDF graphics} \item[\cs{SRlatexdir}] specifies the name of the directory that contains the SAS generated LaTeX tabular output. The default is \Code{tex}. See appendix \ref{latexoutput} for details. \item[\cs{SRlatexstyle}] specifies the ODS style for SAS to use to generate LaTeX tabular output. The default is \Code{statrep}, a monochromatic style based on the \Code{statistical} ODS style. See appendix \ref{latexoutput} for details. \item[\cs{SRodsgraphopts}] specifies a string that is passed as ODS GRAPHICS statement options. For a complete explanation of all available options, see the documentation of the ODS GRAPHICS statement in \textit{SAS Output Delivery System: User's Guide}. \index{ODS graphics options} \item[\cs{SRintertext}] specifies the text to insert in \Code{Datastep} environments that specify the \Code{first=} option. The default is \Code{\mbox{... more data lines ...}} \item[\cs{SRlinesize}] specifies the default line size to use in generating tabular output and centering it for display. The default is \Code{80}. \index{output width}\index{linesize} \item[\cs{SRlistingdir}] specifies the name of the directory that contains the SAS generated listing (tabular) output files. The default is \Code{lst}. \item[\cs{SRmacropath}] specifies the path to the location of the SAS macros that are bundled with the \Code{StatRep} package. \index{SAS macro location} For example, if you installed the \Code{statrep\_macros.sas} file to a directory named \Code{C:\textbackslash mymacros}, then define macro \cs{SRmacropath} as follows: \begin{verbatim} \def\SRmacropath{c:/mymacros/statrep_macros.sas} \end{verbatim} Use the forward slash in the definition as the directory name delimiter instead of the backslash, which is a special character in \LaTeX. If you want to use a backslash character (\textbackslash), you must insert it with the \LaTeX\ command, \cs{@backslashchar}. The default value is the current path. That is, the default definition for the \cs{SRmacropath} macro is the filename itself, \Code{statrep\_macros.sas}. \item[\cs{SRmacroinclude}] specifies the line used in the generated SAS program to include the SAS macros that are bundled with the \Code{StatRep} package. The default is\\\Code{\%include }\cs{SRmacropath}~\Code{/nosource;} \item[\cs{SRpagesize}] specifies the default page size for SAS to use in generating tabular output. The default is \Code{500}. \item[\cs{SRparindent}] specifies the amount of space to indent \Code{Datastep} and \Code{Sascode} environments. The argument is a dimension. The default is \Code{3em} and is measured according to the font currently in use. \item[\cs{SRprogramline}] specifies the first lines to include in the generated SAS program after the \cs{SRmacroinclude} line. The following default value calls a macro (from \Code{statrep\_macros.sas}) that removes the contents of the listing and graphic directories to ensure that the generated graphs and listings from the SAS program are current. The directories are created with each SAS run that includes the macros themselves (via \Code{x} commands). \begin{snugshade} \begin{verbatim} %hostdel; \end{verbatim} \end{snugshade} \item[\cs{SRprogramname}] specifies the filename for the generated SAS program. The default is \cs{jobname\_SR.sas}, where \cs{jobname} is usually the stem name of the \LaTeX\ source file. \item[\cs{SRstyle}] specifies the default ODS style for SAS to use to generate graphical output. The default is \Code{Statistical}. \index{ODS output style} \item[\cs{SRtempfilename}] specifies the name of a temporary file that is used as a scratch file in the current working directory. The default is \Code{sr.tmp}. \item[\cs{SRverbfont}] specifies the font to use for code within \Code{Datastep} and \Code{Sascode} blocks. The default is \cs{ttfamily}\cs{bfseries} (\texttt{\textbf{typewriter text, bold}}). \index{verbatim font} \end{description} \chapter{About the Program Preamble} The \StatRep package automatically writes a preamble to the generated program and a preamble file. The preamble settings are split into two parts to support users who prefer to manually write the calls to the \StatRep macros and work interactively between the \LaTeX\ source document and a SAS session. For this use, you can include the external preamble file once in your SAS session and all the necessary settings are made for you. If you do not manually write calls to the \StatRep macros (you use the default, automated method), there is nothing you need to do---your generated program contains the lines that specify your settings. The preamble in the generated program includes the preamble file and deletes the contents of the output directories (\Code{lst}, \Code{tex}, and \Code{png}, by default) so that obsolete files are not included in the document. Figure \ref{fig:pgmpreamble} shows an example of the preamble lines that are written to the generated program. \begin{figure}[H] \begin{snugshade} \begin{verbatim} /* This file is auto-generated by the statrep package. Do not edit this file or your changes will be lost. Edit the LaTeX file instead. See the statrep package documentation and the file statrep.cfg for information on these settings. */ %include "report_SR_preamble.sas" /nosource; /* Remove all output files. */ %hostdel; /* Start program with a null title. */ title; \end{verbatim} \end{snugshade} \caption{Generated SAS Program Preamble}\label{fig:pgmpreamble} \end{figure} The external preamble file sets defaults, includes the output-capture macros, and creates the output directories if they do not exist. You can customize the preamble; see section \ref{custom} for details. Figure \ref{fig:preamble} shows the default file preamble. \begin{figure}[H] \begin{snugshade} \begin{verbatim} /* This file is auto-generated by the statrep package. Do not edit this file or your changes will be lost. Edit the LaTeX file instead. See the statrep package documentation and the file statrep.cfg for information on these settings. */ /* Set and invoke macro variable defaults. */ %let defaultlinesize=80; %let defaultpagesize=500; %let defaultdpi=300; %let defaultstyle=statistical; %let listingdir=lst; %let graphicdir=png; %let graphtype=png; %let odsgraphopts=; %let latexdir=tex; %let latexstyle=statrep; %let defaultdests=listing; options nodate nonumber ls=&defaultlinesize ps=&defaultpagesize formchar='|----|+|---+=|-/\<>*'; ods graphics on; /* Include SAS macro definitions. */ %include "statrep_macros.sas" /nosource; \end{verbatim} \end{snugshade} \caption{Generated Preamble File}\label{fig:preamble} \end{figure} \chapter{Two Methods of Writing} To maximize flexibility, the \StatRep package provides two methods of writing code in your \LaTeX\ document. When you create your \LaTeX\ document, you can use either the automatic method described in chapter \ref{gs} (in which the SAS macro calls are generated automatically) or a manual method (in which you write the \Code{\%output}, \Code{\%endoutput}, and \Code{\%write} macros yourself). In the automatic method, each \Code{Sascode} code block generates an \Code{\%output} macro call at the beginning of the block and an \Code{\%endoutput} macro call at the end of the block. Each \cs{Listing} and \cs{Graphic} tag generates the \Code{\%write} macro to replay the selected output objects to external files. In the manual method, you decide where and when to make the macro calls. It is only in this respect that the method is manual: the \StatRep package still generates your SAS program and displays your code and results. The \StatRep package uses the SAS macro comment (\Code{\%* \emph{comment} ;}) to provide line commands within a \Code{Sascode} block. Furthermore, any line of code that begins with a null macro comment (\Code{\%*;}) is written to the SAS program and is not displayed. You can use the manual method when you want to do one or more of the following: \begin{itemize} \item capture specialized or complicated output \item capture print output with SAS 9.2 (see the \Code{\%startlist} macro in section \ref{startlist}) \item capture output from the SAS log (see the \Code{\%startlog} macro in section \ref{startlog}) \item work interactively when writing (you can interactively develop or debug a certain section of your document by copying code from your \LaTeX\ document and pasting it into a SAS session) \end{itemize} You can use either method, and you can mix the methods in a single document. The manual method is provided for cases in which the automatic method is too inflexible. By using the line commands in a \Code{Sascode} environment, you are free to write your program as you want, while retaining control of the code that is displayed in your final PDF document. Continuing with example shown in Figure \ref{fig:d1} and Figure \ref{fig:s1}, you can write the code yourself within your \LaTeX\ document as shown in Figure \ref{fig:manual} and obtain the identical code display and capture. \begin{figure}[H] \begin{framed} \begin{snugshade} {\hfil\textit{Datastep is identical}\hfil} \begin{verbatim} \begin{Datastep} proc format; value $sex 'F' = 'Female' 'M' = 'Male'; data one; set sashelp.class; format sex $sex.; run; \end{Datastep} \end{verbatim} \end{snugshade} \begin{snugshade} {\hfil\textit{\texttt{\%output} added manually}\hfil} \begin{verbatim} \begin{Sascode} *; %output(class) proc reg; model weight = height age; run; \end{verbatim} \end{snugshade} \begin{snugshade} {\hfil\textit{\texttt{\%write} macros added manually}\hfil} \begin{verbatim} *; %write(rega, type=listing) *; %write(regb, type=graphic) \end{Sascode} \end{verbatim} \end{snugshade} \begin{snugshade} {\hfil\textit{Listing and Graphic tags only caption and insert output}\hfil} \begin{verbatim} \Listing[caption={Regression Analysis}]{rega} \Graphic[caption={Graphs for Regression Analysis}]{regb} \end{verbatim} \end{snugshade} \end{framed} \caption{Using the SAS Macros Manually}\label{fig:manual} \end{figure} The \Code{Datastep} environment in Figure \ref{fig:manual} is identical to that shown in the Figure \ref{fig:d1}. However, the \Code{Sascode} environment makes an explicit call to the \Code{\%output} macro to create the ODS document that contains all the results from the code block. Because this line begins with the null SAS macro comment (\Code{\%*;}), the line is passed directly to the generated SAS program and is not displayed. The \Code{\%endoutput} macro is not necessary when you are processing only one ODS document. It is implicitly specified by the first \Code{\%write} macro. Next are two explicit calls to the \Code{\%write} macro, which specify the ODS objects to capture and the ODS document that the objects should be taken from. Both \Code{\%write} macros use the minimum number of options. The first \Code{\%write} macro selects all notes and tables from the last ODS document created. The second \Code{\%write} macro selects all graphs from the last ODS document created. Because the \Code{store=} option is omitted in both cases, output from the most recently created ODS document is displayed. Finally, the \cs{Listing} and \cs{Graphic} tags request the outputs. In this method, you do not place the options that are related to SAS in the the \cs{Listing} and \cs{Graphic} tags. You need to specify only the caption and filename prefix. To summarize, the \Code{Datastep} environment is handled identically in either method, the \Code{Sascode} environment can optionally produce the \Code{\%output} and \Code{\%endoutput} macros, and the \cs{Listing} and \cs{Graphic} tags can optionally produce the \Code{\%write} macros. \chapter{\StatRep SAS Macros}\label{macros} \index{SAS macros} SAS programs created by the \StatRep package run SAS macros to capture output. The macros depend on the ODS document. The ODS document is a destination or repository for the results (tables, notes, titles, and graphs) that come from SAS procedures. Each procedure step is run only once, and the results are captured in an ODS document. Then the parts of the ODS document are replayed using PROC DOCUMENT. When \StatRep encounters a \Code{Sascode} environment, it generates a macro call to create an ODS document from the environment. When \StatRep encounters a \cs{Listing} or \cs{Graphic} tag, it generates a macro call to replay output from that ODS document into an external file. For the output that is generated in each \Code{Sascode} block, the SAS macros provide you with a list of all of the objects in the ODS document and a table that displays the objects selected for display. You can review this list in the SAS log. It is important to check these lists to ensure that either all output is included somewhere or any omissions are deliberate. The following macros are defined: \begin{itemize} \item The \Code{\%output} and \Code{\%endoutput} macros open and close an ODS document, respectively. When you use \StatRep to automatically generate your program, these macros are called at the beginning and end of a \Code{Sascode} block, respectively. You can manually call the macros at any time within a \Code{Sascode} block by prefixing the call with a null SAS macro comment (\Code{\%*;}). \index{SAS macros!output}\index{SAS macros!endoutput} \item The \Code{\%write} macro writes ODS objects that are contained in an ODS document to one or more external files. When you use \StatRep to automatically generate your program, this macro is called when a \cs{Listing} or \cs{Graphic} tag is encountered. You can manually call the macro at any time within a \Code{Sascode} block by prefixing the call with a null SAS macro comment (\Code{\%*;}). \index{SAS macros!write} \item The \Code{\%startlist} and \Code{\%endlist} macros capture printed content (for example, a PROC PRINT or DATA step) to an external file. To use these macros, you must manually call the macro within a \Code{Sascode} block and prefix the call with a null SAS macro comment (\Code{\%*;}). \index{SAS macros!startlist}\index{SAS macros!endlist} \item The \Code{\%startlog} and \Code{\%endlog} macros capture content from the SAS log to an external file. To use these macros, you must manually call the macro within a \Code{Sascode} block and prefix the call with a null SAS macro comment (\Code{\%*;}). \index{SAS macros!startlog}\index{SAS macros!endlog} \end{itemize} \section{The \texttt{\%output} and \texttt{\%endoutput} Macros}\label{outputmacro} The \Code{Sascode} environment writes the \Code{\%output} and \Code{\%endoutput} macros to the generated program whenever the \Code{store=} option is specified. However, you can call the macros yourself by omitting the \Code{store=} option in the \Code{Sascode} environment and call the macros within the \Code{Sascode} environment. Each call must be prefixed with a null SAS macro comment (\Code{\%*;}). \index{SAS macros!output}\index{SAS macros!endoutput} The \Code{\%output} macro supports two other options (\Code{style=} and \Code{dpi=}) that are used to set parameters for GRSEG graphs. These options are not supported in the \Code{Sascode} environment options. If you want to change the style or DPI for GRSEG graphs, you must call the \Code{\%output} and \Code{\%endoutput} macros manually. The following options are supported by the \Code{\%output} macro: \begin{description} \item[\Code{store=}] specifies the name of the ODS document. This name is used in the \Code{store=} option in the \cs{Listing} and \cs{Graphic} tags or in the \Code{\%write macro}. \item[\Code{style=}] specifies the style used for GRSEG graphs. The default is \Code{HTMLBlue}. See section \ref{grseg} for details. \item[\Code{dpi=}] specifies the dots per inch (DPI) setting used for GRSEG graphs. The default is 300 DPI. See section \ref{grseg} for details. \end{description} \section{The \texttt{\%write} Macro} The \Code{\%write} macro supports the same key-value options as the \cs{Listing} and \cs{Graphic} tags support. The \StatRep package generates the \Code{\%write} macro in the SAS program file whenever the \Code{store=} option is specified in the output tag. However, you can call the macros yourself by omitting the \Code{store=} option in the \cs{Listing} or \cs{Graphic} tag and call the macro within a \Code{Sascode} environment. Each call must be prefixed with a null SAS macro comment (\Code{\%*;}). \index{SAS macros!write} See the section \titleref{sasopts} for more information about the options used in the \cs{Listing} and \cs{Graphic} tags that are passed to the \Code{\%write} macro. \vspace*{1em}\noindent\textbf{Note:} If you use the macros interactively, be aware that these macros open and close ODS destinations, enable and disable ODS Graphics, and change ODS options. Output capture uses the LISTING destination, and when the \Code{\%write} macro finishes, only the LISTING destination remains open. If you need other ODS destinations for your work, you need to reset them when you are done with a section of output capture. For example, if you are using the HTML destination in the SAS windowing environment, then you need to close the LISTING destination and reopen the HTML destination when you finish capturing output. \section{The \texttt{\%startlist} and \texttt{\%endlist} Macros}\label{startlist} The \Code{\%startlist} and \Code{\%endlist} macros capture printed information from the ODS listing destination. The macros are used when you create output with a procedure that does not support ODS. They are also used when you use the \Code{DATA \_NULL\_} and \Code{PUT \_ODS\_} SAS statements to manually capture output. \index{SAS macros!startlist}\index{SAS macros!endlist} These macros are not automatically generated by the \StatRep package. You must call them manually within a \Code{Sascode} environment (with each call preceded by a null SAS macro comment). In SAS 9.2, PROC PRINT is not fully integrated into the ODS document, unless you specify PROC PRINT with no options. If you specify PROC PRINT with options, you must use the \Code{\%startlist} and \Code{\%endlist} macros to capture output. If you use PROC PRINT in SAS 9.3 or later, you can use the \Code{\%output} and \Code{\%write} macros as you would with any SAS procedure. The \Code{\%startlist} macro has one mandatory argument, the filename prefix of the file to contain the output. The argument is also used in the \cs{Listing} tag to insert the output. The \Code{\%startlist} macro supports the following options after the filename argument, separated with a comma (,): \begin{description} \item[\Code{linesize=}] specifies the line size. The default is the line size currently in effect. This specification lasts for the duration of this step. The current line size is restored at the end. When you specify the \Code{linesize=} option in the \Code{\%startlist} macro, be sure to make the same specification in the \cs{Listing} tag you use to insert the output. \item[\Code{pagesize=}] specifies the size of the output page. The default is the page size currently in effect. This specification lasts for the duration of this step. The current page size is restored at the end. This option is useful for breaking up long listings into smaller parts to allow for page breaks. If a listing output spans more than one SAS page, the output is automatically split into parts and the page breaks can occur only between parts of output. For more information about capturing large outputs, see section \ref{large}. \end{description} \section{The \texttt{\%startlog} and \texttt{\%endlog} Macros}\label{startlog} The \Code{\%startlog} and \Code{\%endlog} macros capture SAS notes or error messages from the SAS log. They also capture output from some SAS/IML functions that write to the SAS log rather than using ODS. \index{SAS macros!startlog}\index{SAS macros!endlog} These macros are not automatically generated by the \StatRep package. To capture content from the SAS log, you must call these macros manually within a \Code{Sascode} environment (with each call preceded by a null SAS macro comment). The \Code{\%startlog} macro has one mandatory argument, the filename prefix of the file to contain the output. The argument is also used in the \cs{Listing} tag to insert the output. The \Code{\%endlog} macro supports the following options, separated by a comma (,): \begin{description} \item[\Code{code=}] specifies whether program code in the SAS log is included. By default, code is captured (\Code{code=1}). Set \Code{code=0} to exclude code. \item[\Code{range=}] specifies a Boolean expression to select certain observations. For example, you can specify \Code{range=\_n\_ <= 5 } to select the first five lines. You can specify \Code{range=not index(line, 'ERROR')} to select all lines that do not contain the string `ERROR'. Selection must be based on \Code{\_n\_} or the variable \Code{line}, which contains a single line of the log. \end{description} \section{Macro Variable Defaults}\label{secdefaults} \index{macro variables}\index{default settings}\index{package!defaults} \index{SAS macros!variables} The SAS macro defaults are set globally in the file \Code{statrep.cfg}. See section \ref{custom} for details. You can also reset the defaults within your document by specifying new settings in a \Code{Sascode} environment. Table \ref{defaults} shows the description and default values for each macro variable. \begin{table}[H] \centering\caption{Default Values for Macro Variables}\label{defaults} \begin{tabular}{llP{2.5in}} \textbf{Macro Variable} & \textbf{Default} & \textbf{Description}\\ \hline \Code{defaultlinesize} & 80 & Line size for tabular ODS output\\ \Code{defaultpagesize} & 500 & Page size for tabular ODS output\\ \Code{defaultstyle} & Statistical & ODS style for graphical output \\ \Code{defaultdpi} & 300 & Dots per inch (DPI) for graphical output\\ \Code{graphtype} & png & graphics file format ('png' or 'pdf')\\ \Code{odsgraphopts} & & string containing ODS graphics options\\ \Code{defaultdests} & listing & \texttt{listing} or \texttt{latex} tabular output\\ \Code{latexstyle} & statrep & ODS Style for SAS-generated LaTeX output\\ \hline \end{tabular} \end{table} You can edit the \Code{statrep.cfg} file\index{customizing}\index{statrep.cfg} \index{configuration}% to globally reset the defaults, or you can specify commands to change the default anywhere in your document. For example, the following lines change all of the macro variable default settings for the duration of the program. The \Code{program} option specifies that the code be written only to the generated program and not displayed. \begin{figure}[H] \begin{snugshade} \begin{verbatim} \begin{Sascode}[program] %let defaultlinesize=96; %let defaultpagesize=50; %let defaultstyle=statistical; %let defaultdpi=100; %let graphtype=pdf; %let odsgraphopts=antialiasmax=10000; \end{Sascode} \end{verbatim} \end{snugshade} \caption{Reset SAS Macro Defaults within Document with SAS}\label{reset} \end{figure} When you change the \Code{defaultlinesize} in the \Code{statrep.cfg} file, the same value is automatically used by SAS and by the \StatRep package. When you change the \Code{defaultlinesize} inside your document, you change the line size used by SAS in generating outputs; You must also set the line size in the \cs{Listing} tag to match. The setting of \Code{defaultpagesize=500} produces a large virtual page so that SAS does not break ODS objects into smaller pieces. When a stream of outputs is typeset, page breaks can occur only between ODS objects or when SAS forces a page break inside an ODS table. The macro options and default macro variables work as follows: If an option is specified in a macro, its value is used regardless of the specification in the default macro variables. If an option is not specified in a macro, the default macro variables provide the values. In summary, a direct option specification in a macro takes precedence over the default settings, and you can change the default settings by resetting the default macro variables in your document or by editing the \Code{statrep.cfg} file. \chapter{ODS Object Selection}\label{selection} To select and display ODS objects, you specify options in the \cs{Listing} tag, \cs{Graphic} tag, or the \Code{\%write} macro. \label{optionopt} By default, when you omit object selection options, the \Code{\%write} macro selects all ODS objects, the \cs{Listing} tag selects all ODS tables and notes, and the \cs{Graphic} tag selects all ODS graphs. \index{ODS object selection} Table \ref{tabselect} summarizes how you select ODS objects. \begin{table}[H] \centering\caption{ODS Object Selection Options}\label{tabselect} \begin{tabular}{lP{3.75in}} \textbf{Option} & \textbf{Action}\\ \hline \Code{options=table} & Select all tables and notes\\ \Code{options=graph} & Select all graphs \\ \Code{pattern=} \textit{pattern} & Select all objects with a name matching a pattern. When an ODS object name has more than two levels, the middle level name is a group name. You can specify the \Code{pattern=} option to select all ODS objects in the specified ODS group. More generally, you can specify any pattern to select all objects whose path contains the pattern.\\ \Code{firstobj=} & Specifies the first object in the output stream to capture. The specified and subsequent objects are captured.\\ \Code{lastobj=} & Specifies the last object in the output stream to capture. The first object in the stream to capture is the first object produced by the \Code{Sascode} code block or the object specified in the \Code{firstobj=} option.\\ \Code{objects=} option & Specifies a space-separated list of objects to capture.\\ \hline \end{tabular} \end{table} The \Code{firstobj=} and \Code{lastobj=} options can be modified with the option \Code{options=skiplast} and \Code{options=skipfirst}. For more information about how to use these options, see page \pageref{skiplast}. \section{Page Breaks}\label{pagebreak} By default, a page break can occur between any two objects in the output stream. However, you can use left and right angle brackets, \Code{<>}, to delineate a set of objects in which to suppress breaks. You use the symbols in the \Code{objects=} option list in a \cs{Listing} tag, a \cs{Graphic} tag, or a \Code{\%write} macro. For example, you can use the symbols to prevent a break between a ``Parameter Estimates'' table and the ``Fit Statistics'' table that follows it with the following option: \Code{objects = < ParameterEstimates FitStatistics >} After the \Code{<} symbol, breaking is suppressed until the \Code{>} symbol is encountered. After the \Code{>} symbol, a break is introduced and normal breaking continues. In summary: \begin{itemize} \item You can use the \Code{<>} symbols in pairs to keep ODS objects together. \item You can use the \Code{>} symbol (unpaired with a matching \Code{<}) to create a break between tables. \item You can use the \Code{<} symbol (unpaired with a matching \Code{>}) to suppress all breaks. \end{itemize} A break is always allowed before and after a graph. See page \pageref{skiplast} for an alternate method of controlling breaks with the \Code{options=nopage} and \Code{options=onebox} options. \chapter{ODS Graphics} \index{ODS graphics} In SAS 9.3 and later, ODS Graphics is enabled by default in the SAS windowing environment. ODS Graphics is not enabled by default in batch mode and in the SAS windowing environment in SAS 9.2. When ODS Graphics is not enabled by default, you can enable ODS Graphics by specifying the following statement: \begin{snugshade} \begin{verbatim} ods graphics on; \end{verbatim} \end{snugshade} You can enable ODS Graphics in \StatRep for all steps by providing this code block at the beginning of your LaTeX document: \begin{snugshade} \begin{verbatim} \begin{Sascode}[program] ods graphics on; \end{Sascode} \end{verbatim} \end{snugshade} \section{ODS Graphics and GRSEG Graphics} \label{grseg} \index{ODS graphics}\index{GRSEG graphics} When you create a graph with ODS Graphics, the style and dots per inch (DPI) can be changed after the graph is created. The style and DPI are set when the graph is written to the external file. This enables you to specify the options in the \cs{Graphic} tag or in the \Code{\%write} macro. On the other hand, when you create a GRSEG graph, the style and DPI are set when the graph is created. That is why you must specify the options in the \Code{\%output} macro. See section \ref{outputmacro} for details about the \Code{\%output} macro options. Table \ref{tabgraph} summarizes the methods you can use to modify the style and DPI settings when you create a graph. \begin{table}[H] \centering \caption{Methods to Change Graph Properties}\label{tabgraph} \begin{tabular}{lcc} \textbf{Method} & \textbf{ODS Graph} & \textbf{GRSEG Graph} \\ \hline \cs{Graphic} tag options & Yes & No \\ \Code{\%write} macro options & Yes & No \\ \Code{\%output} macro options & No & Yes \\ Reset global default & Yes & Yes \\ \hline \end{tabular} \end{table} The \cs{Graphic} tag, the \Code{\%write} macro, and the \Code{\%output} macro have \Code{style=} and \Code{dpi=} options. For more information about these options, see section \ref{sasopts}. Also, see section \ref{secdefaults} for details about using the SAS macro variables to reset global defaults. For GRSEG graphs, there are only two choices for DPI: 300 (the default) and 96. When the DPI is set to anything other than 300, then 96 is automatically used instead for GRSEG graphs. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Advanced Examples} \section{Capturing PRINT Output}\index{SAS macros!startlist}\index{SAS macros!endlist} Figure \ref{printoutput} shows simple use of the \Code{\%startlist} and \Code{\%endlist} macros. \begin{figure}[H] \begin{snugshade} \begin{verbatim} \begin{Sascode} *; %startlist(myprtlabel); proc print data=sashelp.class(obs=10) noobs; run; *; %endlist; \end{Sascode} \Listing[caption={Mass Analysis}]{myprtlabel} \end{verbatim} \end{snugshade} \caption{Capturing Print Output with the \texttt{\%startlist} and \texttt{\%endlist} Macros}\label{printoutput} \end{figure} The \Code{\%startlist} macro opens the ODS listing destination for writing. The PRINT procedure code is executed, and the \Code{\%endlist} macro closes the ODS destinations. The result is an output file called \Code{myprtlabel.lst}, which is inserted into the document with the \cs{Listing} tag. The following section describes how to use the \Code{\%startlist} and \Code{\%endlist} macros to capture and display part of a table. \section{Capturing Large Tables}\label{large} The \StatRep package automatically takes care of all page breaks in the output. Pages are allowed to break between groups of ODS objects or wherever there is a new page in the listing output. In some cases, an ODS object is too large to fit on a page. There are two ways to handle such large tables: \begin{itemize} \item Set the page size to a smaller size so that a single ODS object is broken into pieces by using the SAS system option to control the size of the output parts. By default, a large page size is in effect (\Code{defaultpagesize=500}) and each table appears as a complete output block. However, when you have tables that are too long to fit on a page (that is, single ODS objects that will not fit on a page), you must specify a smaller page size (for example, \Code{pagesize=50}). The tables will automatically split using the normal SAS rules for splitting tables. \item Save the ODS object to a SAS data set and manipulate the data set so that it contains only part of the original output. Use PROC PRINT or DATA step statements to generate and capture the modified data set. \end{itemize} Figure \ref{odsdataset} shows an example of using a SAS data set to manipulate the ODS object resulting from a problem that is very slow to converge. The output from this step includes a long iteration history table. The goal is to display only the first few and last few lines of the iteration history table. \begin{figure}[H] \begin{snugshade} \begin{verbatim} \begin{Sascode}[store=doc] proc prinqual data=X n=1 maxiter=2000 plots=transformation out=results; *; ods output mtv=m convergencestatus=c; title 'Linearize the Scatter Plot'; transform spline(X1-X3 / nknots=9); run; \end{Sascode} \end{verbatim} \end{snugshade} \caption{Capturing Output to an ODS Output Data Set}\label{odsdataset} \end{figure} Any arbitrary SAS statement can be sent to the generated program by preceding it with a null SAS macro comment (\%*;). With the output generated and the ODS document \Code{doc} created, the \Code{Sascode} block shown in Figure \ref{odsmanip} is passed directly to the generated program and not displayed. \begin{figure}[H] \begin{snugshade} \begin{verbatim} \begin{Sascode}[program] %startlist(prqdb) title3 'The PRINQUAL Procedure'; title5 'PRINQUAL MTV Algorithm Iteration History'; title6 ' '; data _null_; set m(rename=(variance=rsquare)); if _n_ le 13 or _n_ gt 1669; if 11 le _n_ le 13 then do; iternum = .; avechange = ._; criterionchange = ._; maxchange = ._; rsquare = ._; end; file print ods=(template='Stat.Transreg.MTV'); put _ods_; run; title; data _null_; set c; file print; put @8 reason; run; %endlist; \end{Sascode} \end{verbatim} \end{snugshade} \caption{Manipulating the ODS Output Data Set for Printing}\label{odsmanip} \end{figure} The \Code{\%startlist} macro opens the file \Code{prqdb} to contain the printed results of the code block. The DATA step reads, manipulates, and prints the data set \Code{m} that was just created by PROC PRINQUAL, and the printed content is written to the output file \Code{prqdb.lst}, which is shown in Figure \ref{odsmanipresult}. \begin{figure}[H] \footnotesize \begin{snugshade} \begin{verbatim} Linearize the Scatter Plot The PRINQUAL Procedure PRINQUAL MTV Algorithm Iteration History Iteration Average Maximum Proportion Criterion Number Change Change of Variance Change Note ------------------------------------------------------------------------- 1 0.15125 0.93453 0.92376 2 0.04589 0.14682 0.98030 0.05653 3 0.03154 0.10125 0.98626 0.00596 4 0.02258 0.06890 0.98890 0.00265 5 0.01682 0.04777 0.99028 0.00137 6 0.01297 0.03782 0.99106 0.00078 7 0.01032 0.03029 0.99154 0.00048 8 0.00851 0.02514 0.99186 0.00032 9 0.00722 0.02124 0.99209 0.00023 10 0.00625 0.01871 0.99226 0.00017 . . . 1670 0.00001 0.00005 0.99371 0.00000 1671 0.00001 0.00005 0.99371 0.00000 1672 0.00001 0.00005 0.99371 0.00000 Converged Algorithm converged. \end{verbatim} \end{snugshade} \caption{Result of Printing ODS Output Data Set}\label{odsmanipresult} \end{figure} Similarly, Figure \ref{printods} creates an output data set in the first step. The second step reads in the data set and uses PROC PRINT to display the first 10 rows of a table. \begin{figure}[H] \begin{snugshade} \begin{verbatim} \begin{Sascode} title2 'Binary Table'; *---Perform Multiple Correspondence Analysis---; proc corresp data=Cars binary; *; ods output rowcoors=rc; ods select RowCoors; tables Origin Size Type Income Home Marital Sex; run; \end{Sascode} \begin{Sascode}[program] %startlist(crse1n) proc print data=rc(obs=10) noobs label; label label = '00'x; title4 'The CORRESP Procedure'; title6 'Row Coordinates'; run; %endlist; \end{Sascode} \end{verbatim} \end{snugshade} \caption{Capturing PROC PRINT Output from an ODS Data Set}\label{printods} \end{figure} \section{Capturing Log Output} \index{SAS macros!startlog}\index{SAS macros!endlog} The SAS/IML example shown in Figure \ref{logout} illustrates the use of the macros that capture log output. In this example, the goal is to display SAS/IML error messages\footnote{The example code generates an error because of a variable scoping issue. Module \Code{Mod7} is called from module \Code{Mod8}. Therefore, the variables available to \Code{Mod7} are those defined in the scope of \Code{Mod8}. Because no variable named \Code{x} is in the scope of \Code{Mod8}, an error occurs on the PRINT statement in \Code{Mod7}. An error would not occur if \Code{Mod7} was called from the main scope, because \Code{x} is defined at main scope.}. \begin{figure}[H] \begin{snugshade} \begin{verbatim} \begin{Sascode} *; %startlog(psmodb) proc iml; x = 123; start Mod7; print "In Mod7:" x; finish; start Mod8(p); print "In Mod8:" p; run Mod7; finish; run Mod8(x); *; %endlog; \end{Sascode} \Listing[caption={Error Message When a Variable is Not Defined in a Module}]{psmodb} \end{verbatim} \end{snugshade} \caption{Capturing Log Output}\label{logout} \end{figure} The captured log output is shown in Figure \ref{logcomplete}. \begin{figure}[H] \begin{snugshade} \begin{verbatim} 1599 +proc iml; NOTE: IML Ready 1600 + x = 123; 1601 + 1602 + start Mod7; 1603 + print "In Mod7:" x; 1604 + finish; NOTE: Module MOD7 defined. 1605 + 1606 + start Mod8(p); 1607 + print "In Mod8:" p; 1608 + run Mod7; 1609 + finish; NOTE: Module MOD8 defined. 1610 + 1611 + run Mod8(x); ERROR: Matrix x has not been set to a value. statement : PRINT at line 1603 column 7 traceback : module MOD7 at line 1603 column 7 module MOD8 at line 1608 column 7 NOTE: Paused in module MOD7. NOTE: Exiting IML. NOTE: The SAS System stopped processing this step because of errors. \end{verbatim} \end{snugshade} \caption{Complete Log Output Capture}\label{logcomplete} \end{figure} The \Code{\%startlog} macro opens the specified file for writing, the IML procedure code is executed, and the \Code{\%endlog} macro closes the file. To omit the PROC IML code from the captured log output, specify the \Code{code=0} option in the \Code{\%endlog} macro as follows: \begin{snugshade} \begin{verbatim} %*; %endlog(code=0); \end{verbatim} \end{snugshade} With the \Code{code=0} option specified, the captured log output is displayed as shown in Figure \ref{lognoproc}. \begin{figure}[H] \begin{snugshade} \begin{verbatim} NOTE: IML Ready NOTE: Module MOD7 defined. NOTE: Module MOD8 defined. ERROR: Matrix x has not been set to a value. statement : PRINT at line 1651 column 7 traceback : module MOD7 at line 1651 column 7 module MOD8 at line 1656 column 7 NOTE: Paused in module MOD7. NOTE: Exiting IML. NOTE: The SAS System stopped processing this step because of errors. \end{verbatim} \end{snugshade} \caption{Log Output Capture: Procedure Code Omitted}\label{lognoproc} \end{figure} You can further refine the captured log output with the \Code{range=} option in the \Code{\%endlog} macro as follows: \begin{snugshade} \begin{verbatim} %*; %endlog(code=0, range=_n_ > 6 and _n_ le 24); \end{verbatim} \end{snugshade} With the both options specified, the captured log output is displayed as shown in Figure \ref{logabbrev}. \begin{figure}[H] \begin{snugshade} \begin{verbatim} NOTE: Module MOD7 defined. NOTE: Module MOD8 defined. ERROR: Matrix x has not been set to a value. statement : PRINT at line 1722 column 7 traceback : module MOD7 at line 1722 column 7 module MOD8 at line 1727 column 7 NOTE: Paused in module MOD7. \end{verbatim} \end{snugshade} \caption{Abbreviated Log Output Capture: Procedure Code Omitted}\label{logabbrev} \end{figure} The \Code{range=\_n\_ > 6 and \_n\_ le 24} option specifies that only the lines between 6 and 24 be included in the captured output. The value of \Code{\_n\_} refers to the original line numbers before any filtering is done. \section{Capturing Output with Interactive Procedures} You can use the \StatRep package to capture output from interactive procedures. Figure \ref{interact} shows how to capture output from the interactive IML procedure. It displays three \Code{Sascode} environments with \cs{Listing} outputs interleaved. \begin{figure}[H] \begin{snugshade} \begin{verbatim} \begin{Sascode} *; %output(doc) proc iml; x = 1; print x; \end{Sascode} \Listing[caption={x = 1}]{x1a} \begin{Sascode} x = 2; print x; \end{Sascode} \Listing[caption={x = 2}]{x2a} \begin{Sascode} x = 3; print x; *; %write(x1a, objects=x) *; %write(x2a, objects=x#2) *; %write(x3a, objects=x#3) \end{Sascode} \Listing[caption={x = 3}]{x3a} \end{verbatim} \end{snugshade} \caption{Capture Output with an Interactive Procedure}\label{interact} \end{figure} When you need to interleave \Code{Sascode} blocks to make a single ODS document, as in Figure \ref{interact}, you cannot rely on the \StatRep package to automatically write the macros. You must write the output capture macros manually. When the \StatRep package automatically writes the macros, there is a one-to-one correspondence between a \Code{Sascode} block and an ODS document. The interactive procedure terminates when the ODS document is closed. Figure \ref{interact} uses three \Code{Sascode} blocks to create a single ODS document. The contents of that ODS document are displayed in three separate listings. The ODS document is created by the \Code{\%output(doc)} statement in the first \Code{Sascode} environment, and it is closed by the first \Code{\%write} macro in the third \Code{Sascode} environment. The three \Code{\%write} macros create the output for the three output listings. The fact that two of the \cs{Listing} lines come before any of the output is created does not pose a problem. \section{Capturing and Displaying Numerical Results in Text} This example shows how you can capture SAS output values and display them in text. For example, suppose you want to capture the R-square values from a PROC REG step and a PROC GLM step and then display those values (but not display the steps) in your document. Use the following steps to capture the values and display them in text: \begin{enumerate} \item In your document source file, anywhere before you want to display the captured values, include the following command to input a \LaTeX\ file (named\newline\texttt{myconstants.tex} in this example) to contain the \LaTeX\ definitions of the captured values: \begin{snugshade} \begin{verbatim} \input{myconstants} \end{verbatim} \end{snugshade} The \texttt{myconstants.tex} file is actually generated in step 3, but you can include the preceding command before the file is generated because the SAS output capture program will create the file and write the definitions before pdf\LaTeX\ generates the final PDF file. \item Include one or more procedure steps, such as the following PROC REG and PROC GLM steps, which produce tables of fit statistics that are named \texttt{fsr} and \texttt{fsg}, respectively: \begin{snugshade} \begin{verbatim} \begin{Sascode} proc reg data=sashelp.class; model weight = height; %*;ods output fitstatistics=fsr; run; quit; proc glm data=sashelp.class; class sex; model weight = sex | height; %*;ods output fitstatistics=fsg; run; quit; \end{Sascode} \end{verbatim} \end{snugshade} Include a null macro comment at the beginning of the ODS OUTPUT statement in each step to cause the step to be run in the capture program but not be displayed in the text. \item Near the end of your document source file, include code such as the following to generate the \texttt{myconstants.tex} file, extract the R-square values from the \texttt{fsr} and \texttt{fsg} tables of fit statistics that were generated in step 2, and write those values to \texttt{myconstants.tex}. The \texttt{Sascode} environment option, \texttt{program}, runs the code without displaying it in the text. \begin{snugshade} \begin{verbatim} \begin{Sascode}[program] data _null_; file 'myconstants.tex' termstr=nl; set fsr(keep=label2 nvalue2 where=(label2='R-Square')); put '\def \regrsq{' nvalue2 6.4 '}'; set fsg(keep=rsquare); put '\def \glmrsq{' rsquare 6.4 '}'; run; \end{Sascode} \end{verbatim} \end{snugshade} \item Include the tags that are contained in the \texttt{myconstants.tex} file when you want to display the values of those tags, as follows: \begin{snugshade} \begin{verbatim} The R-square values are \regrsq\ and \qlmrsq, respectively. \end{verbatim} \end{snugshade} Include a backslash after the tag when you need to include a space after the value. \end{enumerate} When you execute the generated SAS program, SAS writes the following tags in the \texttt{myconstants.tex} file: \begin{snugshade} \begin{verbatim} \def \regrsq{0.7705} \def \glmrsq{0.7930} \end{verbatim} \end{snugshade} When pdf\LaTeX\ processes the file, it replaces the \verb+\regrsq+ and \verb+\glmrsq+ tags with the values that were written to the \texttt{myconstants.tex} file and produces the following: \begin{snugshade} The R-square values are 0.7705 and 0.7930, respectively. \end{snugshade} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \appendix \part{Appendix} %\chapter{Appendix} \chapter{Installation and Requirements}\label{install}\index{installing} You can install the \StatRep package by downloading \Code{statrep.zip} from \url{support.sas.com/StatRepPackage}. Table \ref{ziptable} shows the contents: \begin{table}[H] \caption{Contents of the \Code{statrep.zip} File}\label{ziptable} \begin{tabular}{ll} \hline \textbf{Filename} & \textbf{Description}\\ \Code{doc/statrepmanual.pdf} & The \textit{\StatRep User's Guide} (this manual)\\ \Code{doc/quickstart.tex} & A template and tutorial sample \LaTeX\ file\\ \Code{sas/statrep\_macros.sas} & The \StatRep SAS macros \\ \Code{sas/statrep\_tagset.sas} & The \StatRep SAS tagset for LaTeX tabular output \\ \Code{statrep.ins} & The \LaTeX\ package installer file\\ \Code{statrep.dtx} & The \LaTeX\ package itself\\ \hline \end{tabular} \end{table} Unzip the file \Code{statrep.zip} to a temporary directory and perform the following steps: \section{Step 1: Install the StatRep SAS Macros} Copy the file \Code{statrep\_macros.sas} to a local directory. If you have a folder where you keep your personal set of macros, copy the file there. Otherwise, create a directory such as \Code{C:\textbackslash{}mymacros} and copy the file into that directory. \section{Step 2: Install the StatRep LaTeX Package} These instructions show how to install the StatRep package in your \LaTeX\ distribution for your personal use. \begin{enumerate}[a)] \item \textbf{Mik\TeX\ users}: If you do not have a directory for your own packages, choose a directory name to contain your packages (for example, c:\textbackslash{}localtexmf). In the following instructions, this directory is referred to as the "root directory". \textbf{\TeX{}Live users}: If you maintain a system-wide LaTeX distribution and you want to make StatRep available to all users, see more detailed information about how to install LaTeX packages at: \url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=what-TDS} Determine the location that LaTeX uses to load packages. At a command-line prompt, enter the following command:\\ \texttt{kpsewhich -var-value=TEXMFHOME} The command returns the root directory name in which LaTeX can find your personally installed packages. In the following instructions, this directory is referred to as the "root directory". \item Create the directory if it does not exist, and create the additional subdirectories \Code{tex/latex/statrep}. Your directory tree will have the following structure: \begin{verbatim} --------------- root directory/ tex/ latex/ statrep/ \end{verbatim} \item Copy the files \Code{statrep.dtx}, \Code{statrep.ins}, \Code{statrepmanual.pdf}, and \Code{statrepmanual.tex} to the \Code{statrep} subdirectory. Your directory tree will have the following structure: \begin{verbatim} --------------- root directory/ tex/ latex/ statrep/ statrep.dtx statrep.ins statrepmanual.pdf statrepmanual.tex --------------- \end{verbatim} \item Change to the \Code{statrep} directory and enter the following command:\\ \texttt{pdftex statrep.ins} The command creates several files, one of which is the configuration file, \Code{statrep.cfg}. \textbf{Mik\TeX\ users}: Add the root directory name from Step 2a according to these instructions for installing packages for MikTeX (\textit{Register a user-managed TEXMF directory}): \url{http://docs.miktex.org/manual/localadditions.html} \end{enumerate} \section{Step 3: Tell the StatRep Package the Location of the StatRep SAS Macros} Edit the \Code{statrep.cfg} file that was generated in Step 2d so that the macro \cs{SRmacropath} contains the correct location of the macro file from step 1. For example, if you copied the \Code{statrep\_macros.sas} file to a directory named \Code{C:\textbackslash{}mymacros}, then you define macro \cs{SRmacropath} as follows: \begin{verbatim} \def\SRmacropath{c:/mymacros/statrep_macros.sas} \end{verbatim} Use the forward slash as the directory name delimiter instead of the backslash, which is a special character in LaTeX. You can now test and experiment with the package. Create a working directory, and copy the file \Code{quickstart.tex} into it. To generate the quick-start document: \begin{enumerate} \item Compile the document with pdf\LaTeX. You can use a \LaTeX-aware editor such as \TeX works, or use the command-line command \Code{pdflatex}. This step generates the SAS program that is needed to produce the results. \item Execute the SAS program quickstart\_SR.sas, which was automatically created in the preceding step. This step generates the SAS results that are requested in the quick-start document. \item Recompile the document with pdf\LaTeX. This step compiles the quick-start document to PDF, this time including the SAS results that were generated in the preceding step. In some cases listing outputs may not be framed properly after this step. If your listing outputs are not framed properly, repeat this step so that LaTeX can remeasure the listing outputs. \end{enumerate} You can make changes to the file with a \LaTeX-aware editor or with any plain-text editor such as \textsf{NotePad} or \textsf{emacs}. If you ever want to uninstall the \StatRep package, delete the \Code{statrep} directory that you created in the installation step 2d and remove the SAS macro file \Code{statrep\_macros.sas} that you copied in installation step 1. Mik\TeX\ users must additionally update the filename database.\\ \Code{(MikTeX Options dialog: General-> Refresh FNDB)} \chapter{The \texttt{longfigure} Package}\label{longfigure}\index{longfigure package} The \Code{longfigure} package uses and relabels components of the well-known \Code{longtable} package, written by David Carlisle, to provide a table-like environment that can display a stream of subfigures as a single figure that can break across pages. The \Code{longtable} package defines a \Code{longtable} environment, which produces tables that can be broken by \TeX's standard page-breaking algorithm. Similarly, the \Code{longfigure} package defines a \Code{longfigure} environment, which produces figures that can be broken by \TeX's standard page-breaking algorithm. The internal structure of a long figure is similar to a long table. Rows might contain (for example) tables or graphics. Page breaks can occur only between rows. The \Code{longfigure} package differs from the \Code{longtable} package in the following ways: \begin{itemize} \item The \Code{longfigure} package supports two additional key-value options: \begin{itemize} \item The \Code{figname=} option specifies the counter for numbering \Code{longfigure} environments. You can specify any string; the default is \Code{figure}. When you specify a \Code{figname=} value for which no counter already exists, the \Code{longfigure} package loads the \Code{tocloft} package and creates the counter. \index{figname option} \item The \Code{resetby=} option specifies a counter (for example, \Code{resetby=chapter}) such that output numbering is reset each time the counter value changes. If a counter is specified that does not exist, the \Code{tocloft} package is loaded to create the new counter. \index{tocloft package}% For information about how the lists are typeset, \index{list of outputs, creating}% see the \Code{tocloft} package documentation. \end{itemize} \item The counters and macros that start with \cs{LT} in the \Code{longtable} package are renamed to start with \cs{LF} in the \Code{longfigure} pacakge to avoid namespace conflicts when the two packages are used together. The generic macros that are defined in the \Code{longtable} package (\cs{endfirsthead}, \cs{endhead}, \cs{endfoot}, and \cs{endlastfoot}) are also renamed with \cs{LF} as a prefix in the \Code{longfigure} package. \item The \cs{LF@name} macro is based on the \cs{fnum@table} macro from the \Code{longtable} package. The \cs{LF@name} macro returns the capitalized counter name and value. For example, if the counter is \Code{figure} and the macro is processing the second \Code{longfigure}, the \cs{LF@name} macro would contain the value ``Figure 2.'' \end{itemize} You can use the \Code{longfigure} package defaults to produce a \emph{List of Figures} by inserting the following tag in your document at the point where you want the list to appear: \begin{verbatim} \listoffigures \end{verbatim} The default counter used to display figures is the \Code{figure} counter, but you can specify a different counter. For example, if you want your figures to be labeled as ``Display,'' specify \Code{figname=display} when you load the \Code{longfigure} package; to display a \emph{List of Displays}, insert the following command in your document at the point where you want the list to appear: \begin{verbatim} \listofdisplay \end{verbatim} \textbf{Note:} If you specify a counter that does not exist, an auxiliary file with extension \Code{.lft} is created to contain the information needed to create the list. If you want to use more advanced features of the \Code{tocloft} package, load it before you load the \Code{longfigure} package so that the \Code{longfigure} package sees that the counters specified by the \Code{figname=} and \Code{resetby=} options are already defined and does not attempt to create them. \section{Example} The following lines produce a single figure that contains three images and one tabular environment. Each element is a row of the \Code{longfigure} environment. Page breaks can occur between rows. \begin{verbatim} \documentclass{book} \usepackage{graphicx} \usepackage{longfigure} \begin{document} \begin{longfigure}{c} \caption{My Long Figure}\label{mlfig}\\ \includegraphics[width=3in]{myfig1}\\ \includegraphics[width=3in]{myfig2}\\ \includegraphics[width=3in]{myfig3}\\ \begin{tabular}{ll} one & two \\ three & four\\ \end{tabular} \end{longfigure} \end{document} \end{verbatim} In this example, the \Code{\{c\}} argument in the \cs{begin\{longfigure\}} command specifies only a single centered column. You can also specify multiple columns and, if needed, use the \cs{multicolumn} command for more flexibility. %%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%% \chapter{The ODS \StatRep LaTeX Tagset}\label{latexoutput} \index{ODS LaTeX output}\index{LaTeX output} The \StatRep package provides limited support for SAS-generated LaTeX output\footnote{Since SAS 9.1, SAS\textsuperscript{\textregistered} has provided an experimental LaTeX tagset.\index{statrep tagset} The \texttt{statrep} tagset is a simplified version of that experimental tagset.}. Three corresponding configuration variables are available. You can change them in the file \texttt{statrep.cfg} or in your LaTeX document. For complete details about the configuration file, see the section \ref{custom}. The variables are as follows: \begin{itemize} \item \cs{SRdefaultdests} specifies the type of ODS output to generate. The default is \texttt{listing}, which corresponds to the ODS Listing destination. \item \cs{SRlatexstyle} specifies the ODS style for SAS-generated LaTeX tables. The default is \texttt{statrep}, which is a monochromatic style based on the SAS ODS LaTeX tagset. \item \cs{SRlatexdir} specifies the name of the subdirectory into which SAS writes the LaTeX output files. The default is \texttt{tex}. \end{itemize} To enable the use of LaTeX output in \StatRep, follow these steps. \begin{enumerate} \item Change your \StatRep configuration or in your LaTeX document. The \cs{SRdefaultdests} setting selects the default output type; it can have the value \texttt{latex} or \texttt{listing}. The default value is \texttt{listing}. You can change the value in the \texttt{statrep.cfg} configuration file as follows: \begin{verbatim} \def\SRdefaultdests{latex} \end{verbatim} Alternatively, you can change the value in your LaTeX document after the \StatRep package is loaded and before your document begins: \begin{verbatim} \documentclass{article} \usepackage{statrep} \def\SRdefaultdests{latex} \begin{document} \end{verbatim} \item Run the included SAS program \Code{statrep\_tagsets.sas}\index{statrep tagset} before you generate the SAS output for your document. This program creates a \texttt{statrep} tagset and a \texttt{statrep} ODS style. When you run the program to generate the output for your document, SAS must be able to find the \texttt{statrep} tagset in order to produce LaTeX tabular output that is compatible with the \StatRep package. For details on installing and storing tagsets see this SAS\textsuperscript{\textregistered} Note: \url{http://support.sas.com/kb/32/394.html} \end{enumerate} \section{How It Works} When you first compile your document with \texttt{pdflatex}, the SAS program to produce the requested outputs is generated. When you run the program, SAS checks the type of output requested, which is controlled with the \cs{SRdefaultdests} setting. If the output type is \texttt{latex}, LaTeX output is written to a subdirectory named \texttt{tex}. If the output type is \texttt{listing}, ODS Listing output is written to a subdirectory named \texttt{lst}. When you recompile your document with \texttt{pdflatex}, the \cs{Listing} tag displays the requested output objects, insuring that your outputs are displayed properly with automatic page breaking. \section{Customization} \begin{description} \item[ODS Style] You can specify an ODS style for your LaTeX output with the \cs{SRlatexstyle} setting. The default is \texttt{statrep}, a monochrome style that is generated by the SAS program \Code{statrep\_tagsets.sas}.\index{statrep tagset} Examples of different styles are provided in the section \titleref{styleexamples}. If you specify an ODS style that uses color, specify the \texttt{color} option when you load the \StatRep package. \begin{verbatim} \documentclass{article} \usepackage[color]{statrep} \end{verbatim} The style setting for LaTeX tables cannot be changed within a document. That is, you cannot mix ODS LaTeX styles within a document.\index{mixing LaTeX styles} If you change the style within your document, the last style specified is used for all LaTeX outputs. \item[Mixing Output Types] You can mix output types with the \texttt{dest=} option on the \cs{Listing} tag.\index{mixing output types} The option overrides the global \cs{SRdefaultdests} setting. For example, if your \cs{SRdefaultdests} is set to \texttt{latex}, you can specify that a particular \cs{Listing} output to be in listing format by specifying \texttt{dest=listing} in the \cs{Listing} tag options, as follows: \begin{verbatim} \Listing[store=mydoc, dest=listing, caption={Results}]{outa} \end{verbatim} \item[Output Directory Name] You can change the name of the directory into which SAS writes the outputs with the \cs{SRlatexdir} variable. The default subdirectory name is \Code{tex}. \end{description} \section{Caution} In some cases the LaTeX tagset produces tables that are too wide to fit in the text block. In some cases, you can shift the table to the left so the table will fit on the page. You can shift the table with the \cs{LFleft} command. The following example moves the left margin of the output 1 inch to the left of its normal location (the start of the text block). The output is then typeset and the margin is set back to its default value of 0. \begin{verbatim} \LFleft=-1in \Listing[store=mydoc, caption={Results}]{outa} \LFleft=0in \end{verbatim} In some cases, the table will not fit on the page at all. The only solution in those cases is to change back to the \texttt{listing} output destination, modifying the fontsize and linesize as needed. Some ODS styles may not work with the LaTeX tagset. For example, some styles specify fonts that are available to SAS but not to LaTeX. \section{Style Examples}\label{styleexamples} \begin{figure}[H] \caption{Listing Output} \includegraphics{images/listing} \end{figure} \begin{figure}[H] \caption{LaTeX Output, default style} \includegraphics{images/default} \end{figure} \begin{figure}[H] \caption{LaTeX Output, \texttt{statistical} style} \includegraphics{images/statistical} \end{figure} \begin{figure}[H] \caption{LaTeX Output, \texttt{journal} style} \includegraphics{images/journal} \end{figure} \begin{figure}[H] \caption{LaTeX Output, \texttt{htmlblue} style} \includegraphics{images/htmlblue} \end{figure} \chapter{\StatRep with SAS Studio or SAS University Edition}\label{sasstudio} \index{SAS Studio}\index{University Edition}\index{SAS University Edition} \index{web interface} You can use \StatRep with the SAS Studio web-based interface and SAS University Edition. You can find more information on these applications here: \begin{description} \item[SAS Studio] is a web application for SAS that you access through your web browser. \url{http://support.sas.com/software/products/sasstudio/} \item[SAS University Edition] is free and includes the SAS products Base SAS, SAS/STAT, SAS/IML, SAS/ACCESS Interface to PC Files, and SAS Studio. \url{http://support.sas.com/software/products/university-edition/index.html} \end{description} With a web interface, there is no concept of a \emph{current directory}, so you must let SAS know where your files are located. In order to use \StatRep, SAS needs to know the following locations: \begin{itemize} \item the directory that contains your LaTeX file. \item the full path to the file \texttt{statrep\_macros.sas}. \item the location of the \StatRep ODS tagset, if you prefer LaTeX output (instead of Listing output). See the previous chapter for details on how to create and use this tagset. \end{itemize} With SAS University Edition, you run a virtual machine on your local computer so you can create a shared folder that SAS can access.\index{virtual machine} For SAS Studio folder locations, see the following section for details. \section{SAS Studio Folders} \index{SAS Studio} Other than SAS University Edition, there are three 3 types of installations for SAS Studio: \begin{itemize} \item SAS Studio Single User \item SAS Studio Basic (Windows or UNIX) \item SAS Studio Mid-Tier (Enterprise Edition) \end{itemize} For Single User, \textit{My Folders} is your home directory on your local machine and the folders list will also include folders for your desktop, documents folder, and mapped drives. For both Enterprise and Basic edition, the path for \textit{My Folders} is the home directory on the remote SAS server. That is, the file system in the \textit{Folders} accordion is not your local machine; it is the location of the remote server. On Windows, you can add a \textit{Folder Shortcut} back to your local computer. The shortcut must be accessible by the remote server. On UNIX, you can add a \textit{Folder Shortcut} to your home directory. You may need to ask your local SAS administrator about how to create a folder shortcut to your local files. \section{SAS University Edition: Creating a Shared Folder} \index{University Edition}\index{SAS University Edition}\index{virtual machine} Suppose you have a directory called \texttt{mydocs} that contains your LaTeX file. You create a shared folder in the virtual machine as shown in the following screenshot: \includegraphics[width=\textwidth]{images/vm1} When you select \texttt{Shared Folders} and click to add a new path, enter the information (path and name) as shown in the following screenshot: \includegraphics[width=\textwidth]{images/vm2} The \texttt{Folder Path} is the absolute path to the directory and the folder name is the last part of that path. The name is a short-hand name that is used later in your code. Make sure to select \texttt{Auto-mount} if you want to use the folder in later SAS sessions (as you probably will). The result of entering the information is shown in the following screenshot. \includegraphics[width=\textwidth]{images/vm3} When you start SAS Studio, the \texttt{Folder} panel shows your new shared folder as a \emph{Folder Shortcut}. SAS will know this folder by the full name \texttt{/folders/myshortcuts/mydocs}, which means you can use that name to assign filerefs and libnames as you normally would in any SAS program. Notice the \texttt{Folder} panel in the following screenshot. You can disregard most of the code in the program editor window, but do notice the first line that references the new shared folder. \includegraphics[width=\textwidth]{images/sasuniv1} The LIBNAME statement in the code window assigns the \texttt{mytempl} libref to your shared folder. \section{The Bridge Between LaTeX and SAS} Now you have your working directory and SAS knows that there is such a location. The final step is to define a bridge between your LaTeX document and SAS. You connect the two by defining a LaTeX tag called \verb+\SRrootdir+, which contains the path to your shared folder as displayed in the following LaTeX code: \begin{verbatim} \documentclass{article} \usepackage[margin=1in]{geometry} \usepackage[color]{statrep} \def\SRrootdir{/folders/myshortcuts/mydocs} \def\SRmacropath{/folders/myshortcuts/mydocs/statrep_macros.sas} \begin{document} \end{verbatim} This document preamble performs the following: \begin{itemize} \item Specifies that the document use the \texttt{article} class. \item Loads the \texttt{geometry} package and specifies 1 inch margins on all sides. \item Loads the \texttt{statrep} package and specifies that outputs can include color. \item Defines the \verb+\SRrootdir+ path (the path to the working directory) as the shared folder you created in the previous steps. \item Defines the \verb+\SRmacropath+ that contains the full path and file name of the \texttt{statrep\_macros.sas} file that is part of the \StatRep package. This example shows that it is in the same directory as the LaTeX file, but you can put the macros anywhere you like, as long as SAS can find the file (that is, as long as the macros are in a shared folder) \end{itemize} With this preamble, you can start writing your content; when \StatRep automatically generates the SAS program to create your output, the paths you have defined here are used so SAS can find the macros it needs and so it can write the requested outputs to your working directory. From this point on, you use \StatRep just as you would normally. \printindex \end{document}