Getting an error in a do file can be wearisome so in this article will explain how you can continue the file even when the do file encounters an error. The capture command or a capture prefix” can facilitate a do file to proceed irrespective of an error.
What is the capture command and how it’s helpful?
The capture command suppresses the output including the error term in a do file and makes the file run smoothly and continuously.
Download Example FileLet’s import the auto data using the following command:
sysuse auto.dta, clear
Let’s first run a few commands that would not produce any error and later with the same commands we will demonstrate if these same commands had an error. Stata would run regression smoothly using the regress command. For example, as shown in the image below, weight is regressed on rep78, price on mpg, and so on.
regress weight rep78 regress price mpg regress mpg rep78
The above three commands were executed perfectly and we did not have any error.
Now to demonstrate the idea of capture command, let’s distort the price variable in a way that when we use it in the above commands, it would produce an error.
replace price=.
We have replaced the values in the price variable with missing values. See the picture below, the price variable do not have values in them and now, if we regress price on any variable, it should produce an error.
Related Article: How to use Stata Do file? Tips and Tricks
Now if we execute the same three regressions.
regress weight rep78 regress price mpg regress mpg rep78
The first regression of weight on rep78 would be executed without any error, but because we do not have any values in price variable, the second regression or price over mpg will produce an error. You would also note that the third regression was not executed as the program or the do file had stopped running. Whenever a do file will produce an error it will stop execution of subsequent commands.
To prevent error messages to appear and run the file smoothly, the “capture” command can be used as a prefix.
Using Capture Command as a Prefix
The way to enter the capture command is to add a colon after capture i.e. Capture: before any command that contains error. The capture will prevent the error to be shown and run the file further. So executing the same command with capture wouldn’t display any error message in the file.
capture: regress price mpg capture regress price mpg
We can either use capture with or without a colon. We know from above discussion that regressing price on mpg will produce an error. But from the picture below you can see that when we used the capture prefix, Stata did not produce an error.
What the capture command did is, it suppressed the output, and as there exists an error message in the output, it is also suppressed and not shown in the output window.
Again running the regressions we run in the first image, but now replacing the second regression with capture: regress price mpg, will get us regression results of the first and third regression but the second regression wouldn’t show any output results due to capture command. It didn’t show any return code or error message either, because now the return code is suppressed.
regress weight rep78 capture: regress price mpg regress mpg rep78
One thing to note here is that capture will even suppress the output of the commands that are correct and do not have any error with them. For example, in above case if capture is used with the first and third regression, although it would execute the command (i.e. will run the regression) but the about will not be displayed in output window. That happens because capture suppresses the output of any command. But if you wish Stata to display the output and you also wish to use capture command, then the way forward is with noisily. Noisily instructs Stata to display output. From the below command you can see, although capture suppress the output, but because we have used noisily, the output is displayed.
Related Article: Preserve and Restore Data in Stata
capture noisily regress mpg rep78
Getting to Return Code in Stata
Return code is an error displayed by the Stata, when the command is not executed successfully. Let’s take the previous example of regression where the price is regressed on mpg. Now, without using a capture command, the regression result would be displayed as an error, and we will get a return code i.e. r(2000)
However, after using the capture command, no error message and return code are shown. But, for some reason, if we want a return code, a command of display_rc can be used.
capture: regress price mpg display _rc
In the case of a normal regression (the first and third regression in our example), where values of both variables are accurate and no error message is expected, running display _rc after the successful regression result will have a value of zero for the return code. The zero value of the return code depicts that the command is executed successfully.
Having a return code is useful because we can use it in some conditional statements. Check example below.
capture: regress price mpg if _rc!=0 { gen price2=1 } How does Capture Block in Stata work?
When we have multiple commands that might produce error, then instead of writing capture prefix with each command we can use capture block. To demonstrate this idea, let’s generate two variables named “a” and “b” in the Stata with the gen command.
gen a=1 gen b=1
Now we want to drop these two variables generated above; a and b, but also another variable “c” (although this c variable do not exist in our data), for the sake of demonstration.
drop a b c
Now the way Stata works is that it will either execute the whole command or will not execute it at all. In above code as we do not have c variable in our dataset, so this whole drop command will not be executed as it is producing an error.
But what if we add capture prefix with above command would it drop variable a and b then?
capture: drop a b c
We can see that event then this command was not executed, capture just suppresses the error and if a command do have an error that whole command will not be executed.
To drop variables a and b with the capture command, we need to use the capture block command. So what the capture block command will do is capture the multiple commands and execute them. For instance, here we wish to drop variables a, b and c without showing an error for c variable. So the multiple commands we wish to executed are 1) drop the variables a and b from the variables list, and 2) don’t show the error message. So the capture block will drop the variables in sequencing (a, b, c) without showing any error message. The sequence is important because if a variable that doesn’t exist in the list of variables (c in this case), but comes before any present variable ( a and b in this case), the present variables wouldn’t be dropped from the list of variables either.
To simplify the above statement, assume that we wish to drop variables a, b and c in the following way; capture drop {a , c , b}. Note that, in this case, c variable comes before b variable.
capture { drop a drop c drop b } As the c variable doesn’t exist, the capture drop command will drop a, but it would not drop b because it comes after the error variable-c. So this means that this whole capture block will stop execution as soon as it hits an error. All command within capture block that comes before an error will be executed but any command after the error will not be executed.
A better way to deal with this is to use capture with each drop command.
capture: drop a capture: drop b capture: drop c
Although capture block is useful it does have its limitation, so use it wisely.
