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

• an unconstrained ontology, see Record

# 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
66	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-11 16:51:09.823000+00:00	1	1	3	None	None
65	MJRqduf9	bionty.Ethnicity	human	hancestro	3.0	False	True	Human Ancestry Ontology	http://purl.obolibrary.org/obo/hancestro/relea...	None	https://github.com/EBISPOT/hancestro	False	2026-01-11 16:51:09.823000+00:00	1	1	3	None	None
64	10va5JSt	bionty.DevelopmentalStage	mouse	mmusdv	2024-05-28	False	True	Mouse Developmental Stages	https://github.com/obophenotype/developmental-...	None	https://github.com/obophenotype/developmental-...	False	2026-01-11 16:51:09.823000+00:00	1	1	3	None	None
63	1GbFkOdz	bionty.DevelopmentalStage	human	hsapdv	2024-05-28	False	True	Human Developmental Stages	https://github.com/obophenotype/developmental-...	None	https://github.com/obophenotype/developmental-...	False	2026-01-11 16:51:09.823000+00:00	1	1	3	None	None
62	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-11 16:51:09.823000+00:00	1	1	3	None	None
61	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-11 16:51:09.823000+00:00	1	1	3	None	None
60	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-11 16:51:09.823000+00:00	1	1	3	None	None
59	40JkiRMw	bionty.Pathway	all	pw	7.84	False	False	Pathway Ontology	http://purl.obolibrary.org/obo/pw/7.84/pw.owl	None	https://www.ebi.ac.uk/ols/ontologies/pw	False	2026-01-11 16:51:09.823000+00:00	1	1	3	None	None
58	7Ent3V2y	bionty.Pathway	all	go	2024-06-17	False	True	Gene Ontology	http://purl.obolibrary.org/obo/go/releases/202...	None	http://geneontology.org	False	2026-01-11 16:51:09.823000+00:00	1	1	3	None	None
57	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-11 16:51:09.823000+00:00	1	1	3	None	None
56	48fBFLmn	bionty.Phenotype	human	hp	2024-04-26	False	True	Human Phenotype Ontology	https://github.com/obophenotype/human-phenotyp...	None	https://hpo.jax.org	False	2026-01-11 16:51:09.823000+00:00	1	1	3	None	None
55	6S4qkDx1	bionty.Phenotype	all	pato	2024-03-28	False	True	Phenotype And Trait Ontology	http://purl.obolibrary.org/obo/pato/releases/2...	None	https://github.com/pato-ontology/pato	False	2026-01-11 16:51:09.823000+00:00	1	1	3	None	None
54	1yS830MU	bionty.ExperimentalFactor	all	efo	3.78.0	False	True	The Experimental Factor Ontology	http://www.ebi.ac.uk/efo/releases/v3.78.0/efo.owl	None	https://bioportal.bioontology.org/ontologies/EFO	False	2026-01-11 16:51:09.823000+00:00	1	1	3	None	None
53	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-11 16:51:09.823000+00:00	1	1	3	None	None
52	4kswnHVF	bionty.Disease	human	doid	2024-05-29	False	True	Human Disease Ontology	http://purl.obolibrary.org/obo/doid/releases/2...	None	https://disease-ontology.org	False	2026-01-11 16:51:09.823000+00:00	1	1	3	None	None
51	IGIkseWQ	bionty.Disease	all	mondo	2025-06-03	False	True	Mondo Disease Ontology	http://purl.obolibrary.org/obo/mondo/releases/...	None	https://mondo.monarchinitiative.org	False	2026-01-11 16:51:09.823000+00:00	1	1	3	None	None
50	4U5uYTlc	bionty.Tissue	all	uberon	2025-05-28	False	True	Uberon multi-species anatomy ontology	http://purl.obolibrary.org/obo/uberon/releases...	None	http://obophenotype.github.io/uberon	False	2026-01-11 16:51:09.823000+00:00	1	1	3	None	None
49	3T9KZcjQ	bionty.CellType	all	cl	2025-04-10	False	True	Cell Ontology	http://purl.obolibrary.org/obo/cl/releases/202...	None	https://obophenotype.github.io/cell-ontology	False	2026-01-11 16:51:09.823000+00:00	1	1	3	None	None
48	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-11 16:51:09.823000+00:00	1	1	3	None	None
47	6LyRtvz8	bionty.CellLine	all	clo	2022-03-21	False	True	Cell Line Ontology	s3://bionty-assets/df_all__clo__2022-03-21__Ce...	None	https://bioportal.bioontology.org/ontologies/CLO	False	2026-01-11 16:51:09.823000+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-11 16:51:09.823000+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-11 16:51:09.823000+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-11 16:51:09.823000+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-11 16:51:09.823000+00:00	1	1	3	None	None
42	4RPA3Re0	bionty.Gene	saccharomyces cerevisiae	ensembl	release-112	False	True	Ensembl	s3://bionty-assets/df_saccharomyces cerevisiae...	None	https://www.ensembl.org	False	2026-01-11 16:51:09.823000+00:00	1	1	3	None	None
41	4r4fvV0S	bionty.Gene	mouse	ensembl	release-112	False	True	Ensembl	s3://bionty-assets/df_mouse__ensembl__release-...	None	https://www.ensembl.org	False	2026-01-11 16:51:09.823000+00:00	1	1	3	None	None
40	4UGNz3fr	bionty.Gene	human	ensembl	release-112	False	True	Ensembl	s3://bionty-assets/df_human__ensembl__release-...	None	https://www.ensembl.org	False	2026-01-11 16:51:09.823000+00:00	1	1	3	None	None
39	4tsksCMX	bionty.Organism	all	ncbitaxon	2023-06-20	False	True	NCBItaxon Ontology	http://purl.obolibrary.org/obo/ncbitaxon/2023-...	None	https://github.com/obophenotype/ncbitaxon	False	2026-01-11 16:51:09.823000+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-11 16:51:09.823000+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-11 16:51:09.823000+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-11 16:51:09.823000+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-11 16:51:09.823000+00:00	1	1	3	None	None
34	33TUF039	bionty.Organism	vertebrates	ensembl	release-112	False	True	Ensembl	https://ftp.ensembl.org/pub/release-112/specie...	None	https://www.ensembl.org	False	2026-01-11 16:51:09.823000+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='3T9KZcjQ', entity='bionty.CellType', organism='all', name='cl', version='2025-04-10', in_db=False, currently_used=True, description='Cell Ontology', url='http://purl.obolibrary.org/obo/cl/releases/2025-04-10/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-11 16:51:09 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
3095	6nw5na3PmONKEC	lateral pyloric motor neuron	CL:4070017	None	LP	A Motor Neuron That Controls Pyloric Filter Mo...	False	2026-01-11 16:51:14.925000+00:00	1	1	3	None	49
3094	7k6v66wYZWDMGW	anterior burster neuron	CL:4070016	None	AB	Pyloric Pacemaker Neuron That Provides Feedbac...	False	2026-01-11 16:51:14.925000+00:00	1	1	3	None	49
3093	2YBgl1kNATwnnN	pyloric dilator neuron	CL:4070015	None	PD	A Motor Neuron That Controls The Cardiopyloric...	False	2026-01-11 16:51:14.925000+00:00	1	1	3	None	49
3092	4FhOIxSqvDheOL	pyloric motor neuron	CL:4070014	None	PY	A Motor Neuron That Controls Pyloric Filter Mo...	False	2026-01-11 16:51:14.925000+00:00	1	1	3	None	49
3091	7N982L0jITR5LO	ventricular dilator motor neuron	CL:4070013	None	VD	A Motor Neuron That Controls Ventral Stomach ...	False	2026-01-11 16:51:14.925000+00:00	1	1	3	None	49
...	...	...	...	...	...	...	...	...	...	...	...	...	...
3000	1lYpfaRMf60Htp	middle primary motoneuron	CL:4042041	None	None	A Type Of Primary Motor Neuron Located In The ...	False	2026-01-11 16:51:14.914000+00:00	1	1	3	None	49
2999	4wsKKFDu4vPaVu	glutamatergic neuron of the basal ganglia	CL:4042040	None	None	A Glutametergic Neuron With Its Soma Located I...	False	2026-01-11 16:51:14.914000+00:00	1	1	3	None	49
2998	2GneiPp3tKWQ2x	caudal ganglionic eminence derived neuron	CL:4042039	None	None	A Neuron Of The Central Nervous System That De...	False	2026-01-11 16:51:14.914000+00:00	1	1	3	None	49
2997	3bfpC22i2x5IkG	rostral primary motorneuron	CL:4042038	None	None	A Type Of Primary Motor Neuron Situated In The...	False	2026-01-11 16:51:14.914000+00:00	1	1	3	None	49
2996	3zrwm9CzjCqEqZ	sst GABAergic neuron of the striatum	CL:4042037	None	None	A Interneuron Of The Striatum Expressing Gamma...	False	2026-01-11 16:51:14.914000+00:00	1	1	3	None	49

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 75829 Gene records in batches of 10000

