Stata 15 help for cscript

Title

[P] cscript -- Begin certification script

Syntax

cscript [["]text["]] [adofiles adofile-list]

Description

cscript begins a Stata certification script.

It displays a header, performs a which on any listed ado-file (see [R] which), and drops all

value labels macros programs scalars matrices constraints equations previous estimation results

cscript resets matsize to 400 for Stata/IC, Stata/SE, and Stata/MP; see [R] matsize. cscript also sets linesize to 79; see linesize. cscript also sets maxiter to 100; see maxiter. cscript also sets emptycells to keep; see [R] set emptycells.

The purpose is to reset Stata to default conditions so certification scripts may be run one after the other without the results of one certification script affecting the results of another. The default for maxiter in Stata is 16000, but cscript sets it to 100 so test scripts with bad models will not have excessive run times. Programmers must specify the iterate() option on commands they want to iterate more than 100 times; see [R] maximize.

Remarks

Remarks are presented under the following headings:

Introduction Other documented and undocumented commands for writing certification scripts An example certification script Combining certification scripts Writing a good certification script

Introduction

cscript is not documented in the manual because it would not interest many users.

A certification script is a do-file that tests whether a feature of Stata, an ado-file, or even a community-contributed command works.

The first line of a certification script do-file should read

cscript description_of_test

For instance,

cscript sktest or cscript sktest under usual conditions

might be the beginning of a do-file that tests sktest. If sktest is an ado-file -- as it is -- then a better opening would be

cscript sktest adofile sktest or cscript "sktest under usual conditions" adofile sktest

or, if you prefer, you may perform the which for yourself following the cscript command:

cscript sktest which sktest

Which style you use makes no difference, but you should perform the which. This way, if you save a log of running the certification script, you will know which version of sktest you last tested.

Other documented and undocumented commands for writing certification scripts

assert verify truth of claim confirm argument verification cscript_log control SMCL log files lrecomp display log relative errors mkassert generate asserts rcof verify return code savedresults manipulate and verify stored results r() and e() version run command under version control

Type help followed by the command name for more information.

The reldif() (relative difference) and mreldif() (matrix relative difference) functions are also helpful in certification scripts; see reldif().

An example certification script

At StataCorp, if we have an ado-file called mycmd.ado, we write a corresponding certification script called mycmd.do. The script might be

--- BEGIN --- mycmd.do ------------------------------------------------ cscript mycmd adofile mycmd

use xmpl mycmd x1 x2 assert abs(r(z)-2.5)<=1e-15

keep if x3==2 mycmd x1 x2 local hold = r(z)

use xmpl, clear mycmd x1 x2 if x3==2 assert r(z) == `hold'

rcof "noisily mycmd x1" == 102 /* too few variables specified */ rcof "noisily mycmd x1 x2 x3" == 103 /* too many variables specified */ ----- END --- mycmd.do ------------------------------------------------

A real certification script would be much longer.

Combining certification scripts

At StataCorp, we then combine all our certification scripts into a super certification script. mycmd.do then becomes one element of the super script:

--- BEGIN --- super.do --- do anova do assert ... do merge do mycmd ... ----- END --- super.do ---

We can run all the certification scripts by typing do super.

Writing a good certification script

The purpose of a certification script is to

1. test that the command produces the right answers in a few cases where the solution is known;

2. establish that the command works as it should under extreme conditions, such as R^2=1 regressions;

3. verify that the command responds to mistakes users are likely to make in a dignified manner.

Certification scripts are written for two reasons:

1. To establish on day one (the day the command is written) that the command works.

2. To allow future changes to be made to the command with some assurance that the changes really are improvements. (One simply reruns the certification script.)

A good certification script stops when there is a problem. This way, typing

. do mycmd [output omitted] end of do-file

and seeing it run to completion (that is, seeing Stata respond "end of do-file" with return code 0) demonstrates that, at least for the recorded problems, the command works as expected. You do not want a script where you are required to review the output to determine whether there are any mistakes. Thus, a script that included the lines

regress mpg weight regress mpg weight displ

would be a poor test of regress. If the results were wrong, would you notice? A better test script would read

regress mpg weight assert abs(_b[weight]- -.0060087) < 1e-7 assert abs(_b[_cons]- 39.44028) < 1e-5

regress mpg weight displ assert abs(_b[weight]- -.0065671) < 1e-7 assert abs(_b[displ]- -.0052808) < 1e-7 assert abs(_b[_cons]- 40.08452) < 1e-5

and one that read

regress mpg weight assert abs(_b[weight]- -.0060087) < 1e-7 assert abs(_b[_cons]- 39.44028) < 1e-5 assert abs(_se[weight]-.0005179) < 1e-7 assert abs(_se[_cons]- 1.614003) < 1e-6

regress mpg weight displ assert abs(_b[weight]- -.0065671) < 1e-7 assert abs(_b[displ]- -.0052808) < 1e-7 assert abs(_b[_cons]- 40.08452) < 1e-5 assert abs(_se[weight]-.0011662) < 1e-7 assert abs(_se[displ]-.0098696) < 1e-7 assert abs(_se[_cons]- 2.02011) < 1e-6

would be even better.

To establish that the command responds to mistakes, see rcof. Scripts should include intentional mistakes and then verify results are as expected. For instance,

discard /* eliminate regression results */ rcof "regress" == 301 /* should be "last estimates not found" */

rcof suppresses all output of the command, so induced errors are usually coded with a noisily placed in front of the command.

rcof "noisily regress" == 301

See [P] quietly.


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