help for naam

Title

naam -- Consistent string encoding, ID hashing, and label
management across multiple datasets

Syntax

naam encode varlist using filename
[, replace keep]

naam apply using filename
[, varsonly labelsonly]

naam id varlist using filename
[, replace keep strict]

naam export using filename
[, replace]

naam list using filename
[, variable(varname)]

naam decode varlist using filename
[, keep]

naam check [varlist] using filename

naam compare using filename1
, using2(filename2)

For all subcommands except naam id, filename refers to an Excel workbook (.xlsx);
the .xlsx extension is appended automatically if omitted.
naam id saves each variable's mapping as a separate Stata .dta file
(filename_varname.dta), with no row-count limit.

Description

naam ("What's in a naam?") solves a core problem in
large-scale survey and administrative data work: encoding string variables
consistently across multiple datasets or rounds.

Stata's built-in encode assigns numeric codes alphabetically
within each dataset independently. If a later file introduces a new category
-- a new region, industry, or district -- all alphabetically
subsequent codes shift, and any merge or append across files produces wrong
results with no error message.

naam encodes once, saves the exact string-to-numeric mapping for every
variable to a named Excel workbook, and reapplies those mappings instantly to
every subsequent file. The same string always receives the same numeric code.
New categories are detected automatically, assigned the next available code,
and the Excel file is updated. The Excel file also serves as a permanent,
human-readable audit record of every mapping in the project. ID variables
are handled separately by naam id, which saves mappings as native
Stata .dta files with no row-count limit.

naam requires no user-written dependencies. All subcommands read and
write standard .xlsx files using Stata's built-in import excel
and export excel. naam id reads and writes .dta files using
use and save.

Subcommands

naam encode Converts text columns such as "North" and "South"
into numbers, and saves a record of exactly which text got which number
into an Excel file so you can reuse it on the next file.

naam apply When you receive the next file with the same text
columns, this reads the Excel record saved by naam encode and
applies the exact same numbers instead of starting fresh. New categories
are assigned the next available code automatically.

naam id When you have a unique identifier column such as
HH-001-MH that you need to merge datasets on, this converts it to a
number and saves a record so the same ID always gets the same number
across every file. Mappings are saved as native Stata .dta files
(base_varname.dta), one per ID variable, with no row-count limit.
Use naam id on each file; do not use naam apply for ID
variables.

naam export When your dataset already has numbers with labels
attached, this saves those labels into Excel so you can restore them
later if they get stripped.

naam list Opens your Excel mapping file and displays everything
inside it directly in Stata, so you can see at a glance what number each
category was assigned without opening Excel.

naam decode Takes a numeric column and converts it back to the
original text using the saved Excel mapping, useful when you need the
original words back for a report or export. Works even if value labels
have been stripped from the dataset.

naam check Before merging or appending datasets, this compares
the labels in your current dataset against the saved Excel mapping and
flags any mismatches so you catch problems before they corrupt your
analysis. Does not modify the dataset or the Excel file.

naam compare When two people have encoded the same data
independently, this compares their two Excel mapping files and tells you
exactly where they assigned different numbers to the same
category.

Options

naam encode and naam id

replace overwrites the mapping file if it already exists. For
naam encode and naam export this is the .xlsx file; for
naam id this is the per-variable .dta file. Required the first
time a mapping file is created for a given filename.

keep retains the original string variable alongside the new numeric
variable, renamed _str_varname.

naam id only

strict exits with an error if the current dataset contains any ID
value not found in the saved mapping. Use this to enforce that no unexpected
new observations appear in a subsequent file.

naam apply only

varsonly reattaches variable labels only; skips value labels and
encodings.

labelsonly reattaches value labels and encodings only; skips variable
labels.

naam export only

replace overwrites the Excel file if it already exists.

naam list only

variable(varname) prints only the mapping for the named variable
instead of all variables in the file.

naam decode only

keep retains the original numeric variable alongside the new string
variable, renamed _num_varname.

naam compare only

using2(filename) specifies the second Excel mapping file. Required.

Subcommand details

naam encode

Encodes each string variable in varlist to numeric using Stata's
encode and writes the complete string-to-numeric mapping for each
variable as a separate named sheet in the Excel workbook. Variables that are
already numeric are skipped with a note. Run naam encode once on the
first file in a multi-file workflow; use naam apply on every subsequent
file.

naam apply

Reads the index sheet of the specified Excel workbook to determine which
variables are present and what type of mapping applies to each, then processes
each variable as follows:

type = encode If the variable is still a string, converts it to
numeric using the saved mapping. If already numeric, reattaches the saved
value labels. New categories are assigned new codes and the Excel file is
updated.

type = export The variable is already numeric. Reattaches the
saved value labels.

type = id Prints a note only. Does not perform the
string-to-numeric conversion. Call naam id on each new file that
requires the conversion.

naam id

