help crosswalkhttps://github.com/benjann/crosswalk/

Title

crosswalk -- Recode variable based on crosswalk table (bulk recoding)

Syntax

Recode variable using crosswalk table

crosswalk newvar =
fcn(varname [case])
[if] [in] [, options ]

Generate case indicator

crosswalk newvar =
casefcn(arguments) [if] [in]
[, replace ]

Assign value labels

crosswalk label lblset
[varlist] [, label_options ]

Define custom crosswalk table in memory

crosswalk define fcn[()]
<line 1>
<line 2>
...
end

List names of custom crosswalk tables in memory

crosswalk dir

Delete custom crosswalk tables from memory

crosswalk clear

options Description

expandok allow non-unique crosswalk table and expand data if needed

missing treat missing values like other values

copyrest[(nolabel)] copy values that are out of scope

copymissing[(nolabel)] copy extended missing values

label([lblset][, minimal]) assign custom value labels

nolabel omit automatic value labels

string enforce string format

numeric enforce numeric format

noinfo omit out-of-scope information

out(outname) store out-of-scope indicator

fast do not restore data on error or break if expandok is specified

replace allow overwriting existing variables

label_options Description

name(lblname) provide a custom name for the value label

modify modify (rather than replace) existing value label

minimal only include labels for existing values

fcn() Description

Scales for ISCO-08
isco08_to_isei() ISCO-08 to ISEI scores

isco08_to_iseisps() alternative to isco08_to_isei()

isco08_to_siops() ISCO-08 to SIOPS scores;
isco08_to_treiman() is a synonym

isco08_to_oep() ISCO-08 to OEP scores; also see

isco08_3_to_oep()

isco08_2_to_oep()

isco08_1_to_oep()

isco08_to_esec() ISCO-08 to ESEC classes; also see

isco08_3_to_esec()

isco08_to_oesch() ISCO-08 to OESCH classes; also see

isco08_to_oesch8()

isco08_to_oesch5()

oesch_to_oesch8()

oesch_to_oesch5()

Scales for ISCO-88
isco88_to_isei() ISCO-88 to ISEI scores

isco88_to_siops() ISCO-88 to SIOPS scores;
isco88_to_treiman() is a synonym

isco88_to_oep() ISCO-88 to OEP scores; also see

isco88_3_to_oep()

isco88_2_to_oep()

isco88_1_to_oep()

isco88_to_mps() ISCO-88 to MPS scores

isco88_to_esec() ISCO-88 to ESEC classes; also see

isco88_3_to_esec()

isco88_to_egp() ISCO-88 to EGP classes; also see

isco88_to_egp11()

isco88_to_oesch() ISCO-88 to OESCH classes; also see

isco88_to_oesch8()

isco88_to_oesch5()

oesch_to_oesch8()

oesch_to_oesch5()

Scales for ISCO-68
isco68_to_isei() ISCO-68 to ISEI scores

isco68_to_siops() ISCO-68 to SIOPS scores;
isco68_to_treiman() is a synonym

isco68_to_egp() ISCO-68 to EGP classes; also see

isco68_to_egp11()

Translation
isco08_to_isco88() ISCO-08 to ISCO-88

isco88_to_isco08() ISCO-88 to ISCO-08

isco88_to_isco88com() ISCO-88 to ISCO-88(COM)

isco88_to_isco68() ISCO-88 to ISCO-68

isco68_to_isco88() ISCO-68 to ISCO-88

isco68_to_isco08() ISCO-68 to ISCO-08

Aggregation
isco08_to_isco08_3() 4-digit to 3-digit ISCO-08; also see

isco08_to_isco08_2()

isco08_to_isco08_1()

isco08_3_to_isco08_2()

isco08_3_to_isco08_1()

isco08_2_to_isco08_1()

isco88_to_isco88_3() 4-digit to 3-digit ISCO-88; also see

isco88_to_isco88_2()

isco88_to_isco88_1()

isco88_3_to_isco88_2()

isco88_3_to_isco88_1()

isco88_2_to_isco88_1()

Other
myname() custom crosswalk table

casefcn() Description

case.egp() EGP case function for ISCO-88

case.egp68() EGP case function for ISCO-68

case.esec() ESEC case function for ISCO-08

case.esec88() ESEC case function for ISCO-88

case.oesch() OESCH case function

case.myname() custom case function

lblset

egp EGP labels; also see
egp11

esec ESeC labels

oesch OESCH labels; also see
oesch8,
oesch5

isco08 ISCO-08 labels; also see
isco08_3,
isco08_2,
isco08_1

isco88 ISCO-88 labels; also see
isco88_3,
isco88_2,
isco88_1

isco88com ISCO-88(COM) labels; also see
isco88com_3,
isco88com_2,
isco88com_1

isco88a ISCO-88 labels by Ganzeboom/Treiman; also see
isco88b

isco68 ISCO-68 labels

myname custom label set

Description

