Skip to content

Pandas Categorical Codes Quick Fix

DodaTech Updated 2026-06-26 1 min read

You will learn how to access and use integer codes from pandas categorical data for machine learning pipelines and efficient storage.

The Problem

Manually mapping categories to integers using dictionaries or LabelEncoder is error-prone and duplicates functionality already built into pandas categoricals. The .cat.codes accessor provides a zero-effort integer encoding.

The Wrong Way

import pandas as pd
s = pd.Series(["dog", "cat", "bird", "cat", "dog"])
mapping = {"dog": 0, "cat": 1, "bird": 2}
codes = s.map(mapping)
print(codes)

Output:

0    0
1    1
2    2
3    1
4    0
dtype: int64

Manual mapping breaks when new categories appear in production data.

The Right Way

s = pd.Series(["dog", "cat", "bird", "cat", "dog"], dtype="category")
codes = s.cat.codes
categories = s.cat.categories
print("Codes:", codes.tolist())
print("Categories:", categories.tolist())

Output:

Codes: [1, 0, 2, 0, 1]
Categories: ['bird', 'cat', 'dog']

The codes are zero-based indices into .cat.categories.

Step-by-Step Fix

1. Convert to categorical

s = pd.Series(["dog", "cat", "bird"]).astype("category")

2. Access the integer codes

codes = s.cat.codes

3. Reconstruct from codes if needed

restored = pd.Categorical.from_codes(codes, categories=s.cat.categories)

Prevention Tips

  • Use .cat.codes instead of manual dict mapping for categorical columns
  • Store the original categories list alongside encoded data for decoding
  • Use .cat.categories to inspect the mapping after encoding
  • Combine with CategoricalDtype for ordered encoding

Common Mistakes

  1. Assuming codes are assigned in data appearance order -- codes follow category order, not insertion order
  2. Forgetting to store .cat.categories before serialization -- codes become meaningless without categories
  3. Applying .cat.codes on non-categorical columns -- raises AttributeError; use .astype("category") first

These mistakes appear frequently in real-world pandas code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

FAQ

### What is the difference between `.cat.codes` and `LabelEncoder`?

Both produce integer encodings, but .cat.codes is integrated into pandas and preserves the categorical dtype, while LabelEncoder is a separate sklearn class.

Can I decode codes back to original values?

Yes. Create a new Categorical.from_codes(codes, categories=original_categories).

Do codes respect ordering?

Yes. If the categorical is ordered, codes reflect the defined order in .cat.categories.

Built by the developers of Doda Browser, DodaZIP, and Durga Antivirus Pro. DodaTech tools integrate seamlessly with pandas for enhanced productivity and security.

Built by the developers of DodaTech

Doda Browser, DodaZIP & Durga Antivirus Pro