Manage biological ontologies

This guide shows how to manage ontologies for basic biological entities based on plugin bionty.

If instead you’re interested in

• accessing public ontologies, see Access public ontologies

• flexible bio registries for the wetlab (a LIMS), see Record and Work with sheets

# pip install lamindb
!lamin init --storage ./test-ontologies --modules bionty

Show code cell output Hide code cell output

→ initialized lamindb: testuser1/test-ontologies

Import records from public ontologies

Let’s first populate our CellType registry with the default public ontology (Cell Ontology).

import lamindb as ln
import bionty as bt

# inspect the available public ontology versions
bt.Source.to_dataframe()

Show code cell output Hide code cell output

→ connected lamindb: testuser1/test-ontologies

	uid	entity	organism	name	version	in_db	currently_used	description	url	md5	source_website	is_locked	created_at	branch_id	space_id	created_by_id	run_id	dataframe_artifact_id
id
67	5JnVODh4	BioSample	all	ncbi	2023-09	False	True	NCBI BioSample attributes	s3://bionty-assets/df_all__ncbi__2023-09__BioS...	None	https://www.ncbi.nlm.nih.gov/biosample/docs/at...	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
66	7au3ZQrD	bionty.Ethnicity	human	hancestro	2025-10-14	False	True	Human Ancestry Ontology	http://purl.obolibrary.org/obo/hancestro/relea...	None	https://github.com/EBISPOT/hancestro	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
65	6na9vRls	bionty.DevelopmentalStage	mouse	mmusdv	2025-01-23	False	True	Mouse Developmental Stages	https://github.com/obophenotype/developmental-...	None	https://github.com/obophenotype/developmental-...	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
64	7JO1x6p1	bionty.DevelopmentalStage	human	hsapdv	2025-01-23	False	True	Human Developmental Stages	https://github.com/obophenotype/developmental-...	None	https://github.com/obophenotype/developmental-...	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
63	1atB0WnU	Drug	all	chebi	2024-07-27	False	False	Chemical Entities of Biological Interest	s3://bionty-assets/df_all__chebi__2024-07-27__...	None	https://www.ebi.ac.uk/chebi/	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
62	ugaIoIlj	Drug	all	dron	2024-08-05	False	True	Drug Ontology	http://purl.obolibrary.org/obo/dron/releases/2...	None	https://bioportal.bioontology.org/ontologies/DRON	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
61	3rm9aOzL	BFXPipeline	all	lamin	1.0.0	False	True	Bioinformatics Pipeline	s3://bionty-assets/df_all__lamin__1.0.0__BFXpi...	None	https://lamin.ai	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
60	5ax0h5Ue	bionty.Pathway	all	pw	7.96	False	False	Pathway Ontology	http://purl.obolibrary.org/obo/pw/7.96/pw.owl	None	https://www.ebi.ac.uk/ols/ontologies/pw	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
59	2UZHts8n	bionty.Pathway	all	go	2025-10-10	False	True	Gene Ontology	http://purl.obolibrary.org/obo/go/releases/202...	None	http://geneontology.org	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
58	15uFx5W4	bionty.Phenotype	human	phe	1.2	False	False	Phecodes ICD10 map	s3://bionty-assets/df_human__phe__1.2__Phenoty...	None	https://phewascatalog.org/phecodes_icd10	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
57	h5EFbQNJ	bionty.Phenotype	human	hp	2026-01-08	False	True	Human Phenotype Ontology	https://github.com/obophenotype/human-phenotyp...	None	https://hpo.jax.org	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
56	2rMQe2ZH	bionty.Phenotype	all	pato	2025-05-14	False	True	Phenotype And Trait Ontology	http://purl.obolibrary.org/obo/pato/releases/2...	None	https://github.com/pato-ontology/pato	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
55	7DFdvM5S	bionty.ExperimentalFactor	all	efo	3.85.0	False	True	The Experimental Factor Ontology	http://www.ebi.ac.uk/efo/releases/v3.85.0/efo.owl	None	https://bioportal.bioontology.org/ontologies/EFO	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
54	25rhq3yV	bionty.Disease	human	icd	icd-11-2023	False	False	International Classification of Diseases (ICD)	s3://bionty-assets/df_human__icd__icd-11-2023_...	None	https://www.who.int/standards/classifications/...	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
53	5pzW1FWn	bionty.Disease	human	doid	2025-12-23	False	True	Human Disease Ontology	http://purl.obolibrary.org/obo/doid/releases/2...	None	https://disease-ontology.org	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
52	1gZ2spLp	bionty.Disease	all	mondo	2026-01-06	False	True	Mondo Disease Ontology	http://purl.obolibrary.org/obo/mondo/releases/...	None	https://mondo.monarchinitiative.org	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
51	2zRjWH6J	bionty.Tissue	all	uberon	2025-12-04	False	True	Uberon multi-species anatomy ontology	http://purl.obolibrary.org/obo/uberon/releases...	None	http://obophenotype.github.io/uberon	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
50	6Z0wRdof	bionty.CellType	all	cl	2025-12-17	False	True	Cell Ontology	http://purl.obolibrary.org/obo/cl/releases/202...	None	https://obophenotype.github.io/cell-ontology	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
49	2zHOtEVP	bionty.CellLine	all	depmap	2024-Q2	False	False	Dependency Map	s3://bionty-assets/df_all__depmap__2024-Q2__Ce...	None	https://depmap.org/portal/	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
48	6LyRtvz8	bionty.CellLine	all	clo	2022-03-21	False	False	Cell Line Ontology	s3://bionty-assets/df_all__clo__2022-03-21__Ce...	None	https://bioportal.bioontology.org/ontologies/CLO	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
47	5kJm0APo	bionty.CellLine	all	cellosaurus	53.0	False	True	Cellosaurus	s3://bionty-assets/df_all__cellosaurus__53.0__...	None	https://www.cellosaurus.org/	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
46	7bV5uJo3	bionty.CellMarker	mouse	cellmarker	2.0	False	True	CellMarker	s3://bionty-assets/mouse_cellmarker_2.0_CellMa...	None	http://bio-bigdata.hrbmu.edu.cn/CellMarker	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
45	3kDh8qAX	bionty.CellMarker	human	cellmarker	2.0	False	True	CellMarker	s3://bionty-assets/human_cellmarker_2.0_CellMa...	None	http://bio-bigdata.hrbmu.edu.cn/CellMarker	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
44	01RWXN2V	bionty.Protein	mouse	uniprot	2024-03	False	True	Uniprot	s3://bionty-assets/df_mouse__uniprot__2024-03_...	None	https://www.uniprot.org	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
43	3EYyGRYN	bionty.Protein	human	uniprot	2024-03	False	True	Uniprot	s3://bionty-assets/df_human__uniprot__2024-03_...	None	https://www.uniprot.org	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
42	7SwZGnr2	bionty.Gene	saccharomyces cerevisiae	ensembl	release-114	False	True	Ensembl	s3://bionty-assets/df_saccharomyces cerevisiae...	None	https://www.ensembl.org	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
41	2wv9SRzv	bionty.Gene	mouse	ensembl	release-114	False	True	Ensembl	s3://bionty-assets/df_mouse__ensembl__release-...	None	https://www.ensembl.org	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
40	2w43l1YS	bionty.Gene	human	ensembl	release-114	False	True	Ensembl	s3://bionty-assets/df_human__ensembl__release-...	None	https://www.ensembl.org	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
39	3wWO3xfZ	bionty.Organism	all	ncbitaxon	2025-12-03	False	True	NCBItaxon Ontology	http://purl.obolibrary.org/obo/ncbitaxon/2025-...	None	https://github.com/obophenotype/ncbitaxon	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
38	7GPHh16S	bionty.Organism	plants	ensembl	release-57	False	True	Ensembl	https://ftp.ensemblgenomes.ebi.ac.uk/pub/plant...	None	https://www.ensembl.org	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
37	2PmTrc8x	bionty.Organism	metazoa	ensembl	release-57	False	True	Ensembl	https://ftp.ensemblgenomes.ebi.ac.uk/pub/metaz...	None	https://www.ensembl.org	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
36	6s9nV6xh	bionty.Organism	fungi	ensembl	release-57	False	True	Ensembl	https://ftp.ensemblgenomes.ebi.ac.uk/pub/fungi...	None	https://www.ensembl.org	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
35	6bbVUTCS	bionty.Organism	bacteria	ensembl	release-57	False	True	Ensembl	https://ftp.ensemblgenomes.ebi.ac.uk/pub/bacte...	None	https://www.ensembl.org	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
34	6o9usTh3	bionty.Organism	vertebrates	ensembl	release-114	False	True	Ensembl	https://ftp.ensembl.org/pub/release-114/specie...	None	https://www.ensembl.org	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None

