2 Using SASmarkdown

2.1 Introduction

Using SASmarkdown in RStudio (or in R) gives you a method for writing simple documents which include the results of executing SAS commands. Both the document text and the source SAS code are in one file.

This is especially good for writing simple documents that explain statistical scripting tasks. One way to think of this is as an extended and more readable version of writing comments in your source code.

2.2 Background

Markdown is a language for formatting fairly simple documents using just a few text symbols. It is designed to be easy to read and write. You may already be using some Markdown (in email, for instance) and not even realize it - it's that simple! If you are not already familiar with Markdown see John Gruber's Markdown article.

R Markdown extends Markdown by allowing you to include blocks of code in one of several programming languages. The code is evaluated, and both the code and it's results are included in a Markdown document. To read more about the details of R Markdown see RStudio's R Markdown webpages

RStudio uses an R package called knitr to render documents written in R Markdown. We will discuss some of the nuances of evaluating SAS code in subsequent articles.

The documentation for knitr can be found in the book R Markdown: The Definitive Guide, in R's Help, or from this web page.

RStudio makes it easy to process your R Markdown document to produce a final HTML, pdf, or Word document. After you have written your R Markdown document, RStudio processes it with a simple click of a button! The focus in this book will be on producing HTML (web) pages.

Some caveats:

  • Using SAS with R Markdown is not quite as graceful as using R with R Markdown, but the SASmarkdown package automates some techniques for putting together simple documents.

  • Note that this is not a friendly environment for extensively debugging problems in your SAS code (although with the right options you can see any SAS error messages in the SAS log file). If your code is at all complicated, you should work out the details in SAS first, then bring it into RStudio to develop your documentation!

  • Also note that some of the set up for using SAS and SASmarkdown is done in R. The basics are pretty simple, but to modify the default process it helps to be bilinugal in R and SAS.

2.3 Including SAS Code in your Document

SAS code is included in your R Markdown document in a block called a "code chunk". When you click on Rstudio's Knit button, your initial document (your "source" document) is processed by the R function knitr. This evaluates your code, collects the output, and produces a Markdown document. This Markdown document is then processed by a program called Pandoc to produce your final HTML document.

It helps to understand how knitr evaluates your SAS code. Knitr writes out your code into a file, and then submits that file to SAS to be run in batch mode. This produces SAS log and SAS "listing" output. The listing output is then read back into knitr and used to produce a block of output in the Markdown document. The SAS files are ordinarily temporary.

2.3.1 Limitations

There are several limitations that you will have to work with:

  • Each code chunk runs separately as a SAS batch job, they are not processed as a single running session like R code. Interspersing text with executed code is not (quite) as simple as when running R code.

    For example, suppose you have a DATA step early in your document, and then want to use that data in a later code chunk. In the later code chunk, SAS will have begun a new session (a new batch job) and "forgotten" the first DATA step. SAS will not find the data, so SAS will send an error message to R Markdown. The default message R Markdown passes back to you will only tell you that SAS did not exit properly.

    This difficulty is overcome with a chunk option automated through SASmarkdown, collectcode.

  • Text (listing) output is simple to use. If you want to use SAS's HTML output instead of listing output, or if you want to include SAS graphics in your final document, a different SAS engine makes this fairly simple (sashtml or sashtml5). If you want to use SAS’s LaTeX output, yet another SAS engine does this (saspdf).

  • A third limitation is that knitr returns two blocks of text to your document - by default, the SAS code and the listing output. If you want to show your reader the content on the SAS log file, another SAS engine, saslog makes this easy. Additional engines enable log output with HTML and LaTeX output.

2.3.2 HTML or PDF Document?

You can choose between producing a final document as HTML or PDF when you click on the Knit button in RStudio.

Longtime SAS users will find that SAS listing output looks as expected in both HTML and PDF documents. (Newer SAS users may not be familiar with listing output, since it is no longer the default when using SAS interactively. R Markdown runs SAS in batch mode, so listing output is produced by default.)

SAS HTML output can be included in a final HTML document, but renders poorly as a PDF document when run through R Markdown. Likewise, SAS LaTeX output can be included to produce a final PDF document, but renders poorly in an HTML document.

To go beyond fairly simple PDF documents, you may want to investigate SAS's StatRep or Lenth's SASWeave.

2.3.3 Document Setup

An initial code chunk sets up the SAS engines for use in your document.

```{r} 
library(SASmarkdown)
```

2.3.4 Code Chunk Setup

The minimal code chunk setup to run SAS is just as easy.

```{sas} 

/* SAS code here */

```

2.4 Running SAS

Here then, is a simple example as it might appear in your final document. The code chunk that is written in your document is:

```{sas} 
proc means data=sashelp.class;
run;
```

And appears in your document like this:

proc means data=sashelp.class;
run;
                            The MEANS Procedure

 Variable    N           Mean        Std Dev        Minimum        Maximum
 -------------------------------------------------------------------------
 Age        19     13.3157895      1.4926722     11.0000000     16.0000000
 Height     19     62.3368421      5.1270752     51.3000000     72.0000000
 Weight     19    100.0263158     22.7739335     50.5000000    150.0000000
 -------------------------------------------------------------------------

2.5 HTML Output and Graphics

There are two advantages to using SAS's HTML output, rather than the listing output. First, results tables become HTML tables instead of just monospaced text, and they will dynamically size themselves to the end user's window. Second, you can include SAS graphics in your final document with a minimum of fuss.

To use SAS's html output, use the sashtml or sashtml5 engine, as described in a later chapter. An example as you would write it:

```{sashtml} 
proc corr data=sashelp.class plots=matrix;
run;
```

And as it appears in your document:

proc corr data=sashelp.class plots=matrix;
run;
3 Variables: Age Height Weight
Simple Statistics
Variable N Mean Std Dev Sum Minimum Maximum
Age 19 13.31579 1.49267 253.00000 11.00000 16.00000
Height 19 62.33684 5.12708 1184 51.30000 72.00000
Weight 19 100.02632 22.77393 1901 50.50000 150.00000
Pearson Correlation Coefficients, N = 19
Prob > |r| under H0: Rho=0
  Age Height Weight
Age
1.00000
 
0.81143
<.0001
0.74089
0.0003
Height
0.81143
<.0001
1.00000
 
0.87779
<.0001
Weight
0.74089
0.0003
0.87779
<.0001
1.00000
 
Scatter Plot Matrix Scatter Plot Matrix 60 80 100 120 140 50 55 60 65 70 11 12 13 14 15 16 60 80 100 120 140 50 55 60 65 70 11 12 13 14 15 16 Weight Height Age

Written using

  • SASmarkdown version 0.8.0.
  • knitr version 1.40.
  • R version 4.2.2 (2022-10-31 ucrt).