Ethnicity¶
lamindb provides access to the following public Ethnicity ontologies through bionty:
Here we show how to access and search Ethnicity ontologies to standardize new data.
import bionty as bt
import pandas as pd
PublicOntology objects¶
Let us create a public ontology accessor with .public method, which chooses a default public ontology source from Source.
It’s a PublicOntology object, which you can think about as a public registry:
ethnicitys = bt.Ethnicity.public(organism="human")
ethnicitys
→ connected lamindb: testuser1/test-public-ontologies
PublicOntology
Entity: Ethnicity
Organism: human
Source: hancestro, 3.0
#terms: 342
As for registries, you can export the ontology as a DataFrame:
df = ethnicitys.df()
df.head()
| name | definition | synonyms | parents | |
|---|---|---|---|---|
| ontology_id | ||||
| HANCESTRO:0002 | region | Any Geographic Area Greater Than An Individual... | geographical area | [] |
| HANCESTRO:0003 | country | A Collective Generic Term That Refers Here To ... | None | [] |
| HANCESTRO:0004 | ancestry category | Population Category Defined Using Ancestry Inf... | ancestral group | [] |
| HANCESTRO:0005 | European | Includes Individuals Who Either Self-Report Or... | Caucasian|white | [HANCESTRO:0004] |
| HANCESTRO:0006 | South Asian | Includes Individuals Who Either Self-Report Or... | None | [HANCESTRO:0008] |
Unlike registries, you can also export it as a Pronto object via public.ontology.
Look up terms¶
As for registries, terms can be looked up with auto-complete:
lookup = ethnicitys.lookup()
The . accessor provides normalized terms (lower case, only contains alphanumeric characters and underscores):
lookup.american
Ethnicity(ontology_id='HANCESTRO:0463', name='American', definition=None, synonyms=None, parents=array(['HANCESTRO:0566'], dtype=object))
To look up the exact original strings, convert the lookup object to dict and use the [] accessor:
lookup_dict = lookup.dict()
lookup_dict["American"]
Ethnicity(ontology_id='HANCESTRO:0463', name='American', definition=None, synonyms=None, parents=array(['HANCESTRO:0566'], dtype=object))
By default, the name field is used to generate lookup keys. You can specify another field to look up:
lookup = ethnicitys.lookup(ethnicitys.ontology_id)
lookup.hancestro_0463
Ethnicity(ontology_id='HANCESTRO:0463', name='American', definition=None, synonyms=None, parents=array(['HANCESTRO:0566'], dtype=object))
Search terms¶
Search behaves in the same way as it does for registries:
ethnicitys.search("American").head(3)
| name | definition | synonyms | parents | |
|---|---|---|---|---|
| ontology_id | ||||
| HANCESTRO:0463 | American | None | None | [HANCESTRO:0566] |
| HANCESTRO:0013 | Native American | Includes Indigenous Individuals Of North, Cent... | American Indian | [HANCESTRO:0004] |
| HANCESTRO:0016 | African American or Afro-Caribbean | Includes Individuals Who Either Self-Report Or... | None | [HANCESTRO:0004] |
By default, search also covers synonyms and all other fileds containing strings:
ethnicitys.search("Caucasian").head(3)
| name | definition | synonyms | parents | |
|---|---|---|---|---|
| ontology_id | ||||
| HANCESTRO:0005 | European | Includes Individuals Who Either Self-Report Or... | Caucasian|white | [HANCESTRO:0004] |
Search specific field (by default, search is done on all fields containing strings):
ethnicitys.search(
"General characterisation of the Ancestry of a population",
field=ethnicitys.definition,
).head()
| name | definition | synonyms | parents | |
|---|---|---|---|---|
| ontology_id | ||||
| HANCESTRO:0304 | ancestry status | General Characterisation Of The Ancestry Of A ... | None | [] |
Standardize Ethnicity identifiers¶
Let us generate a DataFrame that stores a number of Ethnicity identifiers, some of which corrupted:
df_orig = pd.DataFrame(
index=[
"Mende",
"European",
"South Asian",
"Arab",
"This ethnicity does not exist",
]
)
df_orig
| Mende |
|---|
| European |
| South Asian |
| Arab |
| This ethnicity does not exist |
We can check whether any of our values are validated against the ontology reference:
validated = ethnicitys.validate(df_orig.index, ethnicitys.name)
df_orig.index[~validated]
! 1 unique term (20.00%) is not validated: 'This ethnicity does not exist'
Index(['This ethnicity does not exist'], dtype='object')
Ontology source versions¶
For any given entity, we can choose from a number of versions:
bt.Source.filter(entity="bionty.Ethnicity").df()
# only lists the sources that are currently used
bt.Source.filter(entity="bionty.Ethnicity", currently_used=True).df()
| uid | entity | organism | name | in_db | currently_used | description | url | md5 | source_website | space_id | dataframe_artifact_id | version | run_id | created_at | created_by_id | _aux | branch_id | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| id | ||||||||||||||||||
| 32 | MJRqduf9 | bionty.Ethnicity | human | hancestro | False | True | Human Ancestry Ontology | http://purl.obolibrary.org/obo/hancestro/relea... | None | https://github.com/EBISPOT/hancestro | 1 | None | 3.0 | None | 2025-07-14 06:41:44.843000+00:00 | 1 | None | 1 |
When instantiating a Bionty object, we can choose a source or version:
source = bt.Source.filter(
name="hancestro", organism="human"
).first()
ethnicitys= bt.Ethnicity.public(source=source)
ethnicitys
PublicOntology
Entity: Ethnicity
Organism: human
Source: hancestro, 3.0
#terms: 342
The currently used ontologies can be displayed using:
bt.Source.filter(currently_used=True).df()