help mata mm_crosswalk()

Title

mm_crosswalk() -- Translate values between classifications (bulk recoding)

Syntax

transmorphic vector
mm_crosswalk(x, from, to [, d,
n])

transmorphic vector
mm_crosswalk_hash(x, from, to [, d])

where

x: transmorphic vector containing values to be translated

from: transmorphic vector containing the origin values of the
crosswalk dictionary; from must be of the same type as x; the values in
from are assumed to be unique (this is not checked)

to: transmorphic vector containing the destination values of the
crosswalk dictionary; to must have the same length as from

d: transmorphic scalar specifying a default destination value for
elements of x that do not have a match in from; alternatively, d
may be a transmorphic vector providing individual default values (must
have same length as x); in any case, d must be of the
same type as to; the default for d is missingof(to)

n: real scalar specifying the maximum length of the
index-based crosswalk vector; this is only relevant if x and from
are integer and non-missing such that fast index-based translation is
possible; if the index-based crosswalk vector would be longer than
n, mm_crosswalk() automatically switches to the (slower but more
memory-efficient) hash-based translation algorithm; the default for
n is 1e6

specify n<1 to enforce
the hash-based algorithm; specify n=. to enforce the index-based
algorithm, provided x and from are integer and non-missing; specify
n=.z to enforce the index-based algorithm and skip any checks for
noninteger or missing values in x and from; use n=.z
to save computer time if you know that x and from are
integer and nonmissing (the function may break or return invalid results
if these assumptions are not met)

in any case, usage of the index-based algorithm is only considered if x
and from have storage type real

Description

mm_crosswalk() translates x based on the dictionary provided
by from and to. That is, for each element in x, mm_crosswalk()
looks for a match in from and then returns the element from to that
has the same index as the matched element in from. Think of
mm_crosswalk() as a way to bulk-recode x where the element-by-element
pairs of from and to provide the recoding rules. Value
d is returned for elements in x that have no match in from.

If feasible, mm_crosswalk() uses a fast translation technique based on
indexing. This requires all elements in x and from to be integer and
nonmissing (also see the description of argument n above). In all other
cases a hash-based algorithm is employed (implemented in terms of
asarray()). The hash-based algorithm is slower than the
index-based algorithm, but it works with any type of input.

Function mm_crosswalk_hash() directly calls the hash-based algorithm.

Examples

Input and output may be of different type:

. mata:
: x = (1,2,3,4,5)'
: from = (2,3)
: to = ("two","three")
: mm_crosswalk(x, from, to, "--")
: end

. mata:
: x = ("one","two","three","four","five")
: from = ("two","three")
: to = (2,3)
: mm_crosswalk(x, from, to, .a)
: end

Partial recoding:

. mata:
: x = (1,2,3,4,5)
: mm_crosswalk(x, (2,3), (3,2), x)
: end

Conformability

mm_crosswalk(x, from, to, d, n)
x: n x 1 or 1 x n
from: l x 1 or 1 x l
to: l x 1 or 1 x l
d: 1 x 1 or n x 1 or 1 x n
n: 1 x 1
result: n x 1 or 1 x n (same orientation as x)

mm_crosswalk_hash(x, from, to, d)
x: n x 1 or 1 x n
from: l x 1 or 1 x l
to: l x 1 or 1 x l
d: 1 x 1 or n x 1 or 1 x n
result: n x 1 or 1 x n (same orientation as x)

Orientation of vectors does not matter for conformability, only length is relevant.

Diagnostics

The values in from are assumed to be unique such that the dictionary
defined by from and to is non-ambiguous (although not necessarily
bijective). Returned results will be arbitrary if this assumption is
not met.

The functions return void if x is void.

The functions return defaults as specified by d if from and
to are void.

Missing values are treated like any other values.

Source code

mm_crosswalk.mata

Author

Ben Jann, University of Bern, ben.jann@unibe.ch

Also see

Online: help for
moremata, editvalue(), asarray()