Name Ethnicity Classification

This repository is part of the name-to-ethnicity research project. If you use this classifier for your scientific work, please cite our paper.

What is name-ethnicity classification?

Name-ethnicity classification is the process of using a person's name to predict their ethnicity. It involves analyzing the linguistic features of the name to determine the likely ethnicity. This can help researchers detect potential biases and discrimination in various contexts, such as education, employment and healthcare.

This project contains a Python package and CLI tool called n2e.

⬇️ Installation:

This project uses the uv Python package manager.

Install the package:

For installing the n2e CLI interface, run:

uv tool install n2e

For the n2e Python package, run:

uv add n2e

If you don't use uv, run:

pip install n2e

For local development:

If you want to set up this repository for local development, clone the repository instead:

git clone https://github.com/name-ethnicity-classifier/name-ethnicity-classifier
cd name-ethnicity-classifier/

Dependencies:

The project was tested with Python ≥ 3.10. The following packages are installed and used as dependencies: NumPy, Pandas and PyTorch.

👨‍💻 Usage:

Read this first:

Before you start classifying, check out the different model configurations in the "Models" table below. Models are hosted as GitHub release assets and downloaded automatically the first time you use one, then cached in ~/.cache/n2e/.

There you will find different models which each classify a unique set of ethnicities and their average accuracy.

When using the CLI or the Python package, you can specify which model you want to use.

None of the models is suitable for your problem?

On the website www.name-to-ethnicity.com you can request custom models trained on selected ethnicities (for free!). Alternatively, you can use the model-training repository to train models locally.

n2e CLI:

The following flags are available:

To classify a list of names put them into a .csv file, with one column named "names". For example:

Then run the classification, for example like this:

n2e -i ./examples/names.csv -o ./examples/predicted_ethnicities.csv -m 21_nationalities_and_else -d gpu -b 64

After running the command, the output .csv will look like this:

If the --distribution flag was set the output .csv will look like this:

Python API:

Import predict_ethnicities to use n2e directly as a Python module:

from n2e import predict_ethnicities

predict_ethnicities(
    names,                              # list[str]
    batch_size=128,                     # names processed in parallel
    model="21_nationalities_and_else",  # any model from the table below
    get_distribution=False,             # return confidences for every ethnicity
)

Returns a list of (ethnicity, confidence) tuples, one per name:

>>> predict_ethnicities(["Giorgos Papadopoulos"])
[('greek', 99.045)]

>>> predict_ethnicities(["Giorgos Papadopoulos", "Max Mustermann"])
[('greek', 99.045), ('german', 60.34)]

With get_distribution=True you get a full distribution per name:

>>> predict_ethnicities(["Giorgos Papadopoulos"], get_distribution=True)
[{'british': 0.073, 'else': 0.046, 'indian': 0.008, ...}]

🌍 Models: