*! version 1.2.0 12jun2017

Title

renamefrom -- Names and labels variables using values stored in an external crosswalk.

Table of contents

Syntax
Description
Options
Examples
Author
Remarks

Syntax

renamefrom
using filename
, filetype(string) raw(string) clean(string)
[options]

Main

raw(string) column in external crosswalk that contains existing variable names in memory

clean(string) column in external crosswalk that contains clean variable names

label(string) column in external crosswalk that contains clean variable labels

Crosswalk

filetype(excel|delimited|stata) file type of external crosswalk

sheet(string) sheet name if the external crosswalk is an Excel workbook

delimiters("chars") chars used as delimiters in the external crosswalk; by default, "\t" or ","

Missing Values

keepx keeps variables in memory if no match in the external crosswalk is found

dropx drops variables in memory if no match in the external crosswalk is found

keeplabel keeps variable labels in memory if no label is specified in the external crosswalk

namelabel labels variables with variable names if no label is specified in the external crosswalk

Other

if(exp) restricts renaming to a subset of values in the external crosswalk

caseignore ignores capitalization when matching variables with raw names

Description

renamefrom names and labels the variables in memory using values stored in an external crosswalk. Storing the mapping from raw names to clean names in a crosswalk helps users align names across data sets and spot discrepancies
between files.

Options

Main

raw(string) specifies the crosswalk column that contains the names of variables in memory.
If there are variables in memory that are not included in the external crosswalk, the user must
specify either the dropx or keepx option.

clean(string) specifies the crosswalk column that contains clean variable names.

label(string) specifies the crosswalk column that contains clean variable labels. If no label
is specified for a given variable, the default behavior is to leave the label blank.
The options namelabel and keeplabel provide alternatives.

Crosswalk

filetype(excel|delimited|stata) specifies the file type
of the crosswalk.
The excel option is for Excel workbooks with file extensions .xls
and .xlsx. The delimited option supports .csv and other
character-delimited text files. The stata option is for Stata .dta files.

sheet(string) specifies a sheet name for the crosswalk in an Excel workbook.
This option can only be used with filetype(excel). In keeping with the syntax for import excel, the
program defaults to using the workbook's first sheet if no sheet is specified.

delimiters("chars") specifies the delimiter that separates columns in the crosswalk.
This option can only be used with filetype(delimited). For .csv crosswalks
the syntax is delimiters(","). For tab-delimited crosswalks the syntax is delimiters("\t"). In keeping with the syntax for import delimited,
if no delimiter is specified, Stata will check if the file is delimited by tabs or commas by default.

Missing Values

The keepx and dropx options determine how the program handles variables
in memory that are not found in the raw column of the crosswalk.

keeplabel preserves the raw variable label if a clean label is not provided.
namelabel applies the raw variable name as the label if a clean label is not provided.
If both options are specified, namelabel will only label a variable with
its raw name if no clean label was specified and the variable did not have a
raw label.

Other

if(exp) restricts renaming to as subset of values in the external crosswalk.

caseignore ignores capitalization when matching variables in memory with raw variable
names in the crosswalk.

Examples

. renamefrom using variables.xlsx, filetype(excel) raw(old_name) clean(new_name) label(label)

. renamefrom using variables.csv, filetype(delimited) delimiters(",") raw(old_name) clean(new_name) label(label)

Author

Sally Hudson

E-mail: sally.hudson@virginia.edu

GitHub: https://github.com/slhudson

Remarks

This program was developed through work at the School Effectiveness and
Inequality Initative at MIT. Thanks are due to the many SEII research
assistants who used and refined it over the years, especially Tyler Hoppenfeld,
Sookyo Jeong, and Alicia Weng. If you encounter any bugs or have suggestions
for additional features, please feel free to submit a pull request on GitHub. The GitHub repository also contains more examples of this program in use.