Merging and Combining

Map Lookup Column

Translate each code in a list to its label by looping over a dict. With pandas, Series.map(dict) applies the same elementwise lookup to an entire column in one call, returning a new Series of labels.

By hand

Loop over codes, look up each code in mapping, and append the label to labels.

naive.py
Replay: real traced execution (multi-file project)
codes = ['A', 'B', 'A', 'C', 'B']
mapping = {'A': 'alpha', 'B': 'beta', 'C': 'gamma'}
labels = []
for code in codes:
    labels.append(mapping[code])
print('RESULT:', labels)

  1. codes ← ['A', 'B', 'A', 'C', 'B']

    1codes = ['A', 'B', 'A', 'C', 'B']2mapping = {'A': 'alpha', 'B': 'beta', 'C': 'gamma'}
    values this step['A', 'B', 'A', 'C', 'B']codes

  2. mapping ← {'A': 'alpha', 'B': 'beta', 'C': 'gamma'}

    1codes = ['A', 'B', 'A', 'C', 'B']2mapping = {'A': 'alpha', 'B': 'beta', 'C': 'gamma'}3labels = []
    values this step{'A': 'alpha', 'B': 'beta', 'C': 'gamma'}mapping

  3. labels ← []

    2mapping = {'A': 'alpha', 'B': 'beta', 'C': 'gamma'}3labels = []4for code in codes:
    values this step[]labels

  4. code ← 'A'

    3labels = []4for code in codes:5    labels.append(mapping[code])
    values this step'A'code

  5. labels ← ['alpha']

    4for code in codes:5    labels.append(mapping[code])6print('RESULT:', labels)
    values this step[] → ['alpha']labels

  6. code ← 'B'

    3labels = []4for code in codes:5    labels.append(mapping[code])
    values this step'A' → 'B'code

  7. labels ← ['alpha', 'beta']

    4for code in codes:5    labels.append(mapping[code])6print('RESULT:', labels)
    values this step['alpha'] → ['alpha', 'beta']labels

  8. code ← 'A'

    3labels = []4for code in codes:5    labels.append(mapping[code])
    values this step'B' → 'A'code

  9. labels ← ['alpha', 'beta', 'alpha']

    4for code in codes:5    labels.append(mapping[code])6print('RESULT:', labels)
    values this step['alpha', 'beta'] → ['alpha', 'beta', 'alpha']labels

  10. code ← 'C'

    3labels = []4for code in codes:5    labels.append(mapping[code])
    values this step'A' → 'C'code

  11. labels ← ['alpha', 'beta', 'alpha', 'gamma']

    4for code in codes:5    labels.append(mapping[code])6print('RESULT:', labels)
    values this step['alpha', 'beta', 'alpha'] → ['alpha', 'beta', 'alpha', 'gamma']labels

  12. code ← 'B'

    3labels = []4for code in codes:5    labels.append(mapping[code])
    values this step'C' → 'B'code

  13. labels ← ['alpha', 'beta', 'alpha', 'gamma', 'beta']

    4for code in codes:5    labels.append(mapping[code])6print('RESULT:', labels)
    values this step['alpha', 'beta', 'alpha', 'gamma'] → ['alpha', 'beta', 'alpha', 'gamma', 'beta']labels

  14. for code in codes:

    3labels = []4for code in codes:5    labels.append(mapping[code])

  15. stdout ← RESULT: ['alpha', 'beta', 'alpha', 'gamma', 'beta']

    5    labels.append(mapping[code])6print('RESULT:', labels)
    values this stepRESULT: ['alpha', 'beta', 'alpha', 'gamma', 'beta']stdout

With pandas

df['code'].map(mapping) applies the dict lookup to every element of the column and returns a Series of translated labels. The snapshot shows the index, values, and dtype of the result.

library.py 
import pandas as pd
from dalib.display import set_display
set_display()

codes = ['A', 'B', 'A', 'C', 'B']
mapping = {'A': 'alpha', 'B': 'beta', 'C': 'gamma'}
df = pd.DataFrame({'code': codes})
labels = df['code'].map(mapping)
print('index:', labels.index.tolist())
print('values:', labels.tolist())
print('dtype:', labels.dtype)
print('RESULT:', labels.tolist())

index: [0, 1, 2, 3, 4]
values: ['alpha', 'beta', 'alpha', 'gamma', 'beta']
dtype: object
RESULT: ['alpha', 'beta', 'alpha', 'gamma', 'beta']

Implementation notes

  • .map(dict) returns NaN for any value not found in the dict. If every code is guaranteed to be in the mapping, this matches the naive loop exactly. Use .map(dict).fillna('unknown') to handle missing keys with a default.
  • .map also accepts a function: df['code'].map(str.lower) applies str.lower elementwise. This is an elementwise API — each Python function call runs per element, not as a vectorized kernel like NumPy arithmetic.
  • The result dtype is object (pandas string) here because the values are strings. For numeric mappings the dtype would follow the mapped values.
  • Contrast with pd.merge: .map is for simple key→value enrichment from a dict; merge is for joining two DataFrames that each have multiple columns. For a large label table, merge is more appropriate.
  • Cross-reference: lookup-enrich (python-data-basics) for the pure-Python dict-lookup version.