Stata Markdown

Posted on by



At GitHub, we’re building the text editor we’ve always wanted: hackable to the core, but approachable on the first day without ever touching a config file. We can’t wait to see what you build with it. The markstat command works with plain Stata Markdown scripts with no extra Stata commands required, but also plays well with Stata commands that generate fancy tables of estimates or statistics, as illustrated in the estout and tabout examples.

Informazioni su come aggiungere contenuto alla pagina di SharePoint Modern tramite la Web part incorporamento. Markdown is a simple, standardized text-formatting language that you can read about at Wikipedia. You mix Markdown with Stata commands that create the output you want. Think of the file you create as being a do-file on steroids. You then run dyndoc to produce a Word document (.docx) or webpage—an HTML file.

News

Use the Stata Jupyter kernel with Atom's Hydrogen package to show Stata results inline. It works with Windows, macOS, and Linux.

Example uses the Atom Material Syntax theme and Fira Code font.

Features

This package highlights:

  • System commands, functions, and function arguments
  • Macros, both global and local
    • Accurately colors nested macros and escaped macros in strings when you want the inner macro to evaluate at runtime
    • Colors macro extended functions inside `: .. ' as well as after local lname:
  • Comments, more accurately than Stata's Do-file Editor.
  • Regular expressions
    • Colors both the limited syntax provided through the regexr() and regexm() functions, as well as the vastly expanded regex syntax provided in Stata 14 and 15 through the ustrregexm(), ustrregexrf(), and ustrregexra() functions.
  • Dynamic Markdown and LaTeX documents. Instructions below.

Other nice features:

  • Works with unicode identifiers. Use unicode anywhere it's legal Stata syntax.
  • Autocomplete for functions with a drop-down help menu. (This can be turned off in the settings).
  • Autocomplete for commands and macros.
  • Alerts you if your variable name is illegal, i.e. if your variable name is more than 32 chars, starts with a number, or is a reserved name.
  • Alerts you if you have any text other than } on a line ending a foreach/forvalues/if/else command
  • Local macro back tick autocompletion. When you write a `, Atom automatically fills in a ' after your cursor
  • Makes it easy to spot incorrect nesting of compound quotes
  • Support for programming ligatures for all valid Stata syntax for fonts that support them, like the Fira Code font.
  • Highlights SQL queries used in the odbc command. (The language-sql base package must be active.)
  • Highlights Docblockr-style keywords inside comments (anything like @Note)

Installation

To install, do one of the following:

  • Go to Preferences/Settings > Install > Packages; and then search for language-stata
  • At the command line, type apm install language-stata

The local macro back tick autocompletion won't function until you fully restart Atom. Do ctrl-shift-P or cmd-shift-P to bring up the command palette, type Window: Reload, and click enter.

Configuration

Atom allows you to toggle whether a line is commented using ctrl+/. As of version 1.6.5, the comment character this uses is // by default. You can change this to use /* */ or * characters to comment lines.

To change to /* */ comments, you can put the following in your config.cson file.

To change to * comments, use the following. However I don't recommend using this character1.

Note that in your config.cson file there can only be a single '.source.stata' top-level key, and only a single editor key under '.source.stata'. If you customize some other settings within the Stata grammar, you might already have a '.source.stata' key, and thus you would add the commentStart key to it.

Running Code

There are three ways to run code in Stata from Atom

  1. The Hydrogen package in conjunction with the Stata Jupyter kernel shows Stata results inside Atom next to your code. The gif at the top of the page is an example of this setup. A few features:

    • Works with Windows, macOS, and Linux. Has an easier install on Windows than stata-exec.
    • Use a different session of Stata for each file, or connect them all to the same session.
    • Autocompletions as you type based on the variables and macros in memory
    • Use any type of comments in your code
    • Low-latency connections with remote sessions of Stata. Possible to reconnect to a running remote session if you get disconnected.
    • Use #delimit ; interactively with your code
    • Run code blocks within a Stata dynamic document

    You'll need to have both Hydrogen and stata_kernel installed. You caninstall Hydrogen from the Atom settings pane; see the stata_kerneldocumentation for moreinformation on how to install stata_kernel.

  2. The stata-exec package sends selected Stata code to an open Stata GUI window on Windows, macOS, and Linux. This differs from Hydrogen because it allows you to still interact with the Stata GUI. This might be easier for users who are new to Stata. However, it can be difficult to successfully install this on Windows.

  3. The script package will run code in the Stata console, but has the limitations 1) each command is run in a separate session of Stata, 2) it currently doesn't work with selections; you have to run the entire file, 3) it doesn't work on Windows.

Dynamic Documents

Stata 15 brought new features for working with dynamic documents. The dyndoc command lets you write in Markdown and converts your file and code to HTML for viewing in a web browser.

