help mata elabel_vl*()

Title

elabel_vl*() -- Manipulate value label

Syntax

(transmorphic)
vl = elabel_vlinit(string scalar name)

(transmorphic)
vl = elabel_vlinit(name,
real colvector values,
string colvector labels)

void
elabel_vlcopy(vl, vl2)

void
elabel_vlset(vl, real colvector values,
string colvector labels)

void
elabel_vlmark(vl, real colvector touse)

void
elabel_vlmarkiff(vl, string scalar eexp)

void
elabel_vlmarkall(vl)

void
elabel_vldefine(vl)

void
elabel_vldefine(vl, real scalar replace[,
real scalar fixformat])

void
elabel_vlmodify(vl)

void
elabel_vlmodify(vl, real scalar add[,
real scalar fixformat])

string scalar
elabel_vlname(vl)

void
elabel_vlname(vl, string scalar newname)

real colvector
elabel_vlvalues(vl)

string colvector
elabel_vllabels(vl)

real colvector
elabel_vlnull(vl)

real colvector
elabel_vltouse(vl)

real scalar
elabel_vlk(vl)

real scalar
elabel_vlK(vl)

real scalar
elabel_vlnemiss(vl)

real scalar
elabel_vlsysmiss(vl)

string rowvector
elabel_vlusedby(vl)

void
elabel_vllist(vl)

void
elabel_vllist(vl, values, labels)

void
elabel_vllistmappings(vl)

void
elabel_vlassert_add(vl)

Description

elabel_vl*() functions manipulate value labels. Technically, the
functions access the elements in
class Elabel_ValueLabel and are provided
so the class does not have to be used directly; see
elabel development.

elabel_vlinit() returns vl that you pass to the other
elabel_vl*() functions; if you declare vl, declare it
transmorphic. In vl, if name is an existing value label,
and if values and labels are not specified, the integer to
text mappings from name are loaded. Specify values and
labels to define new integer-to-text mappings. Note that no
changes are made to value label name until you
elabel_vldefine(vl) or
elabel_vlmodify(vl). Think of vl as a copy of existing
value label name or as a blueprint for new value label name.

elabel_vlcopy() copies vl to vl2; if you declare vl2,
declare it transmorphic. This function respects touse.

elabel_vlset() replaces values and labels in vl.

elabel_vlmark() specifies the integer values and text
in vl to be used by other functions. Default is
touse=J(rows(values), 1, 1), meaning that
all integer-to-text mappings are used.

elabel_vlmarkiff() is an alternative to elabel_vlmark(). Instead
of specifying a real colvector you pass a string scalar containing
an eexp that evaluates to true (!=0) or false
(==0) for each integer value and associated text. The function does nothing
if eexp=="".

elabel_vlmarkall() is a convenience function and specifies that all
values and text in vl are used by other functions.

elabel_vldefine() defines the value label name based on the
information in vl. If replace!=0 is specified, existing value
label name is replaced. If fixformat!=0, the display format
of variables that have value label name attached is changed; see
option nofix. This function respects touse.

elabel_vlmodify() modifies the value label name based on the
information in vl. If add!=0 is specified, only new integer
to text mappings may be added to existing value label name. If
fixformat!=0, the display format of variables that have value label
name attached is changed; see option nofix. This
function respects touse.

elabel_vlname() without arguments returns the name stored in
vl. If newname is specified name in vl is changed
to newname; remember that value labels are neither defined nor
modified until you elabel_vldefine(vl) or
elabel_vlmodify(vl).

elabel_vlvalues() returns real colvector values from vl. This
function respects touse.

elabel_vllabels() returns string colvector labels from vl. This
function respects touse.

elabel_vlnull() returns a real colvector indicating the rows of
labels that are empty, i.e., null strings. This function respects
touse.

elabel_vltouse() returns a real colvector indicating the rows
of values and labels to be used.

elabel_vlk() returns the number of integer-to-text mappings in
vl. This function respects touse.

elabel_vlK() (note capitalization) returns the number of integer
to text mappings in vl, ignoring touse.

elabel_vlnemiss() returns the number of extended missing values in
values. This function respects touse.

elabel_vlsysmiss() returns a real scalar indicating whether
values has system missing values. System missing values are usually
considered an error in value labels but Mata allows them. This function
respects touse.

elabel_vlusedby() returns a string rowvector of variable names
that have value label name attached (in the current label
language).

elabel_vllist() and
elabel_vllist(values, labels) both list the
name and integer-to-text mappings in vl in the same format as
Stata's label list. The types of values and labels
are irrelevant because they are replaced with string scalars
holding the integer values and labels in vl, respectively. These
functions respect touse.

elabel_vllistmappings() list only the integer-to-text mappings in
vl, exclding the name. This function respects touse.

elabel_vlassert_add() exits with the respective Stata error message
if any of the values in values is already defined in the value label
stored in vl. This function respects touse.

Conformability

As indicated above.

Diagnostics

Not documented in detail; functions are provided for convenience. If there is
a problem with the arguments that you pass, the functions typically exit with
Mata error messages and produce traceback logs. elabel_vlinit(),
elabel_vldefine(), and elabel_vlmodify() exit with Stata error
messages if a problem occurs. If name or newname are not valid
Stata names, the respective Stata error message is issued.

Source code

Distributed with the elabel package.

Author

Daniel Klein

University of Kassel

klein.daniel.81@gmail.com

Also see

Online: mata

if installed: elabel