*! version 2.1 11Sep2022 by Mead Over

help for retainlblversion 2.1 11Sep2022

Title

retainlbl -- Retain and restore variable labels after collapse and reshape

Syntax

retainlbl
[varlist]
[, options]

store store the variable labels for variables varlist

restore restore the variable labels for variables varlist

addprefix(string) prepend this prefix to the beginning of all restored variable labels

addsuffix(string) append this suffix at the end of all restored variable labels

offprefix(string) remove this prefix from the beginning of all restored variable labels

offsuffix(string) remove this suffix from the end of all restored variable labels

missingok During the restore process, this option allows execution to continue despite missing variable labels.

Description

Some STATA operations, especially the collapse and reshape commands,
alter or destroy variable labels during execution. retainlbl
stores the variable labels of the varlist variables in global macros
and then, after the Stata command is executed, re-attaches those variable labels
to the reshaped or collapsed versions of the same variables.

For the variables whose variable labels are to be restored,
the user must first execute retainlbl with the store option
before destroying the labels. Then, once the variable-label-destroying command has
been executed, the user issues the retainlbl command a second time
with the restore option in order to restore the labels. See the example below.
Version 1.3 of this program also works with reshape through the approriate use of
the new option offsuffix(string) and the renamed option addsuffix(string).

retainlbl has no effect on value labels.

Options

store stores the variable labels as macros for later use during the same STATA session

restore retrieves the variable labels for the varlist variables and attaches them to the variables

addprefix(string) specifies a character string to prefix every restored variable label

addsuffix(string) specifies a character string to add to the end of every restored variable label

offprefix(string) specifies a character string to be removed from the beginning of every restored variable label

offsuffix(string) specifies a character string to be removed from the end of every restored variable label

missingok During the restore process, this option allows execution to continue despite missing variable labels.

Remarks

Since 1.3, retainlbl¨s basic function works with reshape wide as well as with collapse.
See known issues.

Examples

Example 1: Using retainlbl with collapse.
Load a Stata dataset of 12 observations each of which is a group of students with their average GPAs and number of academic hours.
These data are used in the first of two examples in Stata's documentation for collapse.

. webuse college, clear

. describe

Contains data from http://www.stata-press.com/data/r14/college.dta
obs: 12
vars: 4 3 Jan 2014 12:05
size: 120

storage display value
variable name type format label variable label

gpa float %9.0g gpa for this year

hour int %9.0g Total academic hours

year int %9.0g 1 = freshman, 2 = sophomore, 3 = junior, 4 = senior

number int %9.0g number of students

Sorted by: year

Execute retainlbl prior to the collapse command.

. retainlbl gpa hour year, store

Create a collapsed dataset of four yearly observations each of which contains the weighted mean of gpa and
hour for that year. Use the number of students in each group as a frequency weight.

. collapse (mean) gpa hour [fw=number], by(year)

See how -collapse- constructs the variable labels for the collapsed variables.

. describe

Contains data
obs: 4
vars: 3
size: 40

storage display value
variable name type format label variable label

year int %9.0g 1 = freshman, 2 = sophomore, 3 = junior, 4 = senior

gpa float %9.0g (mean) gpa

hour float %9.0g (mean) hour

Sorted by: year
Note: Dataset has changed since last saved.

While the label of the by variable, year, has been retained,
the labels of the collapsed variables, gpa and hour, are replaced by
the prefix "(mean)" and the variable name. Since retainlbl was issued
before the collapse command, we can now execute retainlbl
with the restore and addprefix(string) options in order to recover the
more informative original labels.

. retainlbl gpa hour, restore addprefix("mean: ")

Now see the variable labels after retainlbl ..., restore.

. describe

Contains data
obs: 4
vars: 3
size: 40

storage display value
variable name type format label variable label

year int %9.0g 1 = freshman, 2 = sophomore, 3 = junior, 4 = senior

gpa float %9.0g mean: gpa for this year

hour float %9.0g mean: Total academic hours

Sorted by: year
Note: Dataset has changed since last saved.

Example 2: Using retainlbl with reshape. Load a Stata dataset with multiple years of observations on individuals.

