## 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:

 * bionty

 * Manage biological ontologies

 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" |

 See also: Access public ontologies

 Example:

 import bionty as bt

 # default source
 celltype_pub = bt.CellType.public()
 celltype_pub
 #> PublicOntology
 #> Entity: CellType
 #> Organism: all
 #> Source: cl, 2023-04-20
 #> #terms: 2698

 # default source of a organism
 gene_pub = bt.Gene.public(organism="mouse")
 gene_pub
 #> PublicOntology
 #> Entity: Gene
 #> Organism: mouse
 #> Source: ensembl, release-112
 #> #terms: 57510

 classmethod from_source(string=None, *, mute=False, **kwargs)

 Create a record or records from source based on a single field
 value.

 Return type:
| "BioRecord" | "list"["BioRecord"] |

 -[ Notes ]-

 For more info, see tutorial bionty

 Bulk create records via "from_values()".

 Example:

 import bionty as bt

 # Create a record by passing a field value:
 record = bt.Gene.from_source(symbol="TCF7", organism="human")

 # Create a record by passing a synonym:
 record = bt.Gene.from_source("TCF-1", organism="human")

 # Create a record from non-default source:
 source = bt.Source.get(entity="CellType", source="cl", version="2022-08-16")
 record = bt.CellType.from_source(name="T cell", source=source)