help for docvars (Version 2.1, 30Aug2022)

Create a Stata dataset which documents the variables in an existing dataset

Document variables in memory.

docvars [varlist] [,
{docvars_options}]

Document variables in file

docvars [varlist] using filename
[, {docvars_options}]

options

varlist List of variables to be summarized. Default is all
variables in memory or, if using is specified, in the "used" file.

using filename Specifies that the variables to be
summarized are in a file not currently in memory. The opened file is
never altered in any way by the execution of docvars.

clear empties memory to allow docvars to open a new
data set with the using option.

dtaname(string) string used to identify the data set to which
variables belong. If blank, the filename is used.

compress document the compressed data type (potype) as well as
the original data type (actype)

saving(datafilename,[replace]) name of new
dataset containing one observation per variable. The replace option specifies
that the version in memory will replace an older version in mass storage.

Description

docvars is an extension of describe. Like the describe
command, docvars lists descriptive attributes for the variables given by
varlist or, if varlist is not specified, for all variables in the current dataset.
Like descsave by Roger Newson (st0043_1), on
which it is based, docvars creates a new Stata dataset which
contains summary information about all the variables in the input
dataset. The newly created dataset contains an observation for each
variable in the original dataset and a variable for each of 23 summary
characteristics of the original variables.

Output dataset specified by saving()

The data file specified by saving() has one observation per
variable. It contains the following variables:

Name

Description

quesno Question sequence in data file

idstr File identifier

name Variable name

actype Actual storage type

potype Potential storage type (only if compress option used)

format Display format

vallab Value label

varlab Variable label

nobsmax No of obs. this data set

nobs No of obs. this variable

nmiss No. of missing or blank

nonseqms No. of non-sequentially missing

mean Mean

sd Std. deviation

min Minimum

max Maximum

nneg Number of negative values

nnegint Number of negative integers

nzero Number of zero values

npos Number of positive values

nposint Number of positive integers

nunique Number of unique values

nundoc Number of observations of a labeled
numeric variable which are "undocumented" in the sense that they
do not have labels.

nreal Number of observations of a string
variable which can be converted to numeric values.

mode Modal value of the variable, whether it be numeric or string.

Remarks

The variable quesno contains the sequential order of the variable
in the input varlist specified for docvars or the order
of that variable in the dataset, if the user does not specify an
input varlist. The variable idstr is a string identifier set
by default to the name of the original dataset.

The variables nneg, nnegint, nzero, npos, nposint and
nunique are the output of Stata's inspect command.
The variable nundoc is a modified version of the output from the
inspect command. In the situation where a variable has been
assigned a label, but the label is not in the dataset, the variable
nundoc reports that all non-missing observations are undocumented.

The variable nonseqms is a count of the number of times that a
variable is missing even though the preceding variable was not missing.
Given knowledge of the skip patterns in a questionnaire, this variable
can help to determine how frequently a variable is "unjustifiably"
missing. For example, if a "no" response to question 5 directs the
interviewer to skip to question 10, then the data should contain many
instances when questions 6, 7, 8 and 9 are all missing and the latter
three are "sequentially missing". In this situation, it would be
reassuring if the values of the variable nonseqms were zero for
questions 7, 8 and 9. Counts greater than zero, on the other hand, would
indicate that the original data contained values of these variables that
were "unjustifiably" missing. (Feature: For datasets with a large number
of variables, nonseqms is set to missing every K variables, where
K is 340 or greater depending on the amount of memory assigned to
STATA.)

The other variable names are self-explanatory. They are produced from the output
of Stata's commands describe and inspect with two exceptions.
For string variables, nobs and nmiss give the number of non-blank and the number
of blank observations, respectively.
The modal value is produced by Stata's command egen ... = mode(varname) with the option (cmd:minmode)
so that, for a variable with multiple equal modes, the smallest is presented.
For string values, the first in the alphanumeric sort order is presented.

Examples

. docvars using bigfile, clear

. docvars using bigfile, clear saving(vrbls_in_bigfile.dta, replace)

The following example accumulates the information on all the variables
in three datasets into a single small file.

. docvars using bigfile1, clear saving(vrbls_in_bigfile1.dta, replace)

. docvars using bigfile2, clear saving(vrbls_in_bigfile2.dta, replace)

. docvars using bigfile3, clear saving(vrbls_in_bigfile3.dta, replace)

. use vrbls_in_bigfile1, clear

. append vrbls_in_bigfile2

. append vrbls_in_bigfile3

. save vrbls_in_bigfiles, replace

. erase vrbls_in_bigfile1

. erase vrbls_in_bigfile2

. erase vrbls_in_bigfile3

The created file vrbls_in_bigfiles can now be analyzed in order to
diagnose some of the most important problems with the three included
datasets. Start by issuing the summarize command in order to see
the maximum number of observations, missing values, etc..

. use vrbls_in_bigfiles, clear

. describe

. summarize

Then execute the tab command in order to list the names of the three datafiles, bigfile1,
bigfile2 and bigfile3, together with the number of variables in each of
those files.

. tab idstr

Subsequent tabulations can, for example, reveal how many missing
var1ables are in each of the data sets.

. tab nmiss idstr

or find the number of variables with a small number of unique values but
no value labels.

. tab nundoc if nunique < 10

Author

Mead Over, Center for Global Development, Washington, DC.

Email: MOver@CGDev.org

Also see

Manual: [U] 15.8 Characteristics,

[R] describe, [R] destring, [R] gsort,
[R] insheet, [R] label, [R] outsheet,
[R] tabulate, [R] xi, [R] egen

[P] char

Online: help for describe, codebook, inspect

help for descsave if installed

{Version 1.9, 20Jun2021 Correct typo referring to the variable -idstr- as -dtaname-}{Version 2.1, Add the statistic -mode- to those computed and saved for each numeric or string variable}