crosswalk applies fast table-based recoding. Pre-defined
crosswalk tables are provided for common recoding tasks related to occupational
classifications. See below on how to define
custom crosswalk tables.

crosswalk works via indexing or hash tables, depending on type of
data. The heavy lifting is done by Mata function
mm_crosswalk() from the moremata package
(Jann 2005), which needs to be installed on the system (see
ssc describe moremata).

crosswalk supersedes command iscogen (Jann 2019).

Options

Main options

expandok allows the crosswalk table to contain duplicate origin values
and adds observations to the dataset if needed. By default, crosswalk
requires the origin values in the crosswalk table to be unique, such that
each value of varname only has a single match in the crosswalk table. Specify expandok
to allow duplicate origin values. In this case, if an observation has multiple matches
in the crosswalk table, copies of the observation will be added to the data,
one for each match (similar to forming pairwise combinations using joinby).

missing treats missing values like other values. The default is
to exclude missing values from the evaluated subsample. Only one of
missing and copymissing is allowed.

copyrest[(nolabel)] copies values that are
out of scope into the generated variable (within the subsample
selected by if and in). By default, the generated
variable will be set to missing for observation without match in the
crosswalk table. Specify copyrest to retain the original values for
these observations rather than setting the variable to missing. Unless
argument nolabel is specified,
copyrest also copies all value labels from varname
to the generated variable (but note that individual labels may subsequently
be overwritten by labels obtained from lblset). copyrest
implies copymissing unless missing is
specified or the source variable is string. Furthermore, copymissing
implies string or numeric depending on the data type of the
source variable.

copymissing[(nolabel)] copies extended missing
values into the generated variable (within the subsample selected by if
and in). Specify copymissing if the source variable has extended
missing values that you want to pass through to the generated variable;
value labels of extended missings will also be copied, unless argument
nolabel is specified. copymissing implies numeric and
is only allowed if the source variable is numeric. Only one of
missing and copymissing is allowed. Only one of copyrest
and copymissing is allowed.

label([lblset][, minimal]) specifies a
lblset to be used for the value labels. By default,
when applying function origin_to_destination(),
the lblset called destination will be used, if such a
set exists. Suboption minimal requests that only values be labeled
that exist in the data; the default is to include all defined
labels. label() has no effect if the generated variable is
string. Specify nolabel to omit the automatic assignment of value
labels.

string enforces string format for the generated variable. The default
is to use a numeric format as long as all destination values in the
crosswalk table are numeric.

numeric enforces numeric format for the generated variable even if
there are nonnumeric destination values. Only one of string and
numeric is allowed.

noinfo omits the information on levels of varname that are out
of scope (i.e., levels of varname that have no match in the crosswalk
table). This saves some computer time.

out(outname) adds an out-of-scope indicator to the data (1 if
no match in the crosswalk table, else 0; missing if outside of
the evaluated subsample).

fast does not restore the original dataset if expandok has been
specified and there is an error or the user presses Break. This saves
memory and some computer time. fast has no effect if expandok is omitted.

replace allows overwriting an existing variable.

Options for crosswalk label

name(lblname) provides a custom name for the value
label. By default, a separate set of labels is assigned to each variable
using the name of the variable as the name of the value label. Specify option
name() to use a common set across all variables. If name() is
omitted and varlist is empty, a single set called lblset will
be created.

modify causes existing value labels to be modified rather than replaced.

minimal equests that only values be labeled that exist in the data. The default is to
include all defined labels. minimal is only allowed if varlist is specified.

Remarks

The case argument
Custom crosswalk tables
Custom case functions
Custom label sets

The case argumment

Some crosswalk tables contain multiple destination columns,
each representing a specific case. Use argument case in
fcn(varname case) to
select the destination column. Argument case may be one of the following.

casevar a numeric variable indicating the destination column of each observation (1 for the first
destination column, 2 for the second destination column, etc.)

exp an expression, possibly involving multiple variables

casefcn(arguments) a special-purpose function
determining the destination column

For example, the translation of ISCO-88 codes into EGP classes depends on
employment status and supervisory function. See the documentation of
isco88_to_egp() for detailed information. You could use you own code to
construct a variable, say egpcase, indicating the appropriate combination
of employment status and supervisory function for each observation
(1 = employee without subordinates, 2 = employee with 1 subordinate, etc.),
and then specify

. crosswalk newvar = isco88_to_egp(varname egpcase)

Alternatively, use pre-defined case function
case.egp() as in

. crosswalk egpcase = case.egp(sempl supvis)

. crosswalk newvar = isco88_to_egp(varname egpcase))

or, equivalently, in

. crosswalk newvar = isco88_to_egp(varname case.egp(sempl supvis))

where sempl contains the employment status (0 = employed, 1 = self-employed)
and supvis contains the number of subordinates or employees.

Argument case will be ignored by crosswalk tables that only have a
single destination column.

Custom crosswalk tables

