4 Linking Code Blocks

4.1 Linking Code Blocks

Most documents have alternating blocks of code, output, and explanatory text. And very often the code illustrated in later blocks will depend in some way on code in the previous blocks. However, each code block (also called a "code chunk") is executed as a separate Stata session.

For example, your first block of code might load a data set, calculate a new variable, and provide summary statistics (see below). You then provide some explanatory text that tells the reader about the analysis you are about to do, followed by the code block for the analysis and the output. Because the second, "analysis" code block is executed as a separate Stata session, you have to reload the data set and re-calculate the new variable.

One way to have some "setup" code execute silently at the start of each Stata code block is to put it in a file named profile.do, located in the same folder as your Markdown file. (See the Stata FAQ about profile.do files: Stata looks for this file every time it starts up.)

Statamarkdown provides a chunk option to collect your code as you go, and adds each block of code to your profile.do.

(Side note: local macros defined in profile.do disappear after the profile has run. In other words, you cannot accumulate local macro definitions.)

You may not want all of your code to end up in the profile.do, so the implementation here makes it a user-specified option whether or not each code block is added to the profile.do. For longer documents, try to collect as little code as possible, or it will really slow down the generation of your document!

4.2 An Example

This illustrates what we would like to be able to do.

A first code block:

sysuse auto
generate gpm = 1/mpg
summarize price gpm
(1978 automobile data)

    Variable |        Obs        Mean    Std. dev.       Min        Max
-------------+---------------------------------------------------------
       price |         74    6165.257    2949.496       3291      15906
         gpm |         74    .0501928    .0127986   .0243902   .0833333

A second, later code block:

regress price gpm
      Source |       SS           df       MS      Number of obs   =        74
-------------+----------------------------------   F(1, 72)        =     35.95
       Model |   211486574         1   211486574   Prob > F        =    0.0000
    Residual |   423578822        72  5883039.19   R-squared       =    0.3330
-------------+----------------------------------   Adj R-squared   =    0.3238
       Total |   635065396        73  8699525.97   Root MSE        =    2425.5

------------------------------------------------------------------------------
       price | Coefficient  Std. err.      t    P>|t|     [95% conf. interval]
-------------+----------------------------------------------------------------
         gpm |     132990   22180.86     6.00   0.000     88773.24    177206.7
       _cons |  -509.8827   1148.469    -0.44   0.658    -2799.314    1779.548
------------------------------------------------------------------------------

4.3 The collectcode Chunk Option

The implementation here makes use of a "chunk hook", collectcode. With the Statamarkdown library loaded, this option is available for any Stata code chunk.

In the example (above), I added code from the first Stata chunk (labelled "first-Stata") to the profile.do, but not code from the second chunk.

A first code block:
```{stata first-Stata, collectcode=TRUE} 
sysuse auto
generate gpm = 1/mpg
summarize price gpm
```

A second, later code block:
```{stata second-Stata} 
regress price gpm
```

4.4 Clear collectcode

If you need to clear collected code partway through a document, include code in your document to delete the profile.do file. This is done automatically at the end of each document.

(This page was written using Statamarkdown version 0.7.1.)