Software

Guide to integrating Stata and external text editors

Download: rundo3.zip (240 KB), rundolines3.zip (240 KB)

Table of contents

1. Introduction
2. Requirements
3. Installation
4. Using the programs
5. Known problems and troubleshooting
6. Acknowledgments
7. History of the programs

1. Introduction

Stata is a statistical package that is available for Windows, Macintosh and Unix operating systems. This guide addresses some shortcomings of the text editor that is part of the Stata package. Stata's so-called Do-File Editor is fully integrated and commands can be executed directly from the editor with a keyboard shortcut or the click of a button. External editors often have a richer set of features, including syntax highlighting, but they lack integration with Stata.

This document describes how external text editors can be integrated with Stata in a way similar to the Do-File Editor. Two free programs are offered for this purpose: rundo.exe allows the execution of complete Stata do-files from an external editor, and rundolines.exe allows the execution of selected Stata commands from an external editor. Both programs can be installed and used together or individually.

2. Requirements
Please contact the author at fhuebler@gmail.com if you use the programs with any editor besides EmEditor, Notepad++, and UltraEdit, so that the list of supported text editors can be updated. I would also like to hear if you have been able to install the programs under Windows Vista. Thank you.

3. Installation

The integration of an external text editor with Stata can be accomplished in three easy steps:
  1. Download and extract the rundo and rundolines programs.
  2. Edit the INI files.
  3. Find a way to call rundo.exe and rundolines.exe from the text editor with a keyboard shortcut, a menu entry, or an icon in the toolbar.
Step 1: Download the rundo and rundolines programs and save the contents of the two ZIP files anywhere on your computer. One suggested location is the personal ADO directory of Stata, usually C:\ado\personal\. Each ZIP archive contains three files: the executable, the source code, and an INI file.

The programs were written and compiled with AutoIt version 3.2.10.0. Users who prefer to compile the programs themselves can do so with the included source code.

Step 2: Edit the INI files for the rundo and rundolines programs. rundo.ini and rundolines.ini are identical and list five options that must be edited to match the user's setup.
The last three options are specified in milliseconds. The default values should work for most users but they can be reduced for a faster execution of the rundo and rundolines programs. If the pauses are too short, the programs fail and no commands are passed on to Stata.

Figure 1: Stata program window
Stata program window with title in upper left corner

Step 3: Find a way to call rundo.exe and rundolines.exe from the text editor with a keyboard shortcut, a menu entry, or an icon in the toolbar. This example shows how the programs can be linked to Notepad++, a free text editor for MS Windows. For Stata users, an optional language file for syntax highlighting is available in the Notepad++ download section. Other text editors can also be integrated with Stata if they provide an option to call the rundo and rundolines programs; many editors have this capability.
  1. rundolines:
    • In Notepad++, go to the Run menu and select Run.
    • Browse to rundolines.exe and enclose the entire path in quotes. For example, if rundolines.exe is saved in the directory C:\ado\personal\, the complete entry in the Run box of Notepad++ would be:
      "C:\ado\personal\rundolines.exe"
    • Click Save.
    • Enter a name, for example "Run do-lines", and select a shortcut, for example F9 (see Figure 2).
    • Click OK, click Cancel.
  2. rundo:
    • In Notepad++, go to the Run menu and select Run.
    • Browse to rundo.exe enclose the entire path in quotes. Next, add the text "$(FULL_CURRENT_PATH)" (with quotes) after the path to rundo.exe. For example, if rundo.exe is saved in the directory C:\ado\personal\, the complete entry in the Run box of Notepad++ would be:
      "C:\ado\personal\rundo.exe" "$(FULL_CURRENT_PATH)"
    • Click Save.
    • Enter a name, for example "Run do-file", and select a shortcut, for example F10.
    • Click OK, click Cancel.
Figure 2: Notepad++ shortcut setup
Notepad++ dialog to add the rundo and rundolines programs

4. Using the programs

After the programs have been successfully installed, Stata commands can be executed directly from the text editor. In the case of Notepad++, press F10 to run a saved Stata do-file. To run only a few commands, highlight the relevant lines in the editor and then press F9.

The rundo program sends the path of the do-file to the Stata Command window, preceded by the word "do" and followed by Enter. If more than one instance of Stata is open, the do-file is executed in the Stata window that was most recently active. If Stata is not open, the rundo program starts Stata and then runs the do-file. Note that a do-file must be saved before the rundo program is called because it looks for the saved version of the document that is currently being edited. An alternative would be to first select the entire text in the editor and then call the rundolines program, which passes all selected lines to Stata.

