ethnicolr2: Predict Race and Ethnicity From Names¶
Project status¶
ethnicolr2 is in maintenance mode. Existing users can keep using it, and we
will continue to fix serious bugs, security issues, and compatibility breaks.
New projects should use ethnicolr, the
canonical package. New models and features will be developed there.
ethnicolr2 preserves three PyTorch LSTM models trained on US Census and
Florida voter registration data. The models use:
Last name only (census model or Florida model)
First and last name combined (Florida full name model)
Quick start for existing projects¶
uv add ethnicolr2
or
pip install ethnicolr2
import pandas as pd
from ethnicolr2 import pred_fl_last_name
# Predict from last names
df = pd.DataFrame({"last": ["Smith", "Zhang", "Rodriguez"]})
result = pred_fl_last_name(df, lname_col="last")
print(result)
Key Features¶
Trained on US Census data and Florida voter registration with proven accuracy for demographic prediction.
Built with PyTorch 2.x for efficient neural network inference with LSTM models.
Both Python API and command-line interface for seamless integration into your workflow.
Documentation Sections¶
Installation, quickstart guide, and core concepts to get you up and running quickly.
Interactive Jupyter notebooks demonstrating real-world applications and best practices.
Detailed tutorials and best practices for different use cases.
Complete API documentation with all classes, functions, and parameters.
Contributing guidelines, testing, and development setup information.
Supported Prediction Categories¶
The models predict one of five race/ethnicity categories:
nh_white: Non-Hispanic Whitenh_black: Non-Hispanic Blackhispanic: Hispanicasian: Asianother: Other
Available Models¶
Model |
Input |
Training Data |
Use Case |
|---|---|---|---|
Census Last Name |
Last name only |
US Census 2000/2010 |
General population predictions |
Florida Last Name |
Last name only |
FL voter registration |
State-specific predictions |
Florida Full Name |
First + Last name |
FL voter registration |
Highest accuracy predictions |