# inspect which ontology version we're about to import
bt.Source.get(entity="bionty.CellType", currently_used=True)

Show code cell output Hide code cell output

Source(uid='6Z0wRdof', entity='bionty.CellType', organism='all', name='cl', version='2025-12-17', in_db=False, currently_used=True, description='Cell Ontology', url='http://purl.obolibrary.org/obo/cl/releases/2025-12-17/cl.owl', md5=None, source_website='https://obophenotype.github.io/cell-ontology', branch_id=1, space_id=1, created_by_id=3, run_id=None, dataframe_artifact_id=None, created_at=2026-01-26 16:01:15 UTC, is_locked=False)

# populate the database with a public ontology
bt.CellType.import_source()

This is now your in-house cell type ontology in which you can add & modify records as you like. It’s a registry just like Artifact or Record.

# all public cell types are now available in LaminDB
bt.CellType.to_dataframe()

Show code cell output Hide code cell output

	uid	name	ontology_id	abbr	synonyms	description	is_locked	created_at	branch_id	space_id	created_by_id	run_id	source_id
id
3437	1ChUsEzDZXWW4B	beam B cell, human	CL:7770006	None	None	A Trabecular Meshwork Cell Within The Eye'S Tr...	False	2026-01-26 16:01:20.831000+00:00	1	1	3	None	50
3436	5xoxfxIf7WrLdU	beam cell	CL:7770005	None	None	A Trabecular Meshwork Cell That Is Part Of The...	False	2026-01-26 16:01:20.831000+00:00	1	1	3	None	50
3435	2j5mhhFoV2vBDV	suprabasal cell	CL:7770004	None	None	An Epithelial Cell That Resides In The Layer(S...	False	2026-01-26 16:01:20.831000+00:00	1	1	3	None	50
3434	RBCFqAmkM1oaaZ	beam A cell	CL:7770003	None	None	A Beam Cell Within The Eye'S Trabecular Meshwo...	False	2026-01-26 16:01:20.831000+00:00	1	1	3	None	50
3433	79Ow7BGPRP018I	juxtacanalicular tissue cell	CL:7770002	None	None	A Trabecular Meshwork Cell Of The Juxtacanalic...	False	2026-01-26 16:01:20.831000+00:00	1	1	3	None	50
...	...	...	...	...	...	...	...	...	...	...	...	...	...
3342	gDJgUmTBv5AHYt	Astro-OLF NN_2 Alk astrocyte (Mmus)	CL:4307054	None	5234 Astro-OLF NN_2	A Astrocyte Of The Mus Musculus Brain. It Is D...	False	2026-01-26 16:01:20.817000+00:00	1	1	3	None	50
3341	51U0BVtjFHQGxE	Astro-OLF NN_2 Slc25a34 astrocyte (Mmus)	CL:4307053	None	5233 Astro-OLF NN_2	A Astrocyte Of The Mus Musculus Brain. It Is D...	False	2026-01-26 16:01:20.817000+00:00	1	1	3	None	50
3340	FjYN3z6zMFQ3JV	Astro-OLF NN_1 Stk32a astrocyte (Mmus)	CL:4307052	None	5232 Astro-OLF NN_1	A Astrocyte Of The Mus Musculus Brain. It Is D...	False	2026-01-26 16:01:20.817000+00:00	1	1	3	None	50
3339	8tHAMMeaiLxdaP	Astro-OLF NN_1 Greb1 astrocyte (Mmus)	CL:4307051	None	5231 Astro-OLF NN_1	A Astrocyte Of The Mus Musculus Brain. It Is D...	False	2026-01-26 16:01:20.817000+00:00	1	1	3	None	50
3338	5SkKyhULGbfXWC	Astro-TE NN_5 Adamts18 astrocyte (Mmus)	CL:4307050	None	5230 Astro-TE NN_5	A Astrocyte Of The Mus Musculus Brain. It Is D...	False	2026-01-26 16:01:20.817000+00:00	1	1	3	None	50

100 rows × 13 columns

# let's also populate the Gene registry with human and mouse genes
bt.Gene.import_source(organism="human")
bt.Gene.import_source(organism="mouse")

Show code cell output Hide code cell output

→ starting creation of 91673 Gene records in batches of 10000

→ starting creation of 78630 Gene records in batches of 10000

Access records in in-house registries

Search key words:

bt.CellType.search("gamma-delta T").to_dataframe().head(2)

	uid	name	ontology_id	abbr	synonyms	description	is_locked	created_at	branch_id	space_id	created_by_id	run_id	source_id
id
780	1HuNn2EPaZnqWk	gamma-delta T cell	CL:0000798	None	gammadelta T cell|gamma-delta T-lymphocyte|gam...	A T Cell That Expresses A Gamma-Delta T Cell R...	False	2026-01-26 16:01:20.274000+00:00	1	1	3	None	50
781	70lHcCNwY7Kxtr	immature gamma-delta T cell	CL:0000799	None	immature gamma-delta T-cell|immature gamma-del...	A Gamma-Delta T Cell That Has An Immature Phen...	False	2026-01-26 16:01:20.274000+00:00	1	1	3	None	50

Or look up with auto-complete:

cell_types = bt.CellType.lookup()
hsc_record = cell_types.hematopoietic_stem_cell
hsc_record

CellType(uid='2U8xapxuL7VEqb', name='hematopoietic stem cell', ontology_id='CL:0000037', abbr=None, synonyms='hemopoietic stem cell|blood forming stem cell', description='A Stem Cell From Which All Cells Of The Lymphoid And Myeloid Lineages Develop, Including Blood Cells And Cells Of The Immune System. Hematopoietic Stem Cells Lack Cell Markers Of Effector Cells (Lin-Negative). Lin-Negative Is Defined By Lacking One Or More Of The Following Cell Surface Markers: Cd2, Cd3 Epsilon, Cd4, Cd5 ,Cd8 Alpha Chain, Cd11B, Cd14, Cd19, Cd20, Cd56, Ly6G, Ter119.', branch_id=1, space_id=1, created_by_id=3, run_id=None, source_id=50, created_at=2026-01-26 16:01:20 UTC, is_locked=False)

Filter by fields and relationships:

gdt_cell = bt.CellType.get(ontology_id="CL:0000798", created_by__handle="testuser1")
gdt_cell

CellType(uid='1HuNn2EPaZnqWk', name='gamma-delta T cell', ontology_id='CL:0000798', abbr=None, synonyms='gammadelta T cell|gamma-delta T-lymphocyte|gamma-delta T lymphocyte|gamma-delta T-cell', description='A T Cell That Expresses A Gamma-Delta T Cell Receptor Complex.', branch_id=1, space_id=1, created_by_id=3, run_id=None, source_id=50, created_at=2026-01-26 16:01:20 UTC, is_locked=False)

View the ontological hierarchy:

gdt_cell.view_parents()  # pass with_children=True to also view children

Or access the parents and children directly:

gdt_cell.parents.to_dataframe()

Show code cell output Hide code cell output

	uid	name	ontology_id	abbr	synonyms	description	is_locked	created_at	branch_id	space_id	created_by_id	run_id	source_id
id
83	22LvKd01YyNA1a	T cell	CL:0000084	None	T lymphocyte|T-lymphocyte|T-cell	A Type Of Lymphocyte Whose Defining Characteri...	False	2026-01-26 16:01:20.173000+00:00	1	1	3	None	50

gdt_cell.children.to_dataframe()

Show code cell output Hide code cell output

	uid	name	ontology_id	abbr	synonyms	description	is_locked	created_at	branch_id	space_id	created_by_id	run_id	source_id
id
2959	5XXsI4tmojLPen	cycling gamma-delta T cell	CL:4033072	None	proliferating gamma-delta T cell	A(N) Gamma-Delta T Cell That Is Cycling.	False	2026-01-26 16:01:20.752000+00:00	1	1	3	None	50
1465	26icgrTr4Nb1i3	gamma-delta thymocyte	CL:0002405	None	gd thymocyte|gammadelta thymocyte	A Post-Natal Thymocyte Expressing Components O...	False	2026-01-26 16:01:20.388000+00:00	1	1	3	None	50
782	3W6NKGpWdMLuOn	mature gamma-delta T cell	CL:0000800	None	mature gamma-delta T-cell|mature gamma-delta T...	A Gamma-Delta T Cell That Has A Mature Phenoty...	False	2026-01-26 16:01:20.274000+00:00	1	1	3	None	50
781	70lHcCNwY7Kxtr	immature gamma-delta T cell	CL:0000799	None	immature gamma-delta T-cell|immature gamma-del...	A Gamma-Delta T Cell That Has An Immature Phen...	False	2026-01-26 16:01:20.274000+00:00	1	1	3	None	50

It is also possible to recursively query parents or children, getting direct parents (children), their parents, and so forth.

gdt_cell.query_parents().to_dataframe()

Show code cell output Hide code cell output

	uid	name	ontology_id	abbr	synonyms	description	is_locked	created_at	branch_id	space_id	created_by_id	run_id	source_id
id
1303	u3sr1GdfF3aIV9	nucleate cell	CL:0002242	None	None	A Cell Containing At Least One Nucleus.	False	2026-01-26 16:01:20.357000+00:00	1	1	3	None	50
967	4Ilrnj9ULJe69Z	hematopoietic cell	CL:0000988	None	haemopoietic cell|hemopoietic cell|haematopoie...	A Cell Of A Hematopoietic Lineage.	False	2026-01-26 16:01:20.305000+00:00	1	1	3	None	50
822	2Jgr5Xx4RSJlVB	mononuclear leukocyte	CL:0000842	None	mononuclear cell	A Leukocyte With A Single Non-Segmented Nucleu...	False	2026-01-26 16:01:20.284000+00:00	1	1	3	None	50
721	3VEAlFdi0Fh4OT	leukocyte	CL:0000738	None	white blood cell|leucocyte	An Achromatic Cell Of The Myeloid Or Lymphoid ...	False	2026-01-26 16:01:20.264000+00:00	1	1	3	None	50
529	X6c7osZ5A24bW2	lymphocyte	CL:0000542	None	None	A Lymphocyte Is A Leukocyte Commonly Found In ...	False	2026-01-26 16:01:20.243000+00:00	1	1	3	None	50
250	4WnpvUTHNi32Fp	eukaryotic cell	CL:0000255	None	None	Any Cell That In Taxon Some Eukaryota.	False	2026-01-26 16:01:20.193000+00:00	1	1	3	None	50
221	2cXC7cgFM5zNgH	single nucleate cell	CL:0000226	None	None	A Cell With A Single Nucleus.	False	2026-01-26 16:01:20.193000+00:00	1	1	3	None	50
214	2K93w3xOD2sghG	motile cell	CL:0000219	None	None	A Cell That Moves By Its Own Activities.	False	2026-01-26 16:01:20.193000+00:00	1	1	3	None	50
83	22LvKd01YyNA1a	T cell	CL:0000084	None	T lymphocyte|T-lymphocyte|T-cell	A Type Of Lymphocyte Whose Defining Characteri...	False	2026-01-26 16:01:20.173000+00:00	1	1	3	None	50
1	4bKGljt0Rpixy0	cell	CL:0000000	None	None	A Material Entity Of Anatomical Origin (Part O...	False	2026-01-26 16:01:20.163000+00:00	1	1	3	None	50

gdt_cell.query_children().to_dataframe()

Show code cell output Hide code cell output

	uid	name	ontology_id	abbr	synonyms	description	is_locked	created_at	branch_id	space_id	created_by_id	run_id	source_id
id
2959	5XXsI4tmojLPen	cycling gamma-delta T cell	CL:4033072	None	proliferating gamma-delta T cell	A(N) Gamma-Delta T Cell That Is Cycling.	False	2026-01-26 16:01:20.752000+00:00	1	1	3	None	50
2176	1rmso5r0areUcW	V1delta gamma-delta T cell	CL:0020001	None	None	A Mature Gamma-Delta T Cell With T Cell Recept...	False	2026-01-26 16:01:20.625000+00:00	1	1	3	None	50
1573	E2koIf0laWBvVp	Vgamma5-negative CD8-alpha alpha positive gamm...	CL:0002514	None	tgd.vg5-.IEL	A Cd8-Alpha Alpha Positive Gamma-Delta Intraep...	False	2026-01-26 16:01:20.529000+00:00	1	1	3	None	50
1572	1jlK4jJ9cfpNl2	Vgamma5-positive CD8-alpha alpha positive gamm...	CL:0002513	None	tgd.vg5+.IEL	A Cd8-Alpha Alpha Positive Gamma-Delta Intraep...	False	2026-01-26 16:01:20.529000+00:00	1	1	3	None	50
1476	6JxpxGgMxEOE0s	mature Vgamma1.1-positive, Vdelta6.3-positive ...	CL:0002416	None	mature Vg1.1+Vd6.3+ T cell	A Vgamma1.1-Positive, Vdelta6.3-Positive Thymo...	False	2026-01-26 16:01:20.388000+00:00	1	1	3	None	50
1475	2SYX59uOSAhgLG	immature Vgamma1.1-positive, Vdelta6.3-positiv...	CL:0002415	None	immature Vg1.1+Vd6.3+ T cell	A Vgamma1.1-Positive, Vdelta6.3-Positive Thymo...	False	2026-01-26 16:01:20.388000+00:00	1	1	3	None	50
1474	5pDjyjfFx2qcX8	immature Vgamma1.1-positive, Vdelta6.3-negativ...	CL:0002414	None	None	A Vgamma1.1-Positive, Vdelta6.3-Negative Thymo...	False	2026-01-26 16:01:20.388000+00:00	1	1	3	None	50
1473	4cYNDr25MbvIM8	mature Vgamma1.1-positive, Vdelta6.3-negative ...	CL:0002413	None	None	A Vgamma1.1-Positive, Vdelta6.3-Negative Thymo...	False	2026-01-26 16:01:20.388000+00:00	1	1	3	None	50
1472	6vYlL7zk77kX4K	Vgamma1.1-positive, Vdelta6.3-positive thymocyte	CL:0002412	None	Vg1.1+Vd6.3+ T cell	A Gamma-Delta Receptor That Expresses Vgamma1....	False	2026-01-26 16:01:20.388000+00:00	1	1	3	None	50
1471	64PCjpkJNJlQkE	Vgamma1.1-positive, Vdelta6.3-negative thymocyte	CL:0002411	None	Vg1.1-positive, Vd6.3-negative T cell	A Gamma-Delta Receptor That Expresses Vgamma1....	False	2026-01-26 16:01:20.388000+00:00	1	1	3	None	50
1469	6RBJq86bxJmQam	mature Vgamma2-negative thymocyte	CL:0002409	None	Vgamma2-negative	A Thymocyte That Has A T Cell Receptor Consist...	False	2026-01-26 16:01:20.388000+00:00	1	1	3	None	50
1468	3ABJ1l1OfMZer3	immature Vgamma2-negative thymocyte	CL:0002408	None	None	A Double Negative Post-Natal Thymocyte That Ha...	False	2026-01-26 16:01:20.388000+00:00	1	1	3	None	50
1467	76CEFg3AEDmvSZ	mature Vgamma2-positive thymocyte	CL:0002407	None	Vgamma2-positive	A Thymocyte That Has A T Cell Receptor Consist...	False	2026-01-26 16:01:20.388000+00:00	1	1	3	None	50
1466	4hrSce5T2s8hii	immature Vgamma2-positive thymocyte	CL:0002406	None	None	A Double Negative Post-Natal Thymocyte That Ha...	False	2026-01-26 16:01:20.388000+00:00	1	1	3	None	50
1465	26icgrTr4Nb1i3	gamma-delta thymocyte	CL:0002405	None	gd thymocyte|gammadelta thymocyte	A Post-Natal Thymocyte Expressing Components O...	False	2026-01-26 16:01:20.388000+00:00	1	1	3	None	50
1191	3efemme8yo4Gfv	CD25-positive, CD27-positive immature gamma-de...	CL:0002126	None	None	A Cd25-Positive, Cd27-Positive Immature Gamma-...	False	2026-01-26 16:01:20.346000+00:00	1	1	3	None	50
1190	1DEERh4LNvIxVR	CD27-negative gamma-delta T cell	CL:0002125	None	gammadelta-17 cells	A Circulating Gamma-Delta T Cell That Expresse...	False	2026-01-26 16:01:20.346000+00:00	1	1	3	None	50
1189	7MDv71IVlcKghc	CD27-positive gamma-delta T cell	CL:0002124	None	gd27-positive|gammadelta27-positive	A Circulating Gamma-Delta T Cell That Is Cd27-...	False	2026-01-26 16:01:20.346000+00:00	1	1	3	None	50
895	1tYOPZxHGFlbLS	dendritic epidermal T cell	CL:0000916	None	dendritic epidermal T-cell|dendritic epidermal...	A Mature Gamma-Delta T Cell Located In The Epi...	False	2026-01-26 16:01:20.295000+00:00	1	1	3	None	50
785	1mNzVotOD9guI6	CD4-negative CD8-negative gamma-delta intraepi...	CL:0000803	None	CD4-positive, gamma-delta intraepithelial T-ce...	A Gamma-Delta Intraepithelial T Cell That Has ...	False	2026-01-26 16:01:20.274000+00:00	1	1	3	None	50
784	6fdlvmJ3Dq1aU6	CD8-alpha alpha positive, gamma-delta intraepi...	CL:0000802	None	CD8-positive, gamma-delta intraepithelial T ly...	A Gamma-Delta Intraepithelial T Cell That Has ...	False	2026-01-26 16:01:20.274000+00:00	1	1	3	None	50
783	2xXcHDQqOsWKH2	gamma-delta intraepithelial T cell	CL:0000801	None	gamma-delta intraepithelial T-lymphocyte|gamma...	A Mature Gamma-Delta T Cell That Is Found In T...	False	2026-01-26 16:01:20.274000+00:00	1	1	3	None	50
782	3W6NKGpWdMLuOn	mature gamma-delta T cell	CL:0000800	None	mature gamma-delta T-cell|mature gamma-delta T...	A Gamma-Delta T Cell That Has A Mature Phenoty...	False	2026-01-26 16:01:20.274000+00:00	1	1	3	None	50
781	70lHcCNwY7Kxtr	immature gamma-delta T cell	CL:0000799	None	immature gamma-delta T-cell|immature gamma-del...	A Gamma-Delta T Cell That Has An Immature Phen...	False	2026-01-26 16:01:20.274000+00:00	1	1	3	None	50

Construct custom hierarchies of records

You can add a child of a parent record:

# register a new cell type
my_celltype = bt.CellType(name="my new T-cell subtype").save()
# specify "gamma-delta T cell" as a parent
my_celltype.parents.add(gdt_cell)

# visualize hierarchy
my_celltype.view_parents(distance=3)

Create new records

When accessing datasets, one often encounters bulk references to entities that might be corrupted or standardized using different standardization schemes.

Let’s consider an example based on an AnnData object, in the cell_type annotations of this AnnData object, we find 4 references to cell types:

adata = ln.examples.datasets.anndata_with_obs()
adata.obs.cell_type.value_counts()

Show code cell output Hide code cell output

cell_type
T cell                     10
hematopoietic stem cell    10
hepatocyte                 10
my new cell type           10
Name: count, dtype: int64

We’d like to load the corresponding records in our in-house registry to annotate a dataset.

To this end, you’ll typically use from_values, which will both validate & retrieve records that match the values.

cell_types = bt.CellType.from_values(adata.obs.cell_type)
cell_types

Show code cell output Hide code cell output

SQLRecordList([CellType(uid='2U8xapxuL7VEqb', name='hematopoietic stem cell', ontology_id='CL:0000037', abbr=None, synonyms='hemopoietic stem cell|blood forming stem cell', description='A Stem Cell From Which All Cells Of The Lymphoid And Myeloid Lineages Develop, Including Blood Cells And Cells Of The Immune System. Hematopoietic Stem Cells Lack Cell Markers Of Effector Cells (Lin-Negative). Lin-Negative Is Defined By Lacking One Or More Of The Following Cell Surface Markers: Cd2, Cd3 Epsilon, Cd4, Cd5 ,Cd8 Alpha Chain, Cd11B, Cd14, Cd19, Cd20, Cd56, Ly6G, Ter119.', branch_id=1, space_id=1, created_by_id=3, run_id=None, source_id=50, created_at=2026-01-26 16:01:20 UTC, is_locked=False),
               CellType(uid='22LvKd01YyNA1a', name='T cell', ontology_id='CL:0000084', abbr=None, synonyms='T lymphocyte|T-lymphocyte|T-cell', description='A Type Of Lymphocyte Whose Defining Characteristic Is The Expression Of A T Cell Receptor Complex.', branch_id=1, space_id=1, created_by_id=3, run_id=None, source_id=50, created_at=2026-01-26 16:01:20 UTC, is_locked=False),
               CellType(uid='7hggmgo1zjJTGi', name='hepatocyte', ontology_id='CL:0000182', abbr=None, synonyms=None, description='The Main Structural Component Of The Liver. They Are Specialized Epithelial Cells That Are Organized Into Interconnected Plates Called Lobules. Majority Of Cell Population Of Liver, Polygonal In Shape, Arranged In Plates Or Trabeculae Between Sinusoids; May Have Single Nucleus Or Binucleated.', branch_id=1, space_id=1, created_by_id=3, run_id=None, source_id=50, created_at=2026-01-26 16:01:20 UTC, is_locked=False)])

Logging informed us that 3 cell types were validated. Since we loaded these records at the same time, we could readily use them to annotate a dataset.

What happened under-the-hood?

.from_values() performs the following look ups:

1. If registry records match the values, load these records

2. If values match synonyms of registry records, load these records

3. If no record in the registry matches, attempt to load records from a public ontology

4. Same as 3. but based on synonyms

No records will be returned if all 4 look ups are unsuccessful.

Sometimes, it’s useful to treat validated records differently from non-validated records. Here is a way:

original_values = ["gut", "gut2"]
inspector = bt.Tissue.inspect(original_values)
records_from_validated_values = bt.Tissue.from_values(inspector.validated)

Alternatively, we can retrieve records based on ontology ids:

adata.obs.cell_type_id.unique().tolist()

Show code cell output Hide code cell output

['CL:0000084', 'CL:0000037', 'CL:0000182', '']

bt.CellType.from_values(adata.obs.cell_type_id, field=bt.CellType.ontology_id)

Show code cell output Hide code cell output

SQLRecordList([CellType(uid='2U8xapxuL7VEqb', name='hematopoietic stem cell', ontology_id='CL:0000037', abbr=None, synonyms='hemopoietic stem cell|blood forming stem cell', description='A Stem Cell From Which All Cells Of The Lymphoid And Myeloid Lineages Develop, Including Blood Cells And Cells Of The Immune System. Hematopoietic Stem Cells Lack Cell Markers Of Effector Cells (Lin-Negative). Lin-Negative Is Defined By Lacking One Or More Of The Following Cell Surface Markers: Cd2, Cd3 Epsilon, Cd4, Cd5 ,Cd8 Alpha Chain, Cd11B, Cd14, Cd19, Cd20, Cd56, Ly6G, Ter119.', branch_id=1, space_id=1, created_by_id=3, run_id=None, source_id=50, created_at=2026-01-26 16:01:20 UTC, is_locked=False),
               CellType(uid='22LvKd01YyNA1a', name='T cell', ontology_id='CL:0000084', abbr=None, synonyms='T lymphocyte|T-lymphocyte|T-cell', description='A Type Of Lymphocyte Whose Defining Characteristic Is The Expression Of A T Cell Receptor Complex.', branch_id=1, space_id=1, created_by_id=3, run_id=None, source_id=50, created_at=2026-01-26 16:01:20 UTC, is_locked=False),
               CellType(uid='7hggmgo1zjJTGi', name='hepatocyte', ontology_id='CL:0000182', abbr=None, synonyms=None, description='The Main Structural Component Of The Liver. They Are Specialized Epithelial Cells That Are Organized Into Interconnected Plates Called Lobules. Majority Of Cell Population Of Liver, Polygonal In Shape, Arranged In Plates Or Trabeculae Between Sinusoids; May Have Single Nucleus Or Binucleated.', branch_id=1, space_id=1, created_by_id=3, run_id=None, source_id=50, created_at=2026-01-26 16:01:20 UTC, is_locked=False)])

Validate & standardize

Simple validation of an iterable of values works like so:

bt.CellType.validate(["fat cell", "blood forming stem cell"])

Show code cell output Hide code cell output

! 2 unique terms (100.00%) are not validated for name: 'fat cell', 'blood forming stem cell'

array([False, False])

Because these values don’t comply with the registry, they’re not validated!

You can easily convert these values to validated standardized names based on synonyms like so:

bt.CellType.standardize(["fat cell", "blood forming stem cell"])

Show code cell output Hide code cell output

['adipocyte', 'hematopoietic stem cell']

Alternatively, you can use .from_values(), which will only ever return validated records and automatically standardize under-the-hood:

bt.CellType.from_values(["fat cell", "blood forming stem cell"])

Show code cell output Hide code cell output

SQLRecordList([CellType(uid='2U8xapxuL7VEqb', name='hematopoietic stem cell', ontology_id='CL:0000037', abbr=None, synonyms='hemopoietic stem cell|blood forming stem cell', description='A Stem Cell From Which All Cells Of The Lymphoid And Myeloid Lineages Develop, Including Blood Cells And Cells Of The Immune System. Hematopoietic Stem Cells Lack Cell Markers Of Effector Cells (Lin-Negative). Lin-Negative Is Defined By Lacking One Or More Of The Following Cell Surface Markers: Cd2, Cd3 Epsilon, Cd4, Cd5 ,Cd8 Alpha Chain, Cd11B, Cd14, Cd19, Cd20, Cd56, Ly6G, Ter119.', branch_id=1, space_id=1, created_by_id=3, run_id=None, source_id=50, created_at=2026-01-26 16:01:20 UTC, is_locked=False),
               CellType(uid='wdLgwUXoz5ZpWT', name='adipocyte', ontology_id='CL:0000136', abbr=None, synonyms='adipose cell|fat cell', description='A Fat-Storing Cell Found Mostly In The Abdominal Cavity And Subcutaneous Tissue Of Mammals. Fat Is Usually Stored In The Form Of Triglycerides.', branch_id=1, space_id=1, created_by_id=3, run_id=None, source_id=50, created_at=2026-01-26 16:01:20 UTC, is_locked=False)])

If you are now sure what to do, use .inspect() to get instructions:

bt.CellType.inspect(["fat cell", "blood forming stem cell"]);

Show code cell output Hide code cell output

! 2 unique terms (100.00%) are not validated for name: 'fat cell', 'blood forming stem cell'

   detected 2 unique terms with synonyms: fat cell, blood forming stem cell

→  standardize terms via .standardize()

We can also add new synonyms to a record:

hsc_record.add_synonym("HSC")

And when we encounter this synonym as a value, it will now be standardized using synonyms-lookup, and mapped on the correct registry record:

bt.CellType.standardize(["HSC"])

Show code cell output Hide code cell output

['hematopoietic stem cell']

A special synonym is .abbr (short for abbreviation), which has its own field and can be assigned via:

hsc_record.set_abbr("HSC")

You can create a lookup object from the .abbr field:

cell_types = bt.CellType.lookup("abbr")
cell_types.hsc

Show code cell output Hide code cell output

CellType(uid='2U8xapxuL7VEqb', name='hematopoietic stem cell', ontology_id='CL:0000037', abbr='HSC', synonyms='hemopoietic stem cell|HSC|blood forming stem cell', description='A Stem Cell From Which All Cells Of The Lymphoid And Myeloid Lineages Develop, Including Blood Cells And Cells Of The Immune System. Hematopoietic Stem Cells Lack Cell Markers Of Effector Cells (Lin-Negative). Lin-Negative Is Defined By Lacking One Or More Of The Following Cell Surface Markers: Cd2, Cd3 Epsilon, Cd4, Cd5 ,Cd8 Alpha Chain, Cd11B, Cd14, Cd19, Cd20, Cd56, Ly6G, Ter119.', branch_id=1, space_id=1, created_by_id=3, run_id=None, source_id=50, created_at=2026-01-26 16:01:20 UTC, is_locked=False)

The same workflow works for all of bionty’s registries.

Manage ontologies across organisms

Several registries are organism-aware (has a .organism field), for instance, Gene.

In this case, API calls that interact with multi-organism registries require an organism argument when there’s ambiguity.

For instance, when validating gene symbols:

bt.Gene.validate(["TCF7", "ABC1"], organism="human")

Show code cell output Hide code cell output

! 1 unique term (50.00%) is not validated for symbol: 'ABC1'

array([ True, False])

In contrary, working with Ensembl Gene IDs doesn’t require passing organism, as there’s no ambiguity:

bt.Gene.validate(
    ["ENSG00000000419", "ENSMUSG00002076988"], field=bt.Gene.ensembl_gene_id
)

! 1 unique term (50.00%) is not validated for ensembl_gene_id: 'ENSMUSG00002076988'

array([ True, False])

When working with the same organism throughout your analysis/workflow, you can omit the organism argument by configuring it globally:

bt.settings.organism = "mouse"
bt.Gene.from_source(symbol="Ap5b1")

Gene(uid='3b8mHb0MRal43m', abbr=None, synonyms='Gm962', description='adaptor-related protein complex 5, beta 1 subunit ', symbol='Ap5b1', stable_id=None, ensembl_gene_id='ENSMUSG00000049562', ncbi_gene_ids=None, biotype='protein_coding', branch_id=1, space_id=1, created_by_id=3, run_id=None, source_id=41, organism_id=2, created_at=2026-01-26 16:02:17 UTC, is_locked=False)

Track ontology versions

Under-the-hood, source ontology versions are automatically tracked for each registry:

bt.Source.filter(currently_used=True).to_dataframe()

Show code cell output Hide code cell output

	uid	entity	organism	name	version	in_db	currently_used	description	url	md5	source_website	is_locked	created_at	branch_id	space_id	created_by_id	run_id	dataframe_artifact_id
id
67	5JnVODh4	BioSample	all	ncbi	2023-09	False	True	NCBI BioSample attributes	s3://bionty-assets/df_all__ncbi__2023-09__BioS...	None	https://www.ncbi.nlm.nih.gov/biosample/docs/at...	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
66	7au3ZQrD	bionty.Ethnicity	human	hancestro	2025-10-14	False	True	Human Ancestry Ontology	http://purl.obolibrary.org/obo/hancestro/relea...	None	https://github.com/EBISPOT/hancestro	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
65	6na9vRls	bionty.DevelopmentalStage	mouse	mmusdv	2025-01-23	False	True	Mouse Developmental Stages	https://github.com/obophenotype/developmental-...	None	https://github.com/obophenotype/developmental-...	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
64	7JO1x6p1	bionty.DevelopmentalStage	human	hsapdv	2025-01-23	False	True	Human Developmental Stages	https://github.com/obophenotype/developmental-...	None	https://github.com/obophenotype/developmental-...	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
62	ugaIoIlj	Drug	all	dron	2024-08-05	False	True	Drug Ontology	http://purl.obolibrary.org/obo/dron/releases/2...	None	https://bioportal.bioontology.org/ontologies/DRON	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
61	3rm9aOzL	BFXPipeline	all	lamin	1.0.0	False	True	Bioinformatics Pipeline	s3://bionty-assets/df_all__lamin__1.0.0__BFXpi...	None	https://lamin.ai	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
59	2UZHts8n	bionty.Pathway	all	go	2025-10-10	False	True	Gene Ontology	http://purl.obolibrary.org/obo/go/releases/202...	None	http://geneontology.org	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
57	h5EFbQNJ	bionty.Phenotype	human	hp	2026-01-08	False	True	Human Phenotype Ontology	https://github.com/obophenotype/human-phenotyp...	None	https://hpo.jax.org	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
56	2rMQe2ZH	bionty.Phenotype	all	pato	2025-05-14	False	True	Phenotype And Trait Ontology	http://purl.obolibrary.org/obo/pato/releases/2...	None	https://github.com/pato-ontology/pato	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
55	7DFdvM5S	bionty.ExperimentalFactor	all	efo	3.85.0	False	True	The Experimental Factor Ontology	http://www.ebi.ac.uk/efo/releases/v3.85.0/efo.owl	None	https://bioportal.bioontology.org/ontologies/EFO	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
53	5pzW1FWn	bionty.Disease	human	doid	2025-12-23	False	True	Human Disease Ontology	http://purl.obolibrary.org/obo/doid/releases/2...	None	https://disease-ontology.org	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
52	1gZ2spLp	bionty.Disease	all	mondo	2026-01-06	False	True	Mondo Disease Ontology	http://purl.obolibrary.org/obo/mondo/releases/...	None	https://mondo.monarchinitiative.org	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
51	2zRjWH6J	bionty.Tissue	all	uberon	2025-12-04	False	True	Uberon multi-species anatomy ontology	http://purl.obolibrary.org/obo/uberon/releases...	None	http://obophenotype.github.io/uberon	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
50	6Z0wRdof	bionty.CellType	all	cl	2025-12-17	True	True	Cell Ontology	http://purl.obolibrary.org/obo/cl/releases/202...	None	https://obophenotype.github.io/cell-ontology	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
47	5kJm0APo	bionty.CellLine	all	cellosaurus	53.0	False	True	Cellosaurus	s3://bionty-assets/df_all__cellosaurus__53.0__...	None	https://www.cellosaurus.org/	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
46	7bV5uJo3	bionty.CellMarker	mouse	cellmarker	2.0	False	True	CellMarker	s3://bionty-assets/mouse_cellmarker_2.0_CellMa...	None	http://bio-bigdata.hrbmu.edu.cn/CellMarker	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
45	3kDh8qAX	bionty.CellMarker	human	cellmarker	2.0	False	True	CellMarker	s3://bionty-assets/human_cellmarker_2.0_CellMa...	None	http://bio-bigdata.hrbmu.edu.cn/CellMarker	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
44	01RWXN2V	bionty.Protein	mouse	uniprot	2024-03	False	True	Uniprot	s3://bionty-assets/df_mouse__uniprot__2024-03_...	None	https://www.uniprot.org	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
43	3EYyGRYN	bionty.Protein	human	uniprot	2024-03	False	True	Uniprot	s3://bionty-assets/df_human__uniprot__2024-03_...	None	https://www.uniprot.org	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
42	7SwZGnr2	bionty.Gene	saccharomyces cerevisiae	ensembl	release-114	False	True	Ensembl	s3://bionty-assets/df_saccharomyces cerevisiae...	None	https://www.ensembl.org	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
41	2wv9SRzv	bionty.Gene	mouse	ensembl	release-114	True	True	Ensembl	s3://bionty-assets/df_mouse__ensembl__release-...	None	https://www.ensembl.org	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
40	2w43l1YS	bionty.Gene	human	ensembl	release-114	True	True	Ensembl	s3://bionty-assets/df_human__ensembl__release-...	None	https://www.ensembl.org	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
39	3wWO3xfZ	bionty.Organism	all	ncbitaxon	2025-12-03	False	True	NCBItaxon Ontology	http://purl.obolibrary.org/obo/ncbitaxon/2025-...	None	https://github.com/obophenotype/ncbitaxon	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
38	7GPHh16S	bionty.Organism	plants	ensembl	release-57	False	True	Ensembl	https://ftp.ensemblgenomes.ebi.ac.uk/pub/plant...	None	https://www.ensembl.org	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
37	2PmTrc8x	bionty.Organism	metazoa	ensembl	release-57	False	True	Ensembl	https://ftp.ensemblgenomes.ebi.ac.uk/pub/metaz...	None	https://www.ensembl.org	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
36	6s9nV6xh	bionty.Organism	fungi	ensembl	release-57	False	True	Ensembl	https://ftp.ensemblgenomes.ebi.ac.uk/pub/fungi...	None	https://www.ensembl.org	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
35	6bbVUTCS	bionty.Organism	bacteria	ensembl	release-57	False	True	Ensembl	https://ftp.ensemblgenomes.ebi.ac.uk/pub/bacte...	None	https://www.ensembl.org	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
34	6o9usTh3	bionty.Organism	vertebrates	ensembl	release-114	False	True	Ensembl	https://ftp.ensembl.org/pub/release-114/specie...	None	https://www.ensembl.org	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None

Each record is linked to a versioned public source (if it was created from public):

hepatocyte = bt.CellType.get(name="hepatocyte")
hepatocyte.source

Show code cell output Hide code cell output

Source(uid='6Z0wRdof', entity='bionty.CellType', organism='all', name='cl', version='2025-12-17', in_db=True, currently_used=True, description='Cell Ontology', url='http://purl.obolibrary.org/obo/cl/releases/2025-12-17/cl.owl', md5=None, source_website='https://obophenotype.github.io/cell-ontology', branch_id=1, space_id=1, created_by_id=3, run_id=None, dataframe_artifact_id=None, created_at=2026-01-26 16:01:15 UTC, is_locked=False)

Create records from a specific ontology version

By default, new records are imported or created from the "currently_used" public sources which are configured during the instance initialization, e.g.:

bt.Source.filter(entity="bionty.Phenotype", currently_used=True).to_dataframe()

Show code cell output Hide code cell output

	uid	entity	organism	name	version	in_db	currently_used	description	url	md5	source_website	is_locked	created_at	branch_id	space_id	created_by_id	run_id	dataframe_artifact_id
id
57	h5EFbQNJ	bionty.Phenotype	human	hp	2026-01-08	False	True	Human Phenotype Ontology	https://github.com/obophenotype/human-phenotyp...	None	https://hpo.jax.org	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None
56	2rMQe2ZH	bionty.Phenotype	all	pato	2025-05-14	False	True	Phenotype And Trait Ontology	http://purl.obolibrary.org/obo/pato/releases/2...	None	https://github.com/pato-ontology/pato	False	2026-01-26 16:01:15.477000+00:00	1	1	3	None	None

Sometimes, the default source doesn’t contain the ontology term you are looking for.

You can then specify to create a record from a non-default source. For instance, we can use the ncbitaxon ontology:

source = bt.Source.get(entity="bionty.Organism", name="ncbitaxon")
source

Source(uid='3wWO3xfZ', entity='bionty.Organism', organism='all', name='ncbitaxon', version='2025-12-03', in_db=False, currently_used=True, description='NCBItaxon Ontology', url='http://purl.obolibrary.org/obo/ncbitaxon/2025-12-03/ncbitaxon.owl', md5=None, source_website='https://github.com/obophenotype/ncbitaxon', branch_id=1, space_id=1, created_by_id=3, run_id=None, dataframe_artifact_id=None, created_at=2026-01-26 16:01:15 UTC, is_locked=False)

# validate against the NCBI Taxonomy
bt.Organism.validate(
    ["iris setosa", "iris versicolor", "iris virginica"], source=source
)

Show code cell output Hide code cell output

! 3 unique terms (100.00%) are not validated for name: 'iris setosa', 'iris versicolor', 'iris virginica'

array([False, False, False])

# since we didn't seed the Organism registry with the NCBITaxon public ontology
# we need to save the records to the database
records = bt.Organism.from_values(
    ["iris setosa", "iris versicolor", "iris virginica"], source=source
).save()

# now we can query a iris organism and view its parents and children
bt.Organism.get(name="iris").view_parents(with_children=True)

Show code cell output Hide code cell output

Access any Ensembl genes

Genes from all Ensembl versions and organisms can be accessed, even though they are not yet present in the bt.Source registry.

For instance, if you want to use rabbit genes from Ensembl version release-103:

# pip install pymysql
import bionty as bt

# automatically download genes for a new organism
gene_ontology = bt.base.Gene(source="ensembl", organism="rabbit", version='release-103')

# register the new source in lamindb
gene_ontology.register_source_in_lamindb()

# now you can start using this source

# import all genes from this source to your Gene registry
source = bt.Source.get(entity="bionty.Gene", name="ensembl", organism="rabbit", version="release-103")
bt.Gene.import_source(source=source)