Converts each string ID variable in varlist to a consistent numeric ID.
On the first file, codes 1, 2, 3, ... are assigned in alphabetical
order using egen group(), and the mapping is saved as a
native Stata .dta file (base_varname.dta). On every subsequent
file, the saved mapping is read: known IDs receive their original codes,
and new IDs receive the next available sequential codes. There is no
row-count limit.

naam export

For datasets that are already numeric with value labels attached. Saves all
variable labels and value labels to Excel so they can be reattached with
naam apply. A common trigger is label drop _all, importing from
a .csv file, or receiving a raw dataset without a .dta file. Does not encode
or modify anything in the dataset.

naam list

Reads a naam Excel file and prints its full contents to the Results window:
each variable, its type, and every numeric code with its corresponding string
value. Applies to variables encoded with naam encode or exported with
naam export. ID variable mappings are stored in separate .dta files
and are not displayed by naam list; use use or browse
to inspect them directly. The dataset in memory is not used or modified.

naam decode

Reverses a naam encoding using the saved Excel mapping. Observations whose
numeric value has no match in the mapping are set to missing and a warning
is printed.

naam check

Compares the value labels currently attached in memory against the saved
Excel mapping and prints a code-by-code report: OK, CONFLICT (label
differs), or MISSING (code in Excel but not in memory). Also flags codes
in memory that are not in the Excel file. If no varlist is given, all
variables in the index are checked. Neither the dataset nor the Excel file
is modified.

naam compare

Compares two naam Excel files without requiring any dataset in memory.
Useful when two teams have encoded data independently and need to confirm
consistency before combining files.

Limitations

naam apply does not perform the string-to-numeric
conversion for ID variables. Call naam id on each new file.

naam encode skips variables that are already numeric.

naam export saves only value labels that are already defined
and attached in the dataset.

naam decode sets unmatched observations to missing and prints
a warning.

Excel sheet names are truncated to 31 characters if the variable
name is longer. This applies to naam encode and naam export;
naam id is unaffected as it writes .dta files, not Excel sheets.

Output file structure

Excel files (naam encode, naam export, naam apply):

Sheet index One row per processed variable. Columns:
varname, varlabel, type (encode / export / id),
and for naam export also lblname and vartype.

Sheet <varname> One sheet per variable with a mapping.
Columns: numeric_code and string_value.

These files are fully human-readable in Excel and should be archived
alongside the datasets they describe.

.dta files (naam id): one file per ID variable, named
base_varname.dta. Each contains two variables: string_value
and numeric_code, sorted by code. No row-count limit.

Examples

The following examples use two sample household survey datasets installed
with naam: naam_round1.dta (200 households, 7 districts) and
naam_round2.dta (200 households, 8 districts -- Amravati is new).
Both contain string variables district, occupation, and
religion, and an alphanumeric household ID hhid in the
format HH-MH-NNNNN. Install them with:

. ssc install naam, all

Example 1 -- naam encode and naam apply

Setup

. use naam_round1.dta, clear

Encode Round 1 and save the mapping

. naam encode district occupation religion using naam_maps.xlsx, replace

. naam id hhid using naam_ids, replace keep

* produces naam_ids_hhid.dta

. save naam_enc1.dta, replace

Apply same mapping to Round 2; Amravati detected and auto-assigned

. use naam_round2.dta, clear

. naam apply using naam_maps.xlsx

. naam id hhid using naam_ids, keep

* reads naam_ids_hhid.dta, assigns same codes + any new ones

Append: every district code is now consistent across both rounds

. append using naam_enc1.dta

. tab district

Inspect the full mapping from inside Stata

. naam list using naam_maps.xlsx

Example 2 -- naam export and naam apply

Setup

. sysuse auto, clear

Save value labels before they are lost

. naam export using naam_labels.xlsx, replace

Simulate receiving the data with no labels attached

. label drop _all

. tab foreign

Restore with a single command

. naam apply using naam_labels.xlsx

. tab foreign

Other subcommands

naam decode -- convert numeric variables back to their original strings

. naam decode district occupation using naam_maps.xlsx

naam check -- verify labels match the saved mapping before a merge

. naam check district occupation religion using naam_maps.xlsx

naam compare -- compare two mapping files from two teams

. naam compare using naam_teamA.xlsx, using2(naam_teamB.xlsx)

Stored results

naam does not store results in r() or e().
Output is written to the Excel file or .dta file specified in using.

Requirements

Stata 14 or higher. No user-written packages are required.
naam relies only on import excel, export excel,
use, save, encode, egen,
label, and levelsof.

Citation

naam is inspired by codebookout. If you use naam,
please also cite the original package:

Das, Kishor K. (2014). "CODEBOOKOUT: Stata module to save codebook
in MS excel format." Statistical Software Components S457811,
Boston College Department of Economics.

https://ideas.repec.org/c/boc/bocode/s457811.html

Author

Vijayshree Jayaraman

Email: jvijayshree26@gmail.com

GitHub: https://github.com/vijayshree-jayaraman

Also see

Manual: [D] encode, [D] label, [D] merge,
[D] append, [D] egen

encode,
label,
egen,
levelsof,
merge,
append,
import excel,
export excel