*! version 1.2 30 August 2021
help for charrenversion 1.2 (30 August 2021)

Title

charren -- rename variables via characteristics saved in the dataset

Table of contents

Syntax
Description
Options
Remarks
Examples
Author
Saved results
Also see

Syntax

charren namelist, to(charname) [options]

Other options
searchspace(charlist) search for variables to rename in all saved characteristics of charlist

verbose give verbose output

Description

charren renames all variables specified in namelist to pre-defined alternative names. These names have to be defined as characteristics and saved to the Stata dataset.

In many datasets originating from surveys, most variables are renamed from its original name to another before dissemination, i.e. in order to fit a general variable naming convention.

However, dataset users being familiar with the original variable names might want to work with these names. charren provides a mechanism
to easily handle this problem. It is based on Stata's ability to save any extra information to a variable using so-called characteristics.
For instance, when renaming variables to its final name, it is possible to save a variable's original name as characteristic NEPS_alias and attach it to the variable.
A second characteristic NEPS_varname may hold the new variable name. The charren command enables a data user to easily switch between both alternative names, parsing these characteristics.

In the NEPS datasets, saved alternative names are NEPS_alias and NEPS_varname.
The first is reflecting the variable name as defined in the survey instrument, the latter the variable name shipped in the Scientific Use Files.

Options

Other options

searchspace(charlist) specifies all characteristics to be parsed when searching for variables to rename.
If one or more variables designated for renaming is not found in the dataset, it is checked if the name is defined as characteristic out of charlist attached to any variable in the dataset.

This enables charren to also accept alternative names in namelist, not only currently active names.

verbose drops verbose output during the process. Eventually needed for debugging.

Remarks

As mentioned before, the optional parameter searchspace(charlist) enables charren to accept alternative variable names as input.
This tool is reportedly not only used with NEPS Scientific Use Files,
but also with datasets from the SCIP survey. Thus, the option does not only default to the array NEPS_instname NEPS_sufname
(as used in the NEPS SUFs), but to the array oldname tempname NEPS_instname NEPS_sufname. This reflects the union of both search spaces.
In case the characteristic _dta[EMD_prefix] is set, as should be for all datasets using the more modern EMD approach for extended
metadata (as are NEPS SUFs since 2021), the default array is <EMD_prefix>varname <EMD_prefix>alias.

If you want to use a similar mechanism in your Stata datasets, feel free to contact the author for more information on how to do so.

This command is part of the NEPStools bundle, written to assist with the NEPS dataset files.

The source code of the program is licensed under the GNU General Public License version 3 or later. The corresponding license text can be found on the internet at http://www.gnu.org/licenses/ or in gnugpl.

Examples

Rename variables t73114c and t73114d to their pre-defined NEPS_instname:

. charren t73114c t73114d, to(NEPS_instname)

Author

Daniel Bela (daniel.bela@lifbi.de), Leibniz Institute for Educational Trajectories e.V. (LIfBi), Germany.

Saved results

charren saves the following in r():

Scalars

r(renamed) number of variables renamed

Locals

r(from#) source variable name of renamed variable #

r(to#) target variable name of renamed variable #

(With # denoting a running number between 0 and the scalar r(renamed))

Also see

NEPStools, char, rename, rename group (Stata 12 or newer only)