Custom crosswalk tables can be defined on the fly using crosswalk define,
or be provided permanently as files on disk (in the working directory or
somewhere else along the adopath). For example, you could type

. crosswalk define myrecode()
1 3
2 2
3 1
.a .b
end

and then used the defined crosswalk table as follows:

. crosswalk Y = myrecode(X), missing

Each line after crosswalk define specifies a recoding rule consisting of
an origin value followed by a destination value (or several destination values;
see the case argument). Empty lines are
not allowed, and the input must be terminated by keyword end.

Alternatively, you could make myrecode() available by
storing

1 3
2 2
3 1
.a .b

in file _cwfcn_myrecode.sthlp in the working directory. The syntax of
crosswalk files is as follows.

o Each line defines a recoding rule consisting of an origin value
followed by one or several destination values. The values must be
space-separated.

o Values containing spaces must be enclosed in single quotes ('...'),
double quotes ("..."), or compound double quotes (`"..."').

o Empty lines and lines starting with * will be ignored.

o Line starts an SMCL formatted
section that will be ignored. Line ends the SMCL section.

o The filename must start with prefix _cwfcn_ and end with
suffix .sthlp.

A crosswalk table can also be implemented as a wrapper for
one or several other crosswalk tables (only one wrapper level is
allowed; that is, wrappers cannot call wrappers). Within a wrapper, use
alias syntax .fcn to call crosswalk table fcn(). For
example, the definition of isco08_to_esec() is

. crosswalk define isco08_to_esec()
.isco08_to_isco08_3
.isco08_3_to_esec
end

This means that isco08_to_esec() first calls
isco08_to_isco08_3()
to translate 4-digit ISCO-08 to 3-digit ISCO-08, and then
isco08_3_to_esec() to translate
3-digit ISCO-08 to ESeC.

Custom case functions

A custom case function called case.myname()
can be provided by storing file _cwcasefcn_myname.sthlp
in the working directory or somewhere else along the adopath. Similar
to a crosswalk table, the file may contain SMCL
sections that will be ignored. Apart from that, the file is assumed to contain
Stata code that will be called by crosswalk using command run. The following
arguments are passed through: the name of the variable to be
generated, the name of the variable marking the evaluated subsample,
any other arguments specified by the user.

Custom label sets

Label sets have the same format as crosswalk tables, but their name must start
with labels_. For example, type

. crosswalk define labels_myrecode
3 "New three (was 1)"
2 "Two (did not change)"
1 "New one (was 3)"
.b "New missing (was .a)"
end

to provide label set myrecode. You could then use it together with
crosswalk table myrecode() defined above about as follows:

. crosswalk Y = myrecode(X), missing label(myrecode)

Hint: Use name labels_destination if you want to provide labels that will be
picked up automatically by crosswalk table
origin_to_destination().

Examples

Generate ISEI scores from ISCO-88 codes:

. crosswalk isei = isco88_to_isei(job)

Translate ISCO-88 to ISCO-08:

. crosswalk job08 = isco88_to_isco08(job)

Translate 4-digit ISCO-88 unit groups to 2-digit sub-major groups:

. crosswalk job_isco2 = isco88_to_isco88_2(job)

Generate EGP classes from ISCO-88 codes:

. crosswalk EGP = isco88_to_egp11(job case.egp(selfemp nemployees))

Assign ISCO-88(COM) labels to multiple variables:

. crosswalk label isco88com job_mother job_father

Stored results

Command crosswalk newvar = fcn() stores the
following results in r().

Scalars:

r(string) 1 if the generated variable is string, else 0

r(r_out) number of levels of varname that are out of scope; only if noinfo is not specified

r(N_add) number of added observations; only if expandok is specified

Macros:
r(fcn) name of applied fcn()

r(lblset) name of applied lblset

r(newvar) name of generated variable

r(varname) name of source variable

r(case) case specification

r(levels_out) list of levels of varname that are out of scope; only if noinfo is not specified

Command crosswalk newvar = casefcn() stores the
following macros in r().

r(casefcn) name of applied casefcn()

r(newvar) name of generated variable

Command crosswalk label stores the following macros in r().

r(lblset) name of applied lblset

r(lbname) name(s) used for the value labels

r(varlist) specified variables

Command crosswalk define stores the name of the defined
function in macro r(fcn).

Command crosswalk dir stores the number of functions in scalar r(n)
and a space separated list of the function names in macro r(fcns).

References

Jann, B. 2005. moremata: Stata module (Mata) to provide various functions. Available
from https://ideas.repec.org/c/boc/bocode/s455001.html.

Jann, B. 2019. iscogen: Stata module to translate ISCO codes. Available from
https://ideas.repec.org/c/boc/bocode/s458665.html.

Author

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

Thanks for citing this software as follows:

Jann, B. 2025. crosswalk: Stata module to recode variable based on
crosswalk table (bulk recoding). Available from
https://ideas.repec.org/c/boc/bocode/s?.html.

Also see

Online: help for
recode, label, merge, joinby,
moremata