help for varlabdef(Roger Newson)

Define a value label with values corresponding to variables

varlabdef labelname [ , vlist(varlist) from(from_option) replace nofix ]

where labelname is a name for a value label,
and from_option is one of

order | name | type | format | vallab | varlab | char characteristic_name

and characteristic_name is the name of a variable characteristic.

Description

varlabdef creates (or extends) a value label,
with one value for each of a list of variables,
and labels copied from the variable labels, variable names, or other variable attributes.
This value label may be re-used in output datasets (or resultssets),
with observations corresponding to the variables.
Such output datasets may be created using packages such as parmest,
downloadable from SSC.

Options

vlist(varlist) specifies the list of variables corresponding to the new values of the value label.
If vlist() is absent, then the full list of variables in the current datasetr is used,
unless there are no variables in the memory,
in which case varlabdef fails.

from(from_option) specifies the source of the labels corresponding to the new values corresponding to the variables.
The possible values of the from_option are
order, name, type, format, vallab, varlab, or char characteristic_name.
These imply that the labels corresponding to the variables will be copied, respectively,
from the order of the variable in the varlist specified by vlist(),
the variable name,
the variable storage type, the variable format,
the value label, the variable label,
or the named characteristic of the variable.
If from() is not specified,
then the default is varlab,
implying that the value label for each new value is copied from the variable label of the corresponding variable.
The values of the from() option correspond to the variable names of the output dataset (or resultsset)
produced by the descsave package, which can be downloaded from SSC.

replace specifies that, if a value label with the specified labelname already exists,
then that label will be dropped before a new label with the same name is created.
If replace is specified, or if no value label with the specified labelname already exists,
then the new values are defined as consecutive integers starting with 1.
If replace is not specified, and a value label with the specified labelname already exists,
then the new labelled values are added to the existing labelled values,
and are defined as consecutive integers,
starting from 1 or from the lowest positive integer above any existing non-missing labelled value,
whichever is higher.

nofix acts as the nofix option of the label define command.
It defines the action of varlabdef
when a value label with the specified labelname already exists,
and is the value label for one or more existing variables in the dataset.
Without the nofix option,
varlabdef finds all the variables that use this value label,
and widens their display formats, if necessary,
to be wide enough for the longest of the new labels.
nofix prevents this.

Remarks

varlabdef was designed to be used with output datasets (or resultssets)
created by the parmest package, which can be downloaded from SSC.
The parmest package creates datasets with 1 observation for each of a set of estimated parameters.
These datasets sometimes include string variables containing the names or labels
of the Y-variables and/or X-variables corresponding to these estimated parameters.
varlabdef can be used in the original dataset, containing the data from which the parameters are estimated,
to create a value label,
with a value for each of a list of variables,
and labels containing the names or variable labels of these variables.
This value label can then be saved to a do-file,
using the label save command.
When the estimation commands have been executed,
and the output datasets (or resultssets) have been created,
the user can execute the saved do-file to re-create the value label in the new output dataset.
It is then possible to use the official Stata encode command,
or the sencode command downloadable from SSC,
to input the string variables containing the names and/or labels
of the Y-variables and/or X-variables,
and to create new numeric variables,
with the string values as labels.
These new numeric variables are useful if the user wants to produce plots of confidence intervals,
which may be produced using the eclplot package, downloadable from SSC.

The parmest, sencode, sdecode and eclplot packages can all be downloaded from SSC.
So can the descsave package,
which is also useful for passing information about variables from one dataset to another.
For more about resultsset processing,
see the References in the on-line help for parmest.

Examples

. sysuse auto, clear

. varlabdef mylabs

. lab list mylabs

. varlabdef yvarlab, vlist(length weight mpg price)

. lab list yvarlab

. varlabdef yvarlab, replace

. lab list yvarlab

. varlabdef yvarname, vlist(length weight mpg price) from(name)

. lab list yvarname

Saved results

varlabdef saves the following in r():

Scalars

r(firstval) first value added by varlabdef

r(lastval) last value added by varlabdef

Macros

r(vlist) variables specified by vlist()

r(from) from() option

Author

Roger Newson, National Heart and Lung Institute, Imperial College London, UK.

Email: r.newson@imperial.ac.uk

Also see

Manual: [D] label, [D] encode, [D] decode, [P] char

On-line: help for label, encode, decode, char

help for parmest, sencode, sdecode, descsave, eclplot if installed