5-Minute Quickstart

This quickstart guide will get you up and running with ethnicolr2 in just a few minutes.

Basic Example

import pandas as pd
from ethnicolr2 import pred_fl_last_name

# Create sample data
names_df = pd.DataFrame({
    'last_name': ['Smith', 'Zhang', 'Rodriguez', 'Johnson', 'Kim']
})

# Predict race/ethnicity from last names
results = pred_fl_last_name(names_df, lname_col='last_name')
print(results)

Output:

  last_name      race     asian   hispanic   nh_black   nh_white
0     Smith  nh_white  0.001234   0.012345   0.234567   0.751854
1     Zhang     asian  0.987654   0.001234   0.002345   0.008767
2 Rodriguez  hispanic  0.001234   0.934567   0.012345   0.051854
3   Johnson  nh_white  0.001234   0.023456   0.123456   0.851854
4       Kim     asian  0.876543   0.012345   0.023456   0.087656

Different Models

Census Data Model

For general population predictions based on US Census data:

from ethnicolr2 import census_ln

# Get census statistics for names
census_results = census_ln(names_df, 'last_name')
print(census_results.columns)
# ['last_name', 'pctwhite', 'pctblack', 'pctapi', 'pctaian', 'pct2prace', 'pcthispanic']

Full Name Model (Highest Accuracy)

When you have both first and last names:

from ethnicolr2 import pred_fl_full_name

# Create data with first and last names
full_names_df = pd.DataFrame({
    'first_name': ['John', 'Wei', 'Maria', 'Robert', 'Priya'],
    'last_name': ['Smith', 'Zhang', 'Rodriguez', 'Johnson', 'Patel']
})

# Predict using both names (most accurate)
full_results = pred_fl_full_name(
    full_names_df,
    lname_col='last_name',
    fname_col='first_name'
)
print(full_results)

Command Line Usage

ethnicolr2 also provides command-line tools:

# Census lookup
census_ln input.csv -l last_name -o output.csv

# Florida last name prediction
pred_fl_last_name input.csv -l last_name -o output.csv

# Florida full name prediction
pred_fl_full_name input.csv -l last_name -f first_name -o output.csv

Understanding the Output

Each model returns probability scores for different racial/ethnic categories:

  • race: The predicted category (highest probability)

  • asian: Probability of Asian ethnicity

  • hispanic: Probability of Hispanic ethnicity

  • nh_black: Probability of Non-Hispanic Black

  • nh_white: Probability of Non-Hispanic White

  • other: Probability of Other (in some models)

Input Data Requirements

Pandas DataFrame

# Your data must be a pandas DataFrame
df = pd.DataFrame({'names': ['Smith', 'Zhang']})

# Specify which column contains the names
result = pred_fl_last_name(df, lname_col='names')

CSV Files

first_name,last_name,id
John,Smith,1
Wei,Zhang,2
Maria,Rodriguez,3

import pandas as pd

# Read CSV file
df = pd.read_csv('names.csv')
result = pred_fl_full_name(df, lname_col='last_name', fname_col='first_name')

Handling Missing Data

# DataFrame with missing values
df = pd.DataFrame({
    'last_name': ['Smith', None, 'Zhang', ''],
    'first_name': ['John', 'Maria', 'Wei', None]
})

# Missing values are handled automatically
# Empty strings and None values will receive default predictions
result = pred_fl_last_name(df, lname_col='last_name')

Performance Tips

# For large datasets, process in chunks
import pandas as pd

def process_large_dataset(df, chunk_size=1000):
    results = []
    for i in range(0, len(df), chunk_size):
        chunk = df[i:i+chunk_size]
        chunk_result = pred_fl_last_name(chunk, lname_col='last_name')
        results.append(chunk_result)
    return pd.concat(results, ignore_index=True)

# Process 100K records efficiently
large_df = pd.read_csv('large_dataset.csv')
results = process_large_dataset(large_df)

What’s Next?