ckvaredit - Editing attached validation rules
ckvaredit [varlist] [, stepthru]
ckvaredit brings up a dialog box which can be used to set validation (or scoring) rules which are then used by ckvar for data validation. This help file will describe the use of the dialog box.
stepthru allows stepping through the variables one at a time. If specified, the first variable in the varlist is automatically chosen at the start, and clicking the save button advances the variable to the next variable in the variable list when clicked. This can be useful for working with large datasets.
Using the ckvaredit Dialog Box
The steps are simple: 1. Choose a variable. 2. Choose a purpose. This is typically done just once for the first variable, and typically is the default choice of Validation. 3. Edit the rule. 4. Decide if missing values are errors. 5. Include names of other variables needed for validation/scoring. 6. Pick which of the buttons at the bottom to push. 6.1. Click Save to Save your changes and keep working, or 6.2. Click Reset to Discard your changes and keep working, or 6.3. Click Done to Save your changes and stop, or 6.4. Click Cancel to Quit without saving any changes for this variable 7. Repeat as needed. If you get frustrated, see the notes below.
Choosing a Variable
Choose a variable from the dropdown box under Variable to Check. If you specified the stepthru option, this will already have a variable name in it, but you can select another variable if you like. The box will be grayed out if you have made changes in the right column which have not yet been saved. If you made the changes to the wrong variable, click the wide Reset button extending across the dialog box near the bottom.
Choosing a Purpose
The two main choices are either Validation (valid) or Scoring (score).
The default choice of Validation will be the correct choice for validating the data, and hence will be correct most of the time.
If you will use ckvar to score an instrument or test, select the Scoring choice.
You should rarely, if ever, need to select the Other button and then specify your own stub. The only time this could be useful would be if there were multiple scoring algorithms for the same data, and you would like to include all of them in the same dataset. If you do choose this option, you need to read and understand how ckvar uses characteristics. (You can read about it here.)
Editing the Rule
There are two types of rules: simple and complex. (Valid validation rules are described below.) Most validation rules will be simple.
If you have a simple validation rule, enter it in the field provided.
If you have a complex validation rule, click the Edit Complex Rule button, and edit the rule in the window that opens up. Do not edit the complex rule directly in the dialog box field, because it will not get saved properly. Some other oddities occur when editing complex validation rules, because of switching to a Do-file editor window to do the editing:
A more condition will appear in the results window. Do not clear it. If you do, the changes you make in the do editor window will be lost.
When you are satisfied with the mini-do-file you have written, close the window, saving the changes when prompted.
Click the Done Editing Complex Rule button. This will clear the more condition, save the changes, and put a message in the results window.
Click the Refresh Complex Rule button to update the rule in the dialog box.
If you would like more information about editing complex rules without using the do editor, take a look here.
By default ckvar considers missing values to be valid values. Click the Required to be non-missing checkbox if missing values are considered errors for the variable you are working on.
If you check the Required to be non-missing checkbox, you can also enter a value which will be used in the error-marking variable for missing values. By default, ckvar uses -1 as the value for missing values when validating data and +1 as the value for other errors to distinguish between errors of omission and errors of commission. If you do not want to make this distinction, change the Value Used to Mark Missing Values to 1.
If you are scoring an instrument or test rather than doing data validation, the default score for missing values is 0.
Noting Other Variables
If you specified a complex rule which uses other variables to validate the current variable, be sure to enter the names of those variables in the Other Variables Needed for Checking box. Filling this in allows ckdrop, ckkeep, and ckrename to work properly in keeping the data verification from failing at a future time. It also helps ckvar prevent odd error messages from cropping up. You do not need to enter any variables if you use a like syntax, because the helper commands for ckvar will track them down.
Buttons to Push!
To save the changes and continue working, click the Save button. You do not need to separately save complex rules, as they are saved at the time you click the Done Editing Complex Rule button. Note that saved changes are saved changes. You cannot revert to old rules after committing the changes.
If you specified the stepthru option, clicking the Save button will automatically choose the next variable for editing. In this case, the Save button can be used as a Next Variable button---there is no danger of destroying anything by clicking it when no changes have been made.
The Reset button repopulates the dialog box with the current state of the saved rules for the given variable. It thus can be used to either get rid of unwanted and unsaved changes or to refresh the dialog box with current, saved rules. There is no way to revert anything which has already been saved.
The Cancel button acts as one would expect: it closes the dialog box without saving any changes for the currently selected variable. Hitting the escape key has the same effect.
The Done button saves the current changes, if any, and closes the dialog box. Unlike standard Stata dialog boxes, it does not result in executing a Stata command.
This dialog box is not a standard Stata dialog box, because its purpose is to edit information in the dataset rather than construct a single Stata command. It does its best to prevent careless errors by disabling items which it thinks should not be edited. If you really are stuck, hit the Reset button. You will lose minor changes that you might have made, but you will also be given access to all the items in the dialog box again. If you run into problems, please let me know about them.
The validation rules you specify using the ckvaredit dialog box are attached to the variables using characteristics. Since this is meant to be as transparent as possible, you do not need to understand characteristics either to use the dialog box or ckvar itself.
INCLUDE help ckvar_rule_syntax
Online: ckvar, ckchar
Bill Rising, StataCorp email: firstname.lastname@example.org web: http://homepage.mac.com/brising