*! version 0.1 12Mar2021

help for bpencode

Title

bpencode - Encode into numeric using a variable or an Excel
file

Syntax

bpencode varname
[, options]

Options
vl(varname) is the variable used to label encoded values.

generate(newvar) specifies the name of the variable to be created. Defaults to _enc_varname

vlname sets the name of the value label. Defaults to vl.

metafile uses an Excel file to encode variables and label its values (see mdata extract).

vlsheet is the worksheet that contains value labels.

dropzeros removes trailing zeros from codes in labels.

Description

bpencode creates a new variable based on the variable varname.
A variable may be used to create a value label for the new encoded variable. Users may
also specify an Excel file to create and label the new variable. Unlike encode,
it's possible to use this command with a numeric variable in order to label its values.

If the variable is numeric, using this command will only serve to clone the variable. In
this case, the command is only useful to label variable's values using other variable from
the data set or an excel file.

For the string type, variables may contain only numbers, only letters or both. In the
first case, the command does the same as running real; In case the variable
only contains letters, values will be sorted and a numeric code is generated for each
level of the variable. When the variable contains values with numbers and letters (this
includes variables featuring rows with just letters and rows with just numbers), the encoding is
a mixture of the two previous cases: rows with digits only preserve their value, while rows
that contain only letters or letters and numbers are encoded according to the second case. In order
to guarantee that there are no overlapping values, the latter type rows are assigned values
that are larger than the maximum value for only digits rows.

The user may specify a variable from the data set in option vl that serves as
a value label for the encoded variable. In doing so, the value label created will be
of the form # desc, where # is the value of the original variable and desc
is the value of the variable used in option vl.

It's also possible to use an Excel file to encode and label a variable. To use this
option, the Excel worksheet should contain two columns - value and label, and
the labels should be of the form # desc.

Examples

Example 1: Label variable x, generating variable xnew and using variable xlab to
create value label xvl.

. set obs 3

. gen x = 1 in 1

. replace x = 2 in 2

. replace x = 3 in 3

. gen xlab = "one" in 1

. replace xlab = "two" in 2

. replace xlab = "three" in 3

. bpencode x, gen(xnew) vl(xlab) vlname(xvl)

Example 2: Encode string variable x, generating variable xnew and using variable xlab to
create value label xvl.

. set obs 3

. gen x = "01" in 1

. replace x = "02" in 2

. replace x = "0X" in 3

. gen xlab = "one" in 1

. replace xlab = "two" in 2

. replace xlab = "xvalue" in 3

. bpencode x, gen(xnew) vl(xlab) vlname(xvl)

Remarks

Please notice that this software is provided "as is", without warranty of any kind, whether
express, implied, or statutory, including, but not limited to, any warranty of merchantability
or fitness for a particular purpose or any warranty that the contents of the item will be error-free.
In no respect shall the author incur any liability for any damages, including, but limited to,
direct, indirect, special, or consequential damages arising out of, resulting from, or any way
connected to the use of the item, whether or not based upon warranty, contract, tort, or otherwise.

Dependencies

gtools package by Mauricio Bravo

Author

BPLIM, Banco de Portugal, Portugal.

Email: bplim@bportugal.pt

We appreciate your feedback. Comments are welcome!