Markdown Stata
Insert Markdown into any Jekyll document with this simple tag.
- My Stata commands. In practice markdown documents are often transformed using eg Pandoc and so The Pandoc User Guide is quite often necessary if.
- Stata/Markdown HTML PDF bibliography tweaks. If you are interested in running the script yourself, note that you need to have the file gpnupt.ado available in the working directory or your personal ado folder, as it is used in one of the examples. The file is listed in Section 4.3.6 of the tutorial.
We have several methods of combining text and Stata code available in the SSCC.
- As of Stata 15, Stata has built in support for dynamic markdown.
- R/RStudio has support for Stata in markdown documents, via the
knit()
function. - Jupyter Lab can support a mix of Stata and markdown.
The Jupyter options require some set up by you, the user, plus one step by our system administrators (not yet implemented, 11 Dec 2018, so ask the Help Desk). The RStudio and Stata options are easier to use if you install an additional package as well. None of these is all that difficult to set up on Winstat.
The main benefit of using a Jupyter notebook is that you can edit and run your code live. If you are thinking your way through a problem, coding and writing simultaneously, this will be a very convenient workflow. In Stata or in RStudio, you need to compile a document to see all the text, code, and output in the same place.
The main disadvantage of using a Jupyter notebook (on Winstat) is that each cell is a separate Stata session (until our system adminstrators complete one extra step). So at the moment this is really only going to be useful for fairly simple Stata coding tasks.
(Jupyter can be set up to run separate cells through one continous Stata session, but this has not been implemented on the SSCC Winstats or in the labs.)
One-time Set Up
You will first need to install IPyStata. This is done outside of Jupyter, from a command prompt. On Winstat, open the Anaconda command prompt (from the Start Menu) and type the command
This may additionally tell you to install the `msgpack` module. Next, open a Jupyter notebook in order to run some Python commands. This, too, is a one-time set up.
Finally, Stata Notebooks
Having done the set up steps above, you are ready to write Jupyter notebooks that run Stata code.
Markdown Stata Editor
When you open a new notebook, you open it with the Python kernel. Your first step is then to invoke ipystata
in a preliminary cell.
After this, you include %%stata
at the beginning of any cell that has Stata code.
However, keep in mind that each cell is run as a separate Stata batch.
What you need for this second example is really
November 2020
- Hints and Examples
Stata notes | Stata and R Markdown
Introduction
This is an introduction to writing dynamic documents using R Markdown to produce documents based on Stata. This process uses Rstudio (or just R) to create documents that depend upon Stata code. The source for this document is StataMarkdown.rmd
Background
Markdown is a language for formatting not-too-complicated documents using just a few text symbols. It is designed to be easy to read and write. If you read and write email, you are probably already familiar with many of these formatting conventions. For more specifics about Markdown see John Gruber's Markdown article.
Markdown Stata Software
Dynamic Markdown has been implemented for a number of programming languages, including Stata and R. Within Stata there is a dynamic markdown package called stmd
that relies on Stata's dyndoc
command, as well as the user-written package markstat
. Each has it's strengths and weaknesses.
The system I will describe here is intended primarily for those of us who are already using R Markdown to write documentation in other languages, and would like to use this for Stata as well.
R Markdown is a dynamic markdown system that 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
Dyndoc
RStudio uses an R package called knitr
(this could also be called directly from R), which includes the ability to evaluate Stata.
The documentation for knitr
can be found in R's Help, from Yihui Xie's web page, or in the book, R Markdown: The Definitive Guide.
Finally, I use some helper functions in a package called Statamarkdown
. While these are not necessary to write dynamic documents based on Stata, they make life easier.
Statamarkdown
can be installed from github.com.
Note, RStudio is a great environment for writing Markdown with executable R code chunks, but it is not a friendly environment for extensively debugging problems in your Stata code. If your Stata code is complicated, you should probably work out the details in Stata first, then pull it into RStudio to develop your documentation!
Setting up the Stata engine
In order to execute your Stata code, knitr
needs to know where the Stata executable is located. This can be done with a preliminary code chunk, by loading the Statamarkdown package:
(In knitr
jargon, a block of code is a 'code chunk'.)
If the package fails to find your copy of Stata (you will see a message), you may have to specify this yourself (see Stata Engine Path).
After this setup chunk, subsequent code to be processed by Stata can be specified as:
Linking Code Blocks
Each block (chunk) of Stata code is executed as a separate batch job. This means that as you move from code chunk to code chunk, all your previous work is lost. To retain data from code chunk to code chunk requires collecting (some of) your code and processing it silently at the beginning of each subsequent chunk.
You can have knitr collect code for you, as outlined in Linking Stata Code Blocks and as illustrated below.
Hints and Examples
Code Separate or with Output
Stata does not give you fine control over what ends up in the .log file. You can decide whether to present code and output separately (R style), or include the code in the output (Stata style).
See Stata Output Hooks).
Including Graphs
Including graphics requires graph export
in Stata, and an image link in the R Markdown. The knitr
chunk option echo
can print just specified lines of code, allowing you to hide the graph export
command as illustrated below.
Frequency Tables
Using chunk options echo=FALSE, cleanlog=FALSE
, yields a more typical Stata documentation style.
Graphics
The example uses the knitr chunk options results='hide'
to suppress the log and echo=1
to show only the Stata graph box
command that users need to see.
(This page was written using Statamarkdown version 0.5.5.)