. webuse union, clear
(NLS Women 14-24 in 1968)

. describe

Contains data from https://www.stata-press.com/data/r17/union.dta
Observations: 26,200 NLS Women 14-24 in 1968
Variables: 8 4 May 2020 13:54
(_dta has notes)

Variable Storage Display Value
name type format label Variable label

idcode int %8.0g NLS ID

year byte %8.0g Interview year

age byte %8.0g Age in current year

grade byte %8.0g Current grade completed

not_smsa byte %8.0g 1 if not SMSA

south byte %8.0g 1 if south

union byte %8.0g 1 if union

black byte %8.0g Race black

Sorted by: idcode year

Individuals are identified by the variable idcode. Each individual is observed for multiple years.
The number of individuals observed varies from year to year.
The only variable that remains constant for an individual person (i.e. an individual idcode) over time is black.
Our objective is to reshape the data so that there is one observation by individual.
Of the variables that vary over time, we keep only union membership.
In order to retain its variable label, we begin by executing retainlbl with the option store.

. retainlbl union, store

Now we "reshape" the data from "long" to "wide" using reshape's more explicit syntax.

. reshape i idcode

. reshape j year

. reshape xi black

. reshape xij union

. reshape wide
(j = 70 71 72 73 77 78 80 82 83 85 87 88)

Data Long -> Wide

Number of observations 26,200 -> 4,434
Number of variables 8 -> 14
j variable (12 values) year -> (dropped)
xij variables:
union -> union70 union71 ... union88

After reshaping, the data retains the two individual specific variables, idcode and black, with their original variable labels,
but creates variable labels for the year-specific union* variables consisting of only the year variable and the variable name.

. describe

Contains data
Observations: 4,434 NLS Women 14-24 in 1968
Variables: 14
(_dta has notes)

Variable Storage Display Value
name type format label Variable label

idcode int %8.0g NLS ID

union70 byte %8.0g 70 union

union71 byte %8.0g 71 union

union72 byte %8.0g 72 union

union73 byte %8.0g 73 union

union77 byte %8.0g 77 union

union78 byte %8.0g 78 union

union80 byte %8.0g 80 union

union82 byte %8.0g 82 union

union83 byte %8.0g 83 union

union85 byte %8.0g 85 union

union87 byte %8.0g 87 union

union88 byte %8.0g 88 union

black byte %8.0g Race black

Sorted by: idcode
Note: Dataset has changed since last saved.

Now execute retainlbl a second time, specifying the variable name for which you want to restore the variable label.
This time, specify the option restore. Like reshape, retainlbl begins the label of each newly created variable
with a value of the j variable (in this case year).
However, instead of appending the variable name to the value of year, retainlbl appends the original variable label,
which in this case is "1 if union".

. retainlbl union, restore

. describe

Contains data
Observations: 4,434 NLS Women 14-24 in 1968
Variables: 14
(_dta has notes)

Variable Storage Display Value
name type format label Variable label

idcode int %8.0g NLS ID

union70 byte %8.0g 70 1 if union

union71 byte %8.0g 71 1 if union

union72 byte %8.0g 72 1 if union

union73 byte %8.0g 73 1 if union

union77 byte %8.0g 77 1 if union

union78 byte %8.0g 78 1 if union

union80 byte %8.0g 80 1 if union

union82 byte %8.0g 82 1 if union

union83 byte %8.0g 83 1 if union

union85 byte %8.0g 85 1 if union

union87 byte %8.0g 87 1 if union

union88 byte %8.0g 88 1 if union

black byte %8.0g Race black

Sorted by: idcode
Note: Dataset has changed since last saved.

Known issues

retainlbl's options do not work properly in all circumstances.
Using retainlbl sometimes fails when used with Stata's reshape,
especially when reshaping from -wide- format to -long- format.
See the do file that accompanies this package for more detailed examples in conjunction with reshape.
Experiment to see whether a specific option combination works in your specific situation.

Author

Mead Over Center for Global Development. Contact him at:
Email: MOver@CGDev.Org if you observe any problems.