Tips for Stata console mode

Graphics, Stata

There are really three main ways of interacting with Stata:

  • In batch mode
  • Console mode
  • Through the GUI

Batch mode is critical to reproducible, self-documenting code. Even if you don’t use it, its existence is a reflection of the idea of a single do-file that takes you from data to results in a single movement. Most people use Stata through the GUI, most of the time, though, even when their goal is a pristine goal-oriented do-file. Stata’s GUI is clean, efficient and pleasant to use.

Console mode, on the other hand, is like the dark ages: a text mode interface (reminiscent of the bad old days before Windows 3.1, of DOS and mainframes). Why would anyone use it?

Well, there are some distinct advantages. First, it cuts you off from almost no essential functionality (OK, that’s really a negative advantage). Second it is lightweight and fast, particularly over remote connections (much more responsive than using GUI-Stata over a VPN). Thirdly, you can integrate it better into alternative environments for writing Stata code, such as Emacs and ESS (it’s no insult to Stata’s interface programmers to say I really love having my multiple Stata sessions in multiple Emacs buffers, and to use Emacs code to process Stata output).

You do lose some functionality, however. You don’t have the data editor, of course. Nor the variables window (so you do a lot of des). You can’t click on links in the help (though you can read it perfectly well). These are potentially irritations but are not huge problems. What would be a show-stopper, however, is that you don’t have graphics.

The point of this post is to show how you can have graphics in Stata console mode, almost as conveniently as in the GUI. I work on Linux, but these tips should be translatable to Macintosh fairly easily, and probably to Windows too. The basic strategy is to export the graph as soon as you create it, and read the exported version (e.g. an EPS) in another programme. To facilitate this I’ve written a tiny program:

program define gx
 graph export /tmp/x.eps, replace
end

This creates x.eps in a temporary location, based on the most recent graph drawn. I can then run a program to display that, e.g., evince /tmp/x.eps &. On Unix, the ampersand puts the program running in the background, which is useful as evince will automatically re-read the graph if it changes. Thus it acts exactly like a built-in graph window. My typical use is as follows:

scatter y x
gx
!evince /tmp/x.eps &
scatter y x, msize(0.5)
gx

The ! runs the viewer from the Stata command line, and I only need to run it once per session. Each subsequent gx command triggers evince to update the display.

Two other handy Unix-based graphics utilities invokable from within Stata are

!convert -density 100 x.eps x.png
!epstopdf x.eps

which create respectively PNG and PDF versions of your graph, ready for inclusion in documents. The convert command is particularly useful, as Stata won’t write PNG files in console mode.

For remote use, this won’t work, but if you can write to an area that a web server can read, writing a PNG file and reading it in a web browser is another handy workaround. The following snippet illustrates this:

program gxpng
 syntax [, FILENAME(string)  DENSITY(integer 100)]
 if "`filename'"=="" {
 local filename x
 }
 graph export /tmp/`filename'.eps, replace
 !convert -density `density' /tmp/`filename'.eps /var/www/somewhere/`filename'.png
 !chmod 604 /var/www/somewhere/`filename'.png
end

Long-live text mode interfaces!