{"id":46835730,"url":"https://github.com/name-ethnicity-classifier/name-ethnicity-classifier","last_synced_at":"2026-03-10T11:18:48.039Z","repository":{"id":65541584,"uuid":"427643666","full_name":"name-ethnicity-classifier/name-ethnicity-classifier","owner":"name-ethnicity-classifier","description":"This repository contains a console-interface name-ethnicity classifier","archived":false,"fork":false,"pushed_at":"2024-05-30T12:27:37.000Z","size":24071,"stargazers_count":13,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-05-31T06:51:08.481Z","etag":null,"topics":["bias-detection","conv-lstm","ethnicity-classifier","machine-learning","nationality-predicter","social-sciences"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/name-ethnicity-classifier.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-11-13T11:16:06.000Z","updated_at":"2024-05-30T12:27:41.000Z","dependencies_parsed_at":"2024-05-29T19:42:06.224Z","dependency_job_id":null,"html_url":"https://github.com/name-ethnicity-classifier/name-ethnicity-classifier","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/name-ethnicity-classifier/name-ethnicity-classifier","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/name-ethnicity-classifier%2Fname-ethnicity-classifier","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/name-ethnicity-classifier%2Fname-ethnicity-classifier/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/name-ethnicity-classifier%2Fname-ethnicity-classifier/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/name-ethnicity-classifier%2Fname-ethnicity-classifier/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/name-ethnicity-classifier","download_url":"https://codeload.github.com/name-ethnicity-classifier/name-ethnicity-classifier/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/name-ethnicity-classifier%2Fname-ethnicity-classifier/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30331889,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-10T05:25:20.737Z","status":"ssl_error","status_checked_at":"2026-03-10T05:25:17.430Z","response_time":106,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bias-detection","conv-lstm","ethnicity-classifier","machine-learning","nationality-predicter","social-sciences"],"created_at":"2026-03-10T11:18:47.764Z","updated_at":"2026-03-10T11:18:48.007Z","avatar_url":"https://github.com/name-ethnicity-classifier.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Name Ethnicity Classification\n\nThis repository is part of the [name-to-ethnicity](https://www.name-to-ethnicity.com) research project. If you use this classifier for your scientific work, please cite our [paper](https://link.springer.com/article/10.1007/s00146-022-01619-4#citeas).\n\n\n## What is name-ethnicity classification?\nName-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.\n\n\n## :arrow_down: Installation:\n### Get repository:\n```\ngit clone https://github.com/name-ethnicity-classifier/name-ethnicity-classifier\ncd name-ethnicity-classifier/\n```\n### Dependencies:\nThe script was tested with **Python ≥ 3.10**.\n\nThe following packages are needed: ``NumPy``, ``Pandas`` and ``PyTorch``.\n\nYou can install them individually with ``pip`` or ``conda`` or use the provided [`requirements.txt`](requirements.txt):\n\n```bash\npip install -r requirements.txt\n```\n\n---\n\n## 👨‍💻 Usage:\n\n### Read this first:\n\nBefore you start classifying, check out the different model configurations inside the folder [model_configurations/](./model_configurations/) or in the table below.\n\nThere you will find different models which each classify a unique set of nationalities.\n\nThe 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.\n\nWhen using this console interface, you can specify which model you want to use.\n\n##### None of the models is suitable for your problem?\nOn our website, www.name-to-ethnicity.com, you can request custom models trained on selected ethnicities (for free!).\n\n### Command line flags:\n| flag | description | example |\n| :------------- |:------------- | ----- |\n| ```-i, --input``` | Sets the path to an input .csv file containing first and last names; must contain one column called \"names\". | ``-i \"./examples/name.csv\"`` (required unless ``-n`` is used) | \n| ```-o, --output``` | Path to an output .csv in which the names along with the predictions will be stored (file will be created if it doesn't exist). | ``-o \"./examples/predictions.csv\"`` (optional, default: ``{input file name}_output.csv``) |\n| ```-m, --model``` | Name of model configuration which can be chosen from \"model_configurations/\" or from the table below. | ``-m indian_and_else`` (optional, default: ``21_nationalities_and_else``) |\n| ```-d, --device``` | Device on which the model will run, must be either \"gpu\" or \"cpu\". | ``-m \"gpu\"`` (optional, default: ``gpu``) |\n| ```-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). | ``-b 128`` (optional, default: amount of names in input-file) |\n| ```--distribution``` | If set, the output with contain the entire output distribution, ie. providing the confidence for all possible ethnicities. | No parameter |\n| ```-n, --name``` | Alternative to ``-i``, expects just a single name which is then predicted | ``-n \"cixin liu\"`` (required unless ``-i`` is used) | \n\n---\n\n### Option 1: Classifying names in a given .csv file :\n#### Example command:\n```\npython predict_ethnicity.py -i ./examples/names.csv -o ./examples/predicted_ethnicities.csv -m 21_nationalities_and_else -d gpu -b 64\n```\n#### Example files:\nThe input .csv file has to have one column named \"names\" (upper-/ lower case doesn't matter):\n| names           |\n|-----------------|\n| John Doe        |\n| Max Mustermann  |\n\nAfter running the command, the output .csv will look like this:\n| names           | predictions | confidences |\n|-----------------|-------------|-------------|\n| John Doe        | american    | 0.73        |\n| Max Mustermann  | german      | 0.92        |\n\nIf the ``--distribution`` flag was set the output .csv will look like this:\n| names           | predictions | american | german |\n|-----------------|-------------|----------|--------|\n| John Doe        | american    | 0.73     | 0.27   |\n| Max Mustermann  | german      | 0.08     | 0.92   |\n\n---\n\n### Option 2: Predicting a single name:\n\n#### Example command:\n```\npython3 predict_ethnicity.py -n \"Gonzalo Rodriguez\"\n\n\u003e\u003e name: Gonzalo Rodriguez - predicted ethnicity: spanish\n```\n\n---\n\n## :earth_africa: Models:\n\n| name | nationalities/groups | accuracy |\n| ------------- |:------------- | :-----:|\n| ```28_nationalities_english_once``` | \u003cdetails\u003e\u003csummary\u003eclick to see nationalities\u003c/summary\u003e``british`` ``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``\u003c/details\u003e | 78.54% |\n| ```21_nationalities_and_else``` |\u003cdetails\u003e\u003csummary\u003eclick to see nationalities\u003c/summary\u003e``british`` ``else`` ``indian`` ``hungarian`` ``spanish`` ``german`` ``zimbabwean`` ``polish`` ``bulgarian`` ``turkish`` ``pakistani`` ``italian`` ``romanian`` ``french`` ``chinese`` ``swedish`` ``nigerian`` ``greek`` ``japanese`` ``dutch`` ``ukrainian`` ``danish`` ``russian``\u003c/details\u003e | 81.08% |\n| ```8_groups``` | \u003cdetails\u003e\u003csummary\u003eclick to see nationalities\u003c/summary\u003e``african`` ``celtic`` ``eastAsian`` ``european`` ``hispanic`` ``muslim`` ``nordic`` ``southAsian``\u003c/details\u003e | 83.55% |\n| ```chinese_and_else``` | \u003cdetails\u003e\u003csummary\u003eclick to see nationalities\u003c/summary\u003e``chinese`` ``else``\u003c/details\u003e | 98.55% |\n| ```20_most_occuring_nationalities``` | \u003cdetails\u003e\u003csummary\u003eclick to see nationalities\u003c/summary\u003e``british`` ``norwegian`` ``indian`` ``irish`` ``spanish`` ``american`` ``german`` ``polish`` ``bulgarian`` ``turkish`` ``pakistani`` ``italian`` ``romanian`` ``french`` ``australian`` ``chinese`` ``swedish`` ``nigerian`` ``dutch`` ``filipin``\u003c/details\u003e | 75.36% |\n| ```german_austrian_and_else``` | \u003cdetails\u003e\u003csummary\u003eclick to see nationalities\u003c/summary\u003e``german/austrian combined`` ``else``\u003c/details\u003e | 88.1% |\n| ```indian_and_else``` | \u003cdetails\u003e\u003csummary\u003eclick to see nationalities\u003c/summary\u003e``else`` ``indian``\u003c/details\u003e | 94.63% |\n| ```japanese_and_else``` | \u003cdetails\u003e\u003csummary\u003eclick to see nationalities\u003c/summary\u003e``else`` ``japanese``\u003c/details\u003e | 99.33% |\n| ```newzealand_and_else``` | \u003cdetails\u003e\u003csummary\u003eclick to see nationalities\u003c/summary\u003e``else`` ``new zealander``\u003c/details\u003e | 66.71% |\n\n\n\n\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fname-ethnicity-classifier%2Fname-ethnicity-classifier","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fname-ethnicity-classifier%2Fname-ethnicity-classifier","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fname-ethnicity-classifier%2Fname-ethnicity-classifier/lists"}