This repository is part of the name-to-ethnicity research project. If you use this classifier for your scientific work, please cite our paper.
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, housing, and healthcare.
git clone https://github.com/name-ethnicity-classifier/name-ethnicity-classifier
cd name-ethnicity-classifier/
Python>=3.7, PyTorch, NumPy, Pandas
Before you start classifying, check out the different model configurations inside the folder model_configurations/ or in the table below.
There you will find different models which each classify a unique set of nationalities.
The README.md in each model folder will inform you about which ethnicities it can classify, its performance and more information you should know about it.
When using this console interface, you can specify which model you want to use.
On our website, www.name-to-ethnicity.com, you can request custom models trained on selected ethnicities (for free!).
python predict_ethnicity.py -i ./examples/names.csv -o ./examples/predicted_ethnicities.csv -m 21_nationalities_and_else -d gpu -b 64
| flag | description | option |
|---|---|---|
-i, --input |
path to .csv containing (first and last) names; must contain one column called "names" (file-name freely selectable) | optional, alternative: -n |
-o, --output |
path to .csv in which the names along with the predictions will be stored (file will be created if it doesn't exist; file-name freely selectable) | required after -i |
-m, --model |
name of model configuration which can be chosen from "model_configurations/" or from the table below | optional, default: 21_nationalities_and_else |
-d, --device |
device on which the model will run, must be either "gpu" or "cpu" | optional, default: gpu if CUDA detected |
-b, --batchsize |
specifies how many names will be processed in parallel (if it crashes choose a batch-size smaller than the amount of names in your .csv file) | optional, default: amount of names in input-file |
The input .csv file has to have one column named "names" (upper-/ lower case doesn't matter):
1 names
2 John Doe
3 Max Mustermann
After running the command, the output .csv will look like this:
1 names,ethnicities
2 John Doe,american
3 Max Mustermann,german
python3 predict_ethnicitiy.py -n "Gonzalo Rodriguez"
>> name: Gonzalo Rodriguez - predicted ethnicity: spanish
| flag | description | option |
|---|---|---|
-n, --name |
first and last name (upper-/ lower case doesn't matter) | optional, alternative: -i |
-m, --model |
name of model configuration which can be chosen from "model_configurations/" or from the table below | optional, default: 21_nationalities_and_else |
| name | nationalities/groups | accuracy |
|---|---|---|
28_nationalities_english_once |
click to see nationalitiesbritish norwegian indian hungarian spanish german zimbabwean portugese polish bulgarian bangladeshi turkish belgian pakistani italian romanian lithuanian french chinese swedish nigerian greek south african japanese dutch danish russian filipino |
78.54% |
21_nationalities_and_else |
click to see nationalitiesbritish else indian hungarian spanish german zimbabwean polish bulgarian turkish pakistani italian romanian french chinese swedish nigerian greek japanese dutch ukrainian danish russian |
81.08% |
8_groups |
click to see nationalitiesafrican celtic eastAsian european hispanic muslim nordic southAsian |
83.55% |
chinese_and_else |
click to see nationalitieschinese else |
98.55% |
20_most_occuring_nationalities |
click to see nationalitiesbritish norwegian indian irish spanish american german polish bulgarian turkish pakistani italian romanian french australian chinese swedish nigerian dutch filipin |
75.36% |
german_austrian_and_else |
click to see nationalitiesgerman/austrian combined else |
88.1% |
indian_and_else |
click to see nationalitiesindian else |
94.63% |