help mata Elabel_ValueLabel()

Title

Elabel_ValueLabel() -- Manipulate value label (class)

Syntax

class Elabel_ValueLabel scalar l

void
l.setup(string scalar name)

void
l.setup(name,
real colvector vvec,
string colvector tvec)

void
l.reset()

void
l.reset(real colvector vvec,
string colvector tvec)

void
l.mark(real colvector touse)

void
l.markiff(string scalar expr)

void
l.markall()

void
l.define()

void
l.define(real scalar replace[,
real scalar fixformat])

void
l.modify()

void
l.modify(real scalar add[,
real scalar fixformat])

void
l.append([real scalar fixformat,
string scalar sep])

string scalar
l.name()

void
l.name(string scalar newname)

real colvector
l.vvec()

string colvector
l.tvec()

real colvector
l.null()

real colvector
l.touse()

real scalar
l.k()

real scalar
l.K()

real scalar
l.nemiss()

real scalar
l.sysmiss()

string rowvector
l.usedby()

void
l.list()

void
l.list(values,
text[,
real scalar noisily])

void
l._list([real scalar includename])

void
l.assert_add()

Description

Elabel_ValueLabel() returns instances of
class Elabel_ValueLabel. Elabel_ValueLabel() extends
Elabel_Utilities(). The class is
used for developing the elabel package. See
elabel_vl*() for the corresponding Mata
functions.

l.setup() sets up value label name. If name is an
existing value label, and if vvec and tvec are not specified,
the integer-to-text mappings from name are loaded and stored in
l. Specify vvec and tvec to create new interger to text
mappings. Note that no changes are made to value label name until
you l.define() or l.modify(). Think of l as a
copy of existing value label name or as a blueprint for new value
label name.

l.reset() replaces vvec and tvec in l. Without
arguments, vvec is reset to J(0, 1, .) and tvec is reset
to J(0, 1, "").

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

l.markiff() is an alternative to l.mark(). 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=="".

l.markall() is a convenience function, short for
l.mark(J(l.K(), 1, 1)), and selects all
integer values and text in l.

l.define() defines the value label name based on the
information in l. 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.

l.modify() modifies the value label name based on the
information in l. 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.

l.append() modifies the value label name based on the
information in l. If sep is not specified, integer values
in l must either not be present in existing value label name,
or if they are present in name, must define the same integer-to-text
mappings. If sep is specified, sep is used as separator to append
any text that is associated with the same integer value. If fixformat!=0,
the display format of variables that have value label name attached is
changed; see option nofix. This function respects touse.

l.name() without arguments returns the name stored in
l. If newname is specified name in l is changed
to newname.

l.vvec() returns real colvector vvec from l. This
function respects touse.

l.tvec() returns string colvector tvec from l. This
function respects touse.

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

l.touse() returns a real colvector indicating the rows
of vvec and tvec to be used.

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

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

l.nemiss() returns the number of extended missing values in
vvec. This function respects touse.

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

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

The function has an optional argument, update, that is best not
specified. If update==0, l.usedby(0) returns the
string rowvector that has previously been obtained from l,
which might or might not be related to name; when you
l.reset() or even l.setup() another name,
the result from l.usedby(0) will still be the same
string colvector that you have previously obtained.

l.list() and
l.list(values, text[, noisily])
both list the name and integer-to-text mappings in l in the same
format as Stata's label list. The types of values and
text are irrelevant because they are replaced with string scalars
holding the integer values and text in l, respectively. If
noisily==0, output is suppressed. These functions respect touse.

l._list() is called by l.list(); if
includename==0, the value label name is not listed. The function
respects touse.

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

Conformability

As indicated above.

Diagnostics

Not documented; class functions are for internal use.

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