ado-files and literate programming

[Christopher Bratt]

Chuck Huber just had a webcast, giving an introduction to ado files. I asked under Q&A what the best method would be to combine ado-files with literate programming. In my case, literate programming is using a separate document to put all supplemental material, including all code. StataCorp seemed to suggest copy and paste, if I understand correctly.

Many in the R community now move away from having separate files with scripts (think separate do-files and ado-files) and include all code in one file, thereby increasing reproducibility for other researchers and avoiding copy and paste (which is error-prone). R users can now use R Markdown or the newer Quarto. If I should develop something similar with Stata and also use ado-files, how would I get the content of an ado-file copied automatically into my summary file (printed as PDF)?

PS. In Quarto, I can load the content of an external file, be it graphics or some text, including a Stata do-file, and have the graphics/text printed in the final document produced by Quarto. Notably, Quarto is less R focused than R Markdown was. If Stata developed an integration with Quarto, that would be great, even for Stata users who combine Stata and Python and don't want to be bothered with R. So if Stata's version(s) of markdown are currently less capable of reading and printing the content of an external file, maybe an official integration of Stata with Quarto could be one way to solve this?

[Doug Hemken]

How are you writing your Quarto source files?

If you use Jupyter, Stata already has an official integration for that. Can Jupyter include an external text file?

If you use R with Statamarkdown (now available through CRAN), you can include text (i.e. your ado file) as a code chunk. IIRC the knitr "child" option is what you are looking for?

I don't think markstat does this itself, although I'm sure you could figure out some Stata code to read and display the ado file. A dyndoc solution would be similar.

[Doug Hemken]

I should add, I don't remember whether the -stmd- package I wrote for Stata enables this or not ... I tend to use Statamarkdown, myself (we do as much consulting in R as in Stata, these days).

[Christopher Bratt]

I work with RStudio. Sorry, Jupiter Notebook just isn't for me (and most of my coding is in R, none in Python).
(My current solution is to develop a do-file, execute the code in Stata, then later let Quarto read the do file and print its code -- with highlighting. No execution of Stata code is done within Quarto.)

[Tim Huegerich]

Christopher Bratt, I'm not sure if you already saw this in the Stata 18 wishlist thread, but FernandoRios shared that he has recently started using my nbstata package as a bridge to using Stata directly in Quarto. There's a little bit more about how he does that here.

[Christopher Bratt]

Tim Huegerich I saw it and thanked Fernando Rios in a PM. But I didn't want to comment publically without having tried the solution. I need to learn how to install nbstata in Quarto (it's long since I tried Python and installations there... and these days most of my time goest to teaching). But thanks for highligting this option, and thanks for developing nbstata!

[FernandoRios]

Indeed. I share the "time constrain" problem you feel Chris.
Luckily, there isn't much to do to install nbstata.
I have simply followed Tim's basic instructions:
- Install python,
- then pip install nbstata,
I'm guessing that I didn't need to do much in terms of setup, because I have a PC. So not sure if you need to tinker much with if you have different platforms.

from there you could do it in jupyter-lab (if you use that already). If you use R, I think you can do exactly the same.
Here a very small example:
Code:
https://github.com/friosavila/playin...to/example.qmd
output:
https://friosavila.github.io/playing...o/example.html
output:
https://friosavila.github.io/playing...to/example.pdf
Of course, this is just the tip of the iceberg!
F

[Doug Hemken]

FernandoRios Tim Huegerich nice! That might actually bridge the gap between me and some of my colleagues who use Jupyter!

[FernandoRios]

All thanks to Tim Huegerich
Now that I discover it, I see the advantages for easier dynamic reports, specially now that many are using some flavor of markdown or Jupyter notebooks!

[Tim Huegerich]

I have simply followed Tim's basic instructions:
- Install python,
- then pip install nbstata,

FernandoRios No, but you are the Stata Quarto pioneer! I'm really glad to learn that is possible. (I still haven't tried it, though I've actually been using Quarto indirectly via nbdev to create the nbstata docs. It's a literate programming small world..)

Just to be clear, did you also do the additional step described in the nbstata docs, running "python -m nbstata.install"? I'm guessing that would be needed to get Quarto to work, but I'm not sure.

[FernandoRios]

i think so...I just know it was easy.
You had extra instructions about how to set up smaller details, but I tried with the simplest and default approach, it worked!

[FernandoRios]

And just an extra example.
This follows the dyndoc example from Stata helpfiles.

https://github.com/friosavila/playin...h-pages/quarto
https://friosavila.github.io/playing...quarto/dynstat

F

[Dirk Enzmann]

Christopher Bratt : You are referring to a webcast by Chuck Huber (introduction to ado files). Where can I find this?

[Christopher Bratt]

Dirk Enzmann You can register here (for a webcast tomorrow, Tuesday 14 March):
https://www.stata.com/training/webin...tion-commands/