→ starting creation of 57510 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	gamma-delta T lymphocyte|gamma-delta T-lymphoc...	A T Cell That Expresses A Gamma-Delta T Cell R...	False	2026-01-11 16:51:14.426000+00:00	1	1	3	None	49
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-11 16:51:14.426000+00:00	1	1	3	None	49

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=49, created_at=2026-01-11 16:51:14 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='gamma-delta T lymphocyte|gamma-delta T-lymphocyte|gammadelta T cell|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=49, created_at=2026-01-11 16:51:14 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-11 16:51:14.316000+00:00	1	1	3	None	49

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
2928	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-11 16:51:14.903000+00:00	1	1	3	None	49
1465	26icgrTr4Nb1i3	gamma-delta thymocyte	CL:0002405	None	gammadelta thymocyte|gd thymocyte	A Post-Natal Thymocyte Expressing Components O...	False	2026-01-11 16:51:14.545000+00:00	1	1	3	None	49
782	3W6NKGpWdMLuOn	mature gamma-delta T cell	CL:0000800	None	mature gamma-delta T lymphocyte|mature gamma-d...	A Gamma-Delta T Cell That Has A Mature Phenoty...	False	2026-01-11 16:51:14.426000+00:00	1	1	3	None	49
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-11 16:51:14.426000+00:00	1	1	3	None	49

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-11 16:51:14.512000+00:00	1	1	3	None	49
967	4Ilrnj9ULJe69Z	hematopoietic cell	CL:0000988	None	haemopoietic cell|haematopoietic cell|hemopoie...	A Cell Of A Hematopoietic Lineage.	False	2026-01-11 16:51:14.458000+00:00	1	1	3	None	49
822	2Jgr5Xx4RSJlVB	mononuclear leukocyte	CL:0000842	None	mononuclear cell	A Leukocyte With A Single Non-Segmented Nucleu...	False	2026-01-11 16:51:14.437000+00:00	1	1	3	None	49
721	3VEAlFdi0Fh4OT	leukocyte	CL:0000738	None	leucocyte|white blood cell	An Achromatic Cell Of The Myeloid Or Lymphoid ...	False	2026-01-11 16:51:14.416000+00:00	1	1	3	None	49
529	X6c7osZ5A24bW2	lymphocyte	CL:0000542	None	None	A Lymphocyte Is A Leukocyte Commonly Found In ...	False	2026-01-11 16:51:14.394000+00:00	1	1	3	None	49
250	4WnpvUTHNi32Fp	eukaryotic cell	CL:0000255	None	None	Any Cell That In Taxon Some Eukaryota.	False	2026-01-11 16:51:14.338000+00:00	1	1	3	None	49
221	2cXC7cgFM5zNgH	single nucleate cell	CL:0000226	None	None	A Cell With A Single Nucleus.	False	2026-01-11 16:51:14.338000+00:00	1	1	3	None	49
214	2K93w3xOD2sghG	motile cell	CL:0000219	None	None	A Cell That Moves By Its Own Activities.	False	2026-01-11 16:51:14.338000+00:00	1	1	3	None	49
83	22LvKd01YyNA1a	T cell	CL:0000084	None	T lymphocyte|T-lymphocyte|T-cell	A Type Of Lymphocyte Whose Defining Characteri...	False	2026-01-11 16:51:14.316000+00:00	1	1	3	None	49
1	4bKGljt0Rpixy0	cell	CL:0000000	None	None	A Material Entity Of Anatomical Origin (Part O...	False	2026-01-11 16:51:14.305000+00:00	1	1	3	None	49

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
2928	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-11 16:51:14.903000+00:00	1	1	3	None	49
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-11 16:51:14.556000+00:00	1	1	3	None	49
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-11 16:51:14.556000+00:00	1	1	3	None	49
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-11 16:51:14.545000+00:00	1	1	3	None	49
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-11 16:51:14.545000+00:00	1	1	3	None	49
1474	5pDjyjfFx2qcX8	immature Vgamma1.1-positive, Vdelta6.3-negativ...	CL:0002414	None	None	A Vgamma1.1-Positive, Vdelta6.3-Negative Thymo...	False	2026-01-11 16:51:14.545000+00:00	1	1	3	None	49
1473	4cYNDr25MbvIM8	mature Vgamma1.1-positive, Vdelta6.3-negative ...	CL:0002413	None	None	A Vgamma1.1-Positive, Vdelta6.3-Negative Thymo...	False	2026-01-11 16:51:14.545000+00:00	1	1	3	None	49
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-11 16:51:14.545000+00:00	1	1	3	None	49
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-11 16:51:14.545000+00:00	1	1	3	None	49
1469	6RBJq86bxJmQam	mature Vgamma2-negative thymocyte	CL:0002409	None	Vgamma2-negative	A Thymocyte That Has A T Cell Receptor Consist...	False	2026-01-11 16:51:14.545000+00:00	1	1	3	None	49
1468	3ABJ1l1OfMZer3	immature Vgamma2-negative thymocyte	CL:0002408	None	None	A Double Negative Post-Natal Thymocyte That Ha...	False	2026-01-11 16:51:14.545000+00:00	1	1	3	None	49
1467	76CEFg3AEDmvSZ	mature Vgamma2-positive thymocyte	CL:0002407	None	Vgamma2-positive	A Thymocyte That Has A T Cell Receptor Consist...	False	2026-01-11 16:51:14.545000+00:00	1	1	3	None	49
1466	4hrSce5T2s8hii	immature Vgamma2-positive thymocyte	CL:0002406	None	None	A Double Negative Post-Natal Thymocyte That Ha...	False	2026-01-11 16:51:14.545000+00:00	1	1	3	None	49
1465	26icgrTr4Nb1i3	gamma-delta thymocyte	CL:0002405	None	gammadelta thymocyte|gd thymocyte	A Post-Natal Thymocyte Expressing Components O...	False	2026-01-11 16:51:14.545000+00:00	1	1	3	None	49
1191	3efemme8yo4Gfv	CD25-positive, CD27-positive immature gamma-de...	CL:0002126	None	None	A Cd25-Positive, Cd27-Positive Immature Gamma-...	False	2026-01-11 16:51:14.502000+00:00	1	1	3	None	49
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-11 16:51:14.502000+00:00	1	1	3	None	49
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-11 16:51:14.502000+00:00	1	1	3	None	49
895	1tYOPZxHGFlbLS	dendritic epidermal T cell	CL:0000916	None	dendritic epidermal T lymphocyte|dendritic epi...	A Mature Gamma-Delta T Cell Located In The Epi...	False	2026-01-11 16:51:14.448000+00:00	1	1	3	None	49
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-11 16:51:14.426000+00:00	1	1	3	None	49
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-11 16:51:14.426000+00:00	1	1	3	None	49
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-11 16:51:14.426000+00:00	1	1	3	None	49
782	3W6NKGpWdMLuOn	mature gamma-delta T cell	CL:0000800	None	mature gamma-delta T lymphocyte|mature gamma-d...	A Gamma-Delta T Cell That Has A Mature Phenoty...	False	2026-01-11 16:51:14.426000+00:00	1	1	3	None	49
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-11 16:51:14.426000+00:00	1	1	3	None	49

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=49, created_at=2026-01-11 16:51:14 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=49, created_at=2026-01-11 16:51:14 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=49, created_at=2026-01-11 16:51:14 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=49, created_at=2026-01-11 16:51:14 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=49, created_at=2026-01-11 16:51:14 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=49, created_at=2026-01-11 16:51:14 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=49, created_at=2026-01-11 16:51:14 UTC, is_locked=False),
               CellType(uid='wdLgwUXoz5ZpWT', name='adipocyte', ontology_id='CL:0000136', abbr=None, synonyms='fat cell|adipose 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=49, created_at=2026-01-11 16:51:14 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=49, created_at=2026-01-11 16:51:14 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-11 16:52:02 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
66	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-11 16:51:09.823000+00:00	1	1	3	None	None
65	MJRqduf9	bionty.Ethnicity	human	hancestro	3.0	False	True	Human Ancestry Ontology	http://purl.obolibrary.org/obo/hancestro/relea...	None	https://github.com/EBISPOT/hancestro	False	2026-01-11 16:51:09.823000+00:00	1	1	3	None	None
64	10va5JSt	bionty.DevelopmentalStage	mouse	mmusdv	2024-05-28	False	True	Mouse Developmental Stages	https://github.com/obophenotype/developmental-...	None	https://github.com/obophenotype/developmental-...	False	2026-01-11 16:51:09.823000+00:00	1	1	3	None	None
63	1GbFkOdz	bionty.DevelopmentalStage	human	hsapdv	2024-05-28	False	True	Human Developmental Stages	https://github.com/obophenotype/developmental-...	None	https://github.com/obophenotype/developmental-...	False	2026-01-11 16:51:09.823000+00:00	1	1	3	None	None
61	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-11 16:51:09.823000+00:00	1	1	3	None	None
60	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-11 16:51:09.823000+00:00	1	1	3	None	None
58	7Ent3V2y	bionty.Pathway	all	go	2024-06-17	False	True	Gene Ontology	http://purl.obolibrary.org/obo/go/releases/202...	None	http://geneontology.org	False	2026-01-11 16:51:09.823000+00:00	1	1	3	None	None
56	48fBFLmn	bionty.Phenotype	human	hp	2024-04-26	False	True	Human Phenotype Ontology	https://github.com/obophenotype/human-phenotyp...	None	https://hpo.jax.org	False	2026-01-11 16:51:09.823000+00:00	1	1	3	None	None
55	6S4qkDx1	bionty.Phenotype	all	pato	2024-03-28	False	True	Phenotype And Trait Ontology	http://purl.obolibrary.org/obo/pato/releases/2...	None	https://github.com/pato-ontology/pato	False	2026-01-11 16:51:09.823000+00:00	1	1	3	None	None
54	1yS830MU	bionty.ExperimentalFactor	all	efo	3.78.0	False	True	The Experimental Factor Ontology	http://www.ebi.ac.uk/efo/releases/v3.78.0/efo.owl	None	https://bioportal.bioontology.org/ontologies/EFO	False	2026-01-11 16:51:09.823000+00:00	1	1	3	None	None
52	4kswnHVF	bionty.Disease	human	doid	2024-05-29	False	True	Human Disease Ontology	http://purl.obolibrary.org/obo/doid/releases/2...	None	https://disease-ontology.org	False	2026-01-11 16:51:09.823000+00:00	1	1	3	None	None
51	IGIkseWQ	bionty.Disease	all	mondo	2025-06-03	False	True	Mondo Disease Ontology	http://purl.obolibrary.org/obo/mondo/releases/...	None	https://mondo.monarchinitiative.org	False	2026-01-11 16:51:09.823000+00:00	1	1	3	None	None
50	4U5uYTlc	bionty.Tissue	all	uberon	2025-05-28	False	True	Uberon multi-species anatomy ontology	http://purl.obolibrary.org/obo/uberon/releases...	None	http://obophenotype.github.io/uberon	False	2026-01-11 16:51:09.823000+00:00	1	1	3	None	None
49	3T9KZcjQ	bionty.CellType	all	cl	2025-04-10	True	True	Cell Ontology	http://purl.obolibrary.org/obo/cl/releases/202...	None	https://obophenotype.github.io/cell-ontology	False	2026-01-11 16:51:09.823000+00:00	1	1	3	None	None
47	6LyRtvz8	bionty.CellLine	all	clo	2022-03-21	False	True	Cell Line Ontology	s3://bionty-assets/df_all__clo__2022-03-21__Ce...	None	https://bioportal.bioontology.org/ontologies/CLO	False	2026-01-11 16:51:09.823000+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-11 16:51:09.823000+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-11 16:51:09.823000+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-11 16:51:09.823000+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-11 16:51:09.823000+00:00	1	1	3	None	None
42	4RPA3Re0	bionty.Gene	saccharomyces cerevisiae	ensembl	release-112	False	True	Ensembl	s3://bionty-assets/df_saccharomyces cerevisiae...	None	https://www.ensembl.org	False	2026-01-11 16:51:09.823000+00:00	1	1	3	None	None
41	4r4fvV0S	bionty.Gene	mouse	ensembl	release-112	True	True	Ensembl	s3://bionty-assets/df_mouse__ensembl__release-...	None	https://www.ensembl.org	False	2026-01-11 16:51:09.823000+00:00	1	1	3	None	None
40	4UGNz3fr	bionty.Gene	human	ensembl	release-112	True	True	Ensembl	s3://bionty-assets/df_human__ensembl__release-...	None	https://www.ensembl.org	False	2026-01-11 16:51:09.823000+00:00	1	1	3	None	None
39	4tsksCMX	bionty.Organism	all	ncbitaxon	2023-06-20	False	True	NCBItaxon Ontology	http://purl.obolibrary.org/obo/ncbitaxon/2023-...	None	https://github.com/obophenotype/ncbitaxon	False	2026-01-11 16:51:09.823000+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-11 16:51:09.823000+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-11 16:51:09.823000+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-11 16:51:09.823000+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-11 16:51:09.823000+00:00	1	1	3	None	None
34	33TUF039	bionty.Organism	vertebrates	ensembl	release-112	False	True	Ensembl	https://ftp.ensembl.org/pub/release-112/specie...	None	https://www.ensembl.org	False	2026-01-11 16:51:09.823000+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='3T9KZcjQ', entity='bionty.CellType', organism='all', name='cl', version='2025-04-10', in_db=True, currently_used=True, description='Cell Ontology', url='http://purl.obolibrary.org/obo/cl/releases/2025-04-10/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-11 16:51:09 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
56	48fBFLmn	bionty.Phenotype	human	hp	2024-04-26	False	True	Human Phenotype Ontology	https://github.com/obophenotype/human-phenotyp...	None	https://hpo.jax.org	False	2026-01-11 16:51:09.823000+00:00	1	1	3	None	None
55	6S4qkDx1	bionty.Phenotype	all	pato	2024-03-28	False	True	Phenotype And Trait Ontology	http://purl.obolibrary.org/obo/pato/releases/2...	None	https://github.com/pato-ontology/pato	False	2026-01-11 16:51:09.823000+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='4tsksCMX', entity='bionty.Organism', organism='all', name='ncbitaxon', version='2023-06-20', in_db=False, currently_used=True, description='NCBItaxon Ontology', url='http://purl.obolibrary.org/obo/ncbitaxon/2023-06-20/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-11 16:51:09 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)