It also added the dyntext command, which fills in Stata output for any text file, without touching the text itself. This lets you then use third-party document generators like Pandoc and LaTeX to generate documents.

Syntax Highlighting

This package provides syntax highlighting for Stata code written inside Stata's dynamic tags for Markdown and LaTeX documents.

By default, this package's Markdown and LaTeX syntax highlighting will be applied for files ending in .domd and .dotex respectively. The language-markdown and language-latex packages must be installed for the highlighting to work.

If you name your file with a different extension, you can manually set the highlighting by clicking on the 'Plain Text' button on the bottom right of the screen (or by pressing CTRL+SHIFT+L). Then type stata and you'll see a list of choices:For a .do file, choose source.stata; for a Markdown dynamic document choose source.dyndoc.md.stata; and for a LaTeX dynamic document choose source.dyndoc.latex.stata.

Both Hydrogen and stata-exec should work for running code interactively, even within a dynamic document.

Examples

An example of the PDF output of using dyntext and Pandoc is in the examples folder: dyntext.pdf.

That file was created by running

from inside Stata 15, and then with

on the command line using Pandoc.

The file dyntext.dotex is a proof-of-concept and should compile with LaTeX but the output is not shown here.

Webdoc support

If you use the user-created commandwebdoc, you canadd highlighting by using a .dowd file extension or by manually selecting thelanguage of the current file to be 'Stata Webdoc'.

Footnotes

1: The following code is legal Stata code, but Atom will confuse the * used as multiplication with the * used for a comment. So if your cursor is on the second line and you press ctrl+/, Atom will remove the * symbol and the semantic meaning of the multiplication will be lost. Thus using // as the comment symbol is safer.

In July of 2017 I updated the Stata Tutorial for version 15, and it seemed a good time to convert it to a Stata Markdown script to be processed with markstat. In September of 2019 I updated it again, this time for version 16. A big advantage of using markstat is that it was very easy to update the tutorial, and I could generate a PDF file via LaTeX from the same script used for HTML. The latest script and the resulting HTML and PDF files are linked below, together with the bibliography and an ancillary fileexplained below:

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. To generate PDF you will also need the file tweaks.tex to match the style used here. The following notes may also be of interest in reproducing the output.

The Input Script

In the source script I used the simple 'one tab or four spaces' rule to indent code that should be run through Stata. To list code that is not to be run through Stata, for example to explain the syntax of a while loop, I used code fences as follows:

The code is rendered in HTML as a preformatted block, and in LaTeX as a verbatim environment. Duckling adv.anne 28 online, free games.

You will also note that I coded graphs using a caption-less figure, as in

Stata

The website uses the Bootstrap framework, and the two classes, img-responsive and center-block ensure that the figure is centered and displays well in devices of varying sizes. One exception is an image used to highlight version 15, where I used an img tag so it appears only in the HTML version. Another is the screen capture of the Stata interface, which I coded so it would appear in natural size in HTML and using the full page width in LaTeX, by coding

How to download whatsapp on mac. This takes advantage of the fact that Pandoc will pass along HTML and LaTeX code to the appropriate target format and ignore it otherwise.

I also collected all the bibliographic references in a BibTeX file, and cited them all using the nocite convention. The YAML block listed further below references the bibliography file and has a literal 'nocite' field.

Stata Markdown R

To publish the HTML to my website I split it into four files, one per section, adjusting the links.

Stata Markdown Mac

Tweaking LaTeX

Stata Markdown

I used caption-less figures because they appear nicely centered in the HTML output, but unfortunately LaTeX will add a figure number to the otherwise empty caption. This is easily avoided however, using the LaTeX command usepackage[labelformat=empty]{caption}, which adds the caption package with an option to supress labels. This is the only required tweak, and is easily added as part of the YAML block, but I decided to add a few more and collect them in a file called tweaks.tex. The YAML block used then reads

If you list the tweaks.tex file you will see that it uses

  • the caption package to supress figure numbers as noted above,

  • the titling package to modify rendering the title and author. I wanted to use a large bold sans serif font and include a subtitle and the URL of the tutorial. I also wanted to add my affiliation to the author field.

  • the sectsty package to modify the fonts used in all the section titles (including subsections, subsubsections, paragraphs and subparagraphs), using bold sans serif fonts of appropriate sizes.

  • the fancyvrb package to modify verbatim blocks so they match exactly the stlog environments used for Stata output.

These are just aesthetic changes that do not affect the content of the tutorial, but allow you to reproduce exactly the published file by simply typing markstat using tutorial, pdf bib.

Something else you may toy with when generating a PDF document is page breaks. Having looked at the document, however, I decided that the few cases where code or output was split across pages were alright and decided to let them be.

Note. The Stata Tutorial was first published in 2006 and targeted version 9, which makes the current version the 8th edition.