The rundolines program saves the highlighted lines in a temporary file and then sends the path of the temporary file to the Command window in Stata, preceded by "do" and followed by Enter. If more than one instance of Stata is open, the commands are executed in the Stata window that was most recently active. If Stata is not open, the rundolines program starts Stata and then runs the selected commands.

The rundo and rundolines programs are self-contained, they do not create any files besides a temporary file with Stata commands, and they make no changes to the Windows registry. As the source code shows, the only function of the programs is to copy commands from the text editor and pass them on to Stata. However, both programs overwrite the contents of the Windows clipboard directly after they are executed because the clipboard is used to store the path to the Stata do-file.

5. Known problems and troubleshooting

Some users have reported that they were unable to install the rundo and rundolines programs under Windows Vista. I do not know if that means that the programs are incompatible with Windows Vista. This document will be updated when I know more about Windows Vista. In the meantime, the troubleshooting hints in this section apply to Windows XP and earlier versions of Windows.

Problem 1: If the rundo and rundolines programs fail, the clippause, winpause and keypause values may be too small. In that case, edit rundo.ini and rundolines.ini, increase the pause values (especially for winpause and clippause), and then run the programs again. For best results, the values in the INI files are long enough so that the rundo and rundolines programs do not fail and short enough to avoid noticeable delays before the execution of the commands in Stata. The default values in the INI file should work on most systems.

Problem 2: A second known problem involves keyboard shortcuts to rundo.exe and rundolines.exe that use combinations with Shift or Ctrl, for example Shift+F9 or Ctrl+F10. Such shortcuts can result in a "stuck" Shift or Ctrl key in Stata. This problem affects Notepad++ and other editors. Shortcuts without Shift or Ctrl are therefore preferred.

Troubleshooting: The rundo and rundolines programs should work if the installation instructions are followed exactly. If the programs do not work, please use the steps below to test your setup. I recommend testing the rundolines program first because its internal code is less complicated than the code for the rundo program.
  1. Save rundolines.exe and rundolines.ini in the same folder, as described in Step 1 of the installation instructions above. Do not edit and recompile the AU3 file.
  2. Edit the rundolines INI file as described in Step 2 of the installation instructions.
  3. Add a link to Notepad++ as described in Step 3 of the installation instructions.
  4. Start Stata.
  5. Start Notepad++ and type one or more Stata commands, for example "dir" (without quotes).
  6. Highlight the Stata commands in Notepad++ with the mouse or by pressing Ctrl+A.
  7. Press F9 (or any other shortcut that was assigned to rundolines.exe) to call the rundolines program. Stata should now run the commands from Notepad++. If the commands are not executed, the rundolines program cannot find Stata because the window title in the INI file is incorrect. If this is the case, edit rundolines.ini to match the title of the Stata program window, as shown in the installation instructions. For example, note the difference between "Stata" and "Stata/SE". Save the INI file and repeat steps 4 to 7 until it is possible to run commands from Notepad++ in a copy of Stata that is already open. Move on to the next step.
  8. Close Stata but keep Notepad++ open.
  9. Highlight all Stata commands in Notepad++ with the mouse or by pressing Ctrl+A.
  10. Press F9 (or any other shortcut assigned to rundolines.exe) to call the rundolines program. Stata should now start and run the commands from Notepad++. If Stata does not start, review the rundolines.ini file and make sure that the path to the Stata executable is correct. For example, note the difference between wstata.exe and wsestata.exe. Save the INI file and repeat steps 8 to 10.
When the rundolines program works as expected, the troubleshooting steps can be repeated for the rundo program. However, rundo.exe is more complicated than rundolines.exe and may not work with as many editors as the rundolines program. Recall that rundolines can do the same as rundo: to run an entire Stata do-file simply highlight all text in the editor (usually by pressing Ctrl-A) and then call rundolines.exe.

6. Acknowledgments

The rundo and rundolines programs are based on previous work by Dimitriy Masterov and Eva Poen. Masterov demonstrated in a post to the Stata mailing list how a do-file can be executed from Vi. Poen showed how individual lines can be executed from WinEdt. Nicholas Winter suggested changes to the programs that made them more efficient and solved some problems with the Windows clipboard. Jeffrey Arnold described how INI files can be used to set program parameters, making it possible to distribute precompiled and thus more user-friendly versions of the rundo and rundolines programs. Many others tested the original AutoIt scripts with different editors, suggested modifications, or provided general feedback; for additional acknowledgments please refer to the Supported Editors and Acknowledgments sections of the original version of this guide.

7. History of the programs
 Related articles

External links

Originally posted at huebler.blogspot.com on 27 April 2008 (edited 24 June 2008).
Permanent URL: http://huebler.info/2008/20080427-stata.html