Incorporating Stata into reproducible documents

Hua Peng@StataCorp

2017 Oceania Stata Users Group meeting

https://huapeng01016.github.io/oceania17/

Why reproducible documents?

Eliminate manual steps such as hand-editing documents

  • mix formatted text and Stata output
  • include inline Stata results
  • embed Stata graphs
  • produce tables containing the output from selected Stata commands

Commands in Stata 15

  • dyndoc - convert dynamic Markdown documents to web pages
  • putdocx - create Word documents
  • putpdf - create PDF files

A dyndoc example

Produce a blog article from a dynamic markdown document

Quick review of dynamic tags

dd_do for a block of Stata code

<<dd_do>>
sysuse auto
regress weight displacement
<</dd_do>>

. sysuse auto
(1978 Automobile Data)

. regress weight displacement

      Source |       SS           df       MS      Number of obs   =        74
-------------+----------------------------------   F(1, 72)        =    289.52
       Model |  35312313.3         1  35312313.3   Prob > F        =    0.0000
    Residual |  8781865.08        72  121970.348   R-squared       =    0.8008
-------------+----------------------------------   Adj R-squared   =    0.7981
       Total |  44094178.4        73  604029.841   Root MSE        =    349.24

------------------------------------------------------------------------------
      weight |      Coef.   Std. Err.      t    P>|t|     [95% Conf. Interval]
-------------+----------------------------------------------------------------
displacement |   7.573261   .4450891    17.02   0.000     6.685992     8.46053
       _cons |   1525.276   96.74555    15.77   0.000     1332.417    1718.134
------------------------------------------------------------------------------

Attributes change a tag's behavior

<<dd_do:quietly>>
matrix define eb = e(b)
<</dd_do>>

dd_display for inline Stata results

  • For every unit increase in displacement, a <<dd_display:%9.4f eb[1,1]>> unit increase in weight is predicted.
  • For every unit increase in displacement, a 7.5733 unit increase in weight is predicted.

dd_graph

<<dd_do:quietly>>
scatter weight displacement, mcolor(%30)
<</dd_do>>
<<dd_graph>>

More dynamic tags

Display contents based on condition

<<dd_skip_if: ("`talkplace'" == "Oceania")>>
> The past was alterable. The past never had been altered.
<<dd_skip_else>>
> Oceania was at war with Eastasia. Oceania had always been at war with Eastasia.
<<dd_skip_end>>

Oceania was at war with Eastasia. Oceania had always been at war with Eastasia.

Include a text file

The text file might be the result of a dynamic file.

<<dd_include: subsection1.txt >>

Make a dataset containing means and variances of 100-observation samples from a lognormal distribution. Perform the experiment 10,000 times, then summarize the result:


    Variable |        Obs        Mean    Std. Dev.       Min        Max
-------------+---------------------------------------------------------
        mean |     10,000    1.648681    .2178435   1.038739   3.246317
         var |     10,000    4.714419    4.978809   .8448562   206.9827

".do files on steroids"

  • macros work the same as in do-file
  • accept arguments

Use arguments in dyndoc

Produce a set of different HTML pages from one dynamic document with different arguments

The dataset is at auto_78_img.dta.

Code for the previous page

<<dd_do:quietly>>
use auto_78_img.dta, clear
desc
cap mkdir cars
<</dd_do>>

<<dd_do:nocommand>>
forval i=1/`r(N)' {
  di "- [" make[`i'] "](./cars/" make[`i'] ".html)"
}
<</dd_do>>

// need use dd_remove
<<dd_do>>
forval i=1/`r(N)' {
  dyndoc auto_78.txt `=make[`i']', saving("cars/`=make[`i']'.html") replace
}
<</dd_do>>
// need use dd_remove

dyntext

Process dynamic tags in any text files, for example, LaTeX and JavaScript

JavaScript

dyntext gchart.txt, sav(gchart.html) replace

Use pandoc instead of Stata's markdown

putdocx

Produce a .docx document from a do-file

  • full range of control for text formatting
  • flexible table output

Output tables in markdown

Produce markdown tables from commands, including

  • all estimation commands using _coef_table
  • table
  • estimates table

THE END