I have a certain version of Stata and have come across a user-written program that is apparently written for a later version of Stata. What are my options?

1. Introduction

Suppose you have Stata 10.1. You may in fact have an earlier version, or indeed a later version, as you read this. You should be able to relate to examples here as long as you are clear that there are three possible situations: a Stata program may be written for the same version of Stata that you have, an earlier version, or a later version. It is the last situation that is the focus here.

2. The different meanings of version

You need to distinguish the four meanings of the word “version” in discussions of this and related problems. In programming jargon, the word is heavily overloaded.

2a. The version of Stata you are using

Any copy of Stata you run has a version. Stata itself will tell you the version in several ways, such as in the GUI when you start a session or if you type version, about, or display c(version). (If you have a really old version of Stata, some of these methods may not work.)

The version of Stata you are using is always displayed, such as 12, 11.2, 11.1, 11, etc. If you are not using the most recent version of Stata, the version you are using imposes limits on what you can do with user-written programs.

2b. The programmer’s personal version number

Most Stata commands are defined by programs written in Stata and defined by ado-files. The exceptions are part of the executable and do not come under this FAQ. Many programmers keep track of the history of their programs by including a comment such as

    *! version 3.10  20jan2009  Ben Jann

Usually, that comment is placed at or near the top of the ado-file. In the example above, the comment appears at the top of estout, a popular ado-file, as downloaded from SSC on 25 January 2009. The programmer, Ben Jann, has his own version number for estout so that he can keep track of which version is which. User-programmers often mimic a style used by StataCorp and common throughout computing: the first number marks major rewrites, and any following numbers mark minor changes.

The version number also can help users of any program keep track of which version they are using and whether they need to update. For example, if you have previously installed estout, then typing which estout will tell you which version you have installed.

This number also helps in dealing with bug reports. If you experience a problem with a user-written program, then check that you have the most recent version. Often a bug that bites you bit someone else first, and the bug is fixed in a later version.

As stated above, the line starting with *! is a comment. The initial * is what makes it a comment. Comments are generally ignored by Stata. However, the following ! makes that comment special, because the which command looks for lines beginning *! and echoes them to the Results window. Thus if you want to know which version of xyzzy you are using, then all you have to do is type which xyzzy, and you will see

    . which xyzzy
    *! version 3.10  20jan2009  Ben Jann

The above works whether xyzzy is a user-written command or an official Stata command.

Some programmers do not use the *! version number. You will find Stata’s own commands and most of the heavily used user-written commands generally do use it, but this is mainly an issue of style.

However interesting or informative you find this, remember that the *! version number used personally by the programmer has no implications whatsoever for whether your version of Stata is modern enough to use the program.

2c. The version declared within a program

The easy way to find out whether you can use a program is just to try it. Either the program will work or you might see something like

    . xyzzy 
    this is version 10.1 of Stata; it cannot run version 10.2 programs.
         A free update to version 10.2 is available; type update and follow the
         instructions, or visit http://www.stata.com/support/updates.  If you are
         not connected to the Internet, you can contact StataCorp to obtain the
         latest version.
         r(9);

Or you might see

    . xyzzy ...
    this is version 8.2 of Stata; it cannot run version 9.0 programs.
         You can purchase the latest version of Stata by visiting 
         http://www.stata.com
    r(9);

Let me show you how this works. We are going to have to look inside the program to do so. The easy way to do that is to type

    . viewsource name_of_ado_file

A Viewer window will display the source code.

For instance, say you have installed estout from SSC. If you type

    . viewsource estout.ado

you will see in the Viewer window something like

    *! version 3.10  20jan2009  Ben Jann

    program define estout, rclass 
        version 8.2 
        ...

Look for the version statement—not to be confused with the *! comment. The version statement is usually found near the top of the program, after the program statement.

estout is declared to be version 8.2, meaning it requires Stata 8.2 or a more recent version to run.

Most programs include at least one version statement. The first—which is often the only one—is usually found at or near the top of the program definition.

Often programs call other programs, and sometimes those programs call yet other programs. When that happens, the highest version number is that which bites. Thus if foobar, which declares itself to require version 8.2, calls frogtoadandnewt, which declares itself to require version 9, then you need at least Stata version 9 to run foobar.

Some programmers write branching code within their programs that detects the version of Stata you have and calls other code accordingly. For example, if you have Stata 9 or above, then a clever program may call fast and efficient Mata routines to do some work; if you do not have Stata 9, then the program calls code that will do the same job, albeit more slowly. In this way, it is possible that a program containing some code that would not run on your version of Stata is usable by you, because the program itself is smart enough to work around that limitation.

Precisely what version does is too complicated to explain in full detail here. There is no substitute for careful reading of the documentation for version. But you are warned against a surprisingly common misconception: that the version command is a time machine. It emphatically is not a time machine. version cannot be used to make an old Stata behave like a newer Stata.

What version does is set the clock back to make a more modern Stata behave like an older version or, at least, behave like an older version where that older behavior is important.

Here is the main idea. Suppose you have Stata 12, and a program includes the statement

    version 8.2 

Your copy of Stata 12 does not remove all the improvements and new features of Stata 12. What the version 8.2 statement does, in any case where there is a conflict between what was in Stata 8.2 and what is now in Stata 12, is to use the Stata 8.2 interpretation.

It is difficult (impossible, really) for you to be certain that what you have within Stata 12 will work exactly as it would in Stata 8.2 unless you test it by running a physical copy of Stata 8.2. You might be exploiting a new, nonconflicting feature introduced since Stata 8.2 without realizing it.

