bionty.models ¶

Models library.

class bionty.models.BioRecord(*args, **kwargs)¶

Base SQLRecord of bionty.

BioRecord inherits all methods from SQLRecord and CanCurate().

Notes

For more info, see tutorials:

uid: str¶: A universal id (base62-encoded hash of defining fields).

abbr: str | None¶: A unique abbreviation, maximum length 32 characters.

synonyms: str | None¶: Bar-separated (|) synonyms of this biorecord.

description: str | None¶: Description of the biorecord.

classmethod require_organism(field=None)¶

Check if the registry has an organism field and is required.

Return type:: bool
Returns:: True if the registry has an organism field and is required, False otherwise.

save(*args, **kwargs)¶

Save the record and its parents recursively.

Example:

import bionty as bt

record = bt.CellType.from_source(name="T cell")
record.save()

Return type:: BioRecord

class bionty.models.HasOntologyId(*args, **kwargs)¶

HasOntologyId - base class for standard ontologies.

This class is inherited by all standard ontology registries in bionty. It provides common fields name, ontology_id, and parents.

parents: HasOntologyId¶: Parent records.

class bionty.models.HasSource(*args, **kwargs)¶

HasSource - base class for records with a source foreign key.

Provides public() and from_source().

source_id¶

source: Source¶: Source this record associates with.

classmethod import_source(source=None, update_records=False, *, organism=None, ignore_conflicts=True)¶

Bulk save records from a Bionty ontology.

Use this method to initialize your registry with public ontology.

Parameters:

source (Source | None, default: None) – Source record to import records from.
update_records (bool, default: False) –
If True, update existing records with the new source.
- If a record has the same metadata in the new source, link the record to the new source.
- If a record has no artifacts associated, update it’s metadata and link to the new source.
- If a record associated artifacts, but different name in the new source, create a new record with the new source.
organism (str | SQLRecord | None, default: None) – Organism name or record. Required for entities with a required organism foreign key when no source is passed.
ignore_conflicts (bool, default: True) – Whether to ignore conflicts during bulk record creation.

Examples:

import bionty as bt

# import all records from a default source
default_sources = bt.Source.filter(entity="bionty.CellType", currently_used=True).to_dataframe()
bt.CellType.import_source()

# import all records from a specific source
source = bt.Source.get(entity="bionty.CellType", source="cl", version="2022-08-16")
bt.CellType.import_source(source)
bt.CellType.to_dataframe()  # all records from the source are now in the registry

# update existing records with a new source (version update)
source = bt.Source.get(entity="bionty.CellType", source="cl", version="2024-08-16")
bt.CellType.import_source(source, update_records=True)

classmethod add_source(source, *, df=None, version=None, organism=None)¶

Link a source record to the entity with a reference DataFrame.

Creates or retrieves a Source record for the entity and optionally associates it with a DataFrame artifact containing the ontology data. If the source already exists with a DataFrame artifact, returns the existing source.

Parameters:

source (Source | PublicOntology | str) –
Source specification. Can be:
- Source record: Existing bionty.Source instance
- PublicOntology: PublicOntology object with source metadata
- str: Source name (e.g., “mondo”, “cl”, “go”)
df (DataFrame | None, default: None) – Optional DataFrame containing ontology data to store as Artifact. If None and source is a PublicOntology, uses the ontology’s DataFrame.
version (str | None, default: None) – Source version string. Required when source is str and no existing source found. Examples: “2025-06-03”, “v1.0”, “release-112”
organism (str | None, default: None) – Organism identifier. Required for organism-specific entities when source is str. Use “all” for cross-organism ontologies.

Return type:

Source

Examples

Add a source by name with version and organism:

import bionty as bt
source = bt.Disease.add_source("mondo", version="2025-06-03", organism="all")

Add a source to an entity with a custom DataFrame:

import pandas as pd
df = pd.DataFrame({"name": ["disease1"], "ontology_id": ["MONDO:123"]})
source = bt.Source(
    entity="bionty.Disease",
    name="new mondo",
    version="99.999",
    organism="human",
)
source = bt.Disease.add_source(source=source, df=df)

Add from existing PublicOntology:

pub_ont = bt.Disease.public()
source = bt.Disease.add_source(pub_ont)

Add organism-specific source:

source = bt.Gene.add_source("ensembl", version="release-112", organism="human")

classmethod public(organism=None, source=None)¶

The corresponding bionty.base.PublicOntology object.

Note that the source is auto-configured and tracked via bionty.Source.

Parameters:

organism (str | SQLRecord | None, default: None) – Organism name or record to filter by
source (Source | None, default: None) – Source record to use instead of default

Return type:

PublicOntology | StaticReference