Stata 15 help for savedresults

Title

[P] storedresults -- Manipulate and verify stored results r() and e()

Syntax

storedresults save name {r()|e()}

storedresults compare name {r()|e()} [, tolerance(#) reverse verbose exclude(list) include(list) ]

storedresults drop name

where list is

class: name [name [...]] [list]

and class is macro, macros, matrix, matrices, scalar, or scalars.

This command is intended for authors of certification scripts -- do-files used to test that commands work properly; see [P] cscript.

Description

storedresults allows easy saving of the r() or e() stored results produced by a command and then later comparing other stored results with them.

storedresults save saves r() or e() under the name specified.

storedresults compare compares the current r() or e() results with those previously saved. If they are different, return code 9 is produced.

storedresults drop eliminates previously stored results from memory.

Options

tolerance(#) specifies the tolerance for numeric comparisons. The default is 0, meaning numerical results are required to be exactly equal.

Comparisons between scalars are made using the reldif() function and comparing the results to tolerance().

Comparisons between matrices are made using the mreldif() function and comparing the results to tolerance().

Comparisons between macros, if both contain numbers, is made using the reldif() function and comparing the results to tolerance(). If the previous results, current results, or both, for a particular macro do not contain numbers, then a string comparison is made between them and tolerance() is irrelevant for that comparison.

reverse might affect which r() or e() results are checked. The default is to compare all the previously stored results with current results, which means if an extra result is currently stored, that will not be detected. On the other hand, if a result was previously stored and is not stored now, that will be detected and, of course, when results were stored both previously and currently, they will be compared.

reverse turns this around. reverse specifies that the currently stored results are to be compared with what was previously stored. This means if a result is now stored that was not stored previously, it will be detected but, of course, previously stored results that are not now stored will go undetected.

The only way to be certain that the same results were stored both previously and now is to run the command twice, once with and once without the reverse option. Most authors of certification scripts, however, do not do that, nor do they bother to specify reverse.

verbose specifies that a list is to be displayed of what is being checked. The default is to produce output only when there are problems.

exclude(list) specifies that, from the list of all stored results (meaning all stored results previously, or all stored results now; see the reverse option above), the list of results specified is to be excluded from the comparison. The items in the exclude() list might not be stored at all (in which case there would be no reason to specify them), stored in previously but not currently, stored currently but not previously, or stored both times but you do not care if they have different values.

Specifying exclude() allows you to check a subset of the returned results.

For instance, if you wished to exclude the stored macros e(if), e(in), the stored scalar e(N), and the stored matrix e(V), you could specify

. storedresults comp ..., exclude(macros: if in scalar: N matrix: V)

include(list) specifies that only the stored results specified are to be compared. The list has the same syntax as when used with exclude(), just the meaning is reversed.

Remarks

In a certification script, one sometimes wants to verify that the same results are obtained when the command is run two different ways. For instance, if we were testing summarize, we might want to verify that the if exp modifier works:

. sysuse auto . keep if foreign . summarize mpg . storedresults save mustbetrue r()

. sysuse auto, clear . summarize mpg if foreign . storedresults compare mustbetrue r()

. storedresults drop mustbetrue

For your edification, it is useful to change the middle part of this script to read

. use auto, clear . summarize mpg /* omit the if foreign */ . storedresults compare mustbetrue r() /* so this is not true */

Running the first version of the script, storedresults will produce no output. Running the second version, storedresults will produce detailed output highlighting the differences in the stored result and, more importantly, will end with a return code of 9, meaning the certification script will stop.

As a second example, consider writing a script to verify that regress works with frequency weights:

. use auto, clear . expand mpg . regress price weight foreign . storedresults save unweighted e()

. use auto, clear . regress price weight foreign [fw=mpg] . storedresults compare unweighted e(), tol(1e-14)

. storedresults drop unweighted

Here the tolerance() option is required because, when this test script was tried without it, it was found that results had a maximum relative difference of about 4e-15, which was deemed to be acceptable. (In the final form of the test script, the final tolerance was lightened from the 4e-15 observed to 1e-14, for no good reason).


© Copyright 1996–2018 StataCorp LLC   |   Terms of use   |   Privacy   |   Contact us   |   What's new   |   Site index