Some users tend to look at version 8.2 at the top of a program and say, “Oh, this will work with Stata 8.2”. That statement is necessarily true if the program was written only on Stata 8.2. version is about forward compatibility, not backward. What is true, and all that is guaranteed to be true, is that a program written on Stata 8.2, with a version 8.2 statement at the top, will continue to work properly with future versions of Stata.

By the way, on occasion there can be good and subtle reasons for omitting a version statement. But, more commonly, a program (or a do-file for that matter) would benefit from a version statement.

If there is no version statement within a program, then that omitted statement can have no bite. But keep on reading.

2d. The version needed within a program

Programmers can be a little cavalier about what they say in any version statement included in their programs. There are two common styles:

• Some programmers write the version of Stata they are using as the version needed by their programs. Their thinking is, “I know that this program runs fine on this version of Stata, because that is the version on which it is being developed and tested by me. I am not going to commit myself to any backward compatibility.” In particular, StataCorp programmers think and act this way.
• Other programmers write down an earlier version of Stata as the version needed by their program. Their thinking is, “I believe that this program does require at least that version of Stata, because it needs certain features introduced then.” For example, a program may require the current Stata graphics introduced in Stata 8 or a particular version of the ml engine introduced in another version of Stata.

In either case, note that many Stata programmers either do not have older versions of Stata on their machines or lack the time and inclination to test whether their program would run successfully on an older version. So any version statement given explicitly within a program may not be the exact version of Stata that the program needs.

Also it is not wrong to declare a version statement either less than or more than what is really needed, so long as the version number is not greater than the version of Stata being written for.

3. Looking inside a program

You may want to look inside a program to see what version is declared. Even if the documentation includes information on the Stata version required, checking on the facts will do no harm. The documentation can be wrong, most commonly because the documentation itself is out of date. In any case, what the program requires is all that matters. Stata pays no attention to anything said in the help file or anywhere other than the program itself.

Using viewsource to look inside a program was mentioned earlier; you may also find it helpful to learn about findfile. Simply using type to type a program may be enough. (With ssc, be aware of the subcommand ssc type.)

4. Choices

Now the question can be answered directly.

If you have Stata 9, and the foobar command appears to require Stata 9.2 and the bazz command appears to require Stata 10.1, what can you do?

4a. Upgrade

If your Stata version differs by 1 or more from what is required, you can purchase an upgrade to the current version from StataCorp.

4b. Update

If your Stata version has the same initial integer as what is required, you can update your Stata for free over the web. For example, you can update from Stata 10 to Stata 10.1 or from Stata 11 to Stata 11.2; just type update. You cannot update for free from (say) Stata 11.2 to Stata 12. That requires an upgrade, as described just above.

4c. Look for older versions or older alternatives

An older version of a program may be found. For example, the Stata Journal and the Stata Technical Bulletin archives retain all previous versions of any programs published therein; some packages in the SSC archives include versions for older Stata programs; some users’ websites allow you to download different versions of a program according to your version of Stata. Commonly, older versions are frozen as they were and are not updated, even when it is possible.

One common, but not universal, convention is that names like foobar7, foobar8, and foobar9 may signal versions of foobar for Stata 7, 8, or 9. The documentation will usually make this clear, but, if in doubt, you can look inside each program, as above. Another common convention is that foobar2 and foobar3 merely mark successive versions of foobar, but as Stata ages the chance of these two conventions clashing diminishes.

Similarly, there can be older alternatives. Using search (possibly with the historical option), using findit, or asking on Statalist can help here, perhaps by implying that no older alternative exists.

4d. Change the program

You can copy the program in question and try to change it so that it works under your version of Stata. This process will vary from being trivially easy to being essentially impossible, depending on how many newer features any program requires. The difficulty also depends on your knowledge of Stata.

At the easiest, it may simply be that the version statement specifies a version later than really needed. Thus, if you edit version 12 to version 11, then you may find that a program works under Stata 11.

But watch out:

• You now take full responsibility for what you have done, while etiquette still requires that you give full credit and respect to previous authors. Most program authors take mild to strong exception to others changing their program and then asking why it no longer works.
• You are advised to change the name of the program. For example, if your initials are XYZ, you might change foobar to foobar_xyz. Or if you adapt foobar to work on Stata 9, foobar9 is a possible name. Running findit with a possible program name will indicate any clashes of name with programs in the most accessible sources. If you do not change the name, you can confuse yourself and others you distribute the program to, even if you only use the program within a restricted group. You will find it difficult to keep track of which variation of the program you are running. And, if you keep the same name, you run the risk that your version will get overwritten, say, by an adoupdate. Finally, you should not put your version in the public domain where it can be confused with the original.
• Even if an edited program appears to work satisfactorily, that is not a guarantee that your version produces identical results to the original.
• The original program authors will commonly have little or no interest in rewriting a program to work on an older version of Stata for you.

But often a program would require more drastic surgery to the extent that your only real choices are to upgrade, update, or do without.

5. A note on help files

Stata 10 and later versions of Stata look first for help files with extension .sthlp and second for help files with extension .hlp. Conversely, Stata 9 and earlier versions know nothing about the .sthlp extension.

Thus if you managed to get a Stata 10 program working in Stata 9, then you would normally be best advised to rename any .sthlp files to have the .hlp extension.

The previous section implies that it is now good practice to edit the help files to indicate what has been changed and who is now responsible, namely, you.

Acknowledgments

David Elliott suggested, on Statalist, that an FAQ be written on this topic. He, William Gould, Ben Jann, and Richard Williams made very helpful comments on a draft.