API Reference

biokb_taxtree.db.models

Database models for the biokb_taxtree application.

Defines the SQLAlchemy ORM models representing the database schema for taxonomy tree data.

`Class_`

Bases: Base

Model representing class.

Attributes:

Name	Type	Description
`id`	`int`	Primary key, ID of the class.
`name`	`str`	Name of the class.

Source code in src/biokb_taxtree/db/models.py

class Class_(Base):
    """Model representing class.

    Attributes:
        id (int): Primary key, ID of the class.
        name (str): Name of the class.
    """

    __tablename__ = Base._prefix + "class_"

    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
    name: Mapped[str] = mapped_column(
        String(255), nullable=False, comment="Name of the class", index=True
    )
    # relationships
    ranked_lineages: Mapped[list[RankedLineage]] = relationship(back_populates="class_")

`Domain`

Bases: Base

Model representing domain.

Attributes:

Name	Type	Description
`id`	`int`	Primary key, ID of the domain.
`name`	`str`	Name of the domain.

Source code in src/biokb_taxtree/db/models.py

class Domain(Base):
    """Model representing domain.

    Attributes:
        id (int): Primary key, ID of the domain.
        name (str): Name of the domain.
    """

    __tablename__ = Base._prefix + "domain"

    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
    name: Mapped[str] = mapped_column(
        String(255), nullable=False, comment="Name of the domain", index=True
    )
    # relationships
    ranked_lineages: Mapped[list[RankedLineage]] = relationship(back_populates="domain")

`Family`

Bases: Base

Model representing family.

Attributes:

Name	Type	Description
`id`	`int`	Primary key, ID of the family.
`name`	`str`	Name of the family.

Source code in src/biokb_taxtree/db/models.py

class Family(Base):
    """Model representing family.

    Attributes:
        id (int): Primary key, ID of the family.
        name (str): Name of the family.
    """

    __tablename__ = Base._prefix + "family"

    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
    name: Mapped[str] = mapped_column(
        String(255), nullable=False, comment="Name of the family", index=True
    )
    # relationships
    ranked_lineages: Mapped[list[RankedLineage]] = relationship(back_populates="family")

`Genus`

Bases: Base

Model representing genus.

Attributes:

Name	Type	Description
`id`	`int`	Primary key, ID of the genus.
`name`	`str`	Name of the genus.

Source code in src/biokb_taxtree/db/models.py

class Genus(Base):
    """Model representing genus.

    Attributes:
        id (int): Primary key, ID of the genus.
        name (str): Name of the genus.
    """

    __tablename__ = Base._prefix + "genus"

    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
    name: Mapped[str] = mapped_column(
        String(255), nullable=False, comment="Name of the genus", index=True
    )
    # relationships
    ranked_lineages: Mapped[list[RankedLineage]] = relationship(back_populates="genus")

`Kingdom`

Bases: Base

Model representing kingdom.

Attributes:

Name	Type	Description
`id`	`int`	Primary key, ID of the kingdom.
`name`	`str`	Name of the kingdom.

Source code in src/biokb_taxtree/db/models.py

class Kingdom(Base):
    """Model representing kingdom.

    Attributes:
        id (int): Primary key, ID of the kingdom.
        name (str): Name of the kingdom.
    """

    __tablename__ = Base._prefix + "kingdom"

    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
    name: Mapped[str] = mapped_column(
        String(255), nullable=False, comment="Name of the kingdom", index=True
    )
    # relationships
    ranked_lineages: Mapped[list[RankedLineage]] = relationship(
        back_populates="kingdom"
    )

`Name`

Bases: Base

Model representing a name associated with a taxonomy node.

Attributes:

Name	Type	Description
`id`	`int`	Primary key.
`name_txt`	`str`	Text of the name.
`unique_name`	`Optional[str]`	Unique variant of this name if not unique.
`name_class`	`str`	Class of the name (e.g., synonym, common name).
`tax_id`	`int`	Foreign key to the associated Node.
`node`	`Node`	Relationship to the associated Node.

Source code in src/biokb_taxtree/db/models.py

class Name(Base):
    """Model representing a name associated with a taxonomy node.

    Attributes:
        id (int): Primary key.
        name_txt (str): Text of the name.
        unique_name (Optional[str]): Unique variant of this name if not unique.
        name_class (str): Class of the name (e.g., synonym, common name).
        tax_id (int): Foreign key to the associated Node.
        node (Node): Relationship to the associated Node.
    """

    __tablename__ = Base._prefix + "name"

    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)

    name_txt: Mapped[str] = mapped_column(
        String(500),
        index=True,
        nullable=False,
        comment="Organism name text (e.g., Escherichia coli, E. coli, etc.)",
    )
    unique_name: Mapped[str | None] = mapped_column(
        String(255), nullable=True, comment="Unique variant of this name if not unique"
    )
    name_class: Mapped[NameClassEnum] = mapped_column(
        Enum(
            NameClassEnum,
            native_enum=False,
            values_callable=lambda x: [e.value for e in x],
        ),
        nullable=False,
        index=True,
        comment="Class of the name (e.g., synonym, common name)",
    )

    # foreign keys
    tax_id: Mapped[int] = mapped_column(
        ForeignKey(Base._prefix + "node.tax_id"), nullable=False
    )
    # relationships
    node: Mapped[Node] = relationship(back_populates="names")

    @property
    def rank(self) -> Optional[str]:
        """Get the taxonomic rank of this name based on its associated node."""
        return self.node.rank if self.node else None

    def __repr__(self) -> str:
        return (
            f"<{self.__class__.__name__} ("
            f"name_txt={self.name_txt}, "
            f"unique_name={self.unique_name}, "
            f"name_class={self.name_class}, "
            f"tax_id={self.tax_id})>"
        )

`rank` `property`

Get the taxonomic rank of this name based on its associated node.

`Node`

Bases: Base

Model representing a taxonomy node in the GenBank taxonomy database.

Attributes:

Name	Type	Description
`tax_id`	`int`	Node ID in GenBank taxonomy database (primary key).
`parent_tax_id`	`int`	Parent node ID in GenBank taxonomy database.
`rank`	`str`	Rank of this node (e.g., superkingdom, kingdom).
`embl_code`	`Optional[str]`	Locus-name prefix; not unique.
`division_id`	`int`	Taxonomy database division ID.
`inherited_div_flag`	`bool`	1 if node inherits division from parent.
`genetic_code_id`	`int`	GenBank genetic code ID.
`inherited_gc_flag`	`bool`	1 if node inherits genetic code from parent.
`mitochondrial_genetic_code_id`	`int`	GenBank mitochondrial genetic code ID.
`inherited_mgc_flag`	`bool`	1 if node inherits mitochondrial gencode from parent.
`genbank_hidden_flag`	`bool`	1 if name is suppressed in GenBank entry lineage.
`hidden_subtree_root_flag`	`bool`	1 if this subtree has no sequence data yet.
`comments`	`Optional[str]`	Free-text comments and citations.
`plastid_genetic_code_id`	`Optional[int]`	GenBank plastid genetic code ID.
`inherited_pgc_flag`	`Optional[bool]`	1 if node inherits plastid gencode from parent.
`specified_species`	`Optional[bool]`	1 if species in the node's lineage has formal name.
`hydrogenosome_genetic_code_id`	`Optional[int]`	GenBank hydrogenosome genetic code ID.
`inherited_hgc_flag`	`Optional[bool]`	1 if node inherits hydrogenosome gencode from parent.
`tree_id`	`int`	Sorted tree ID.
`tree_parent_id`	`Optional[int]`	Sorted tree parent ID.
`level`	`int`	Level in the tree.
`right_tree_id`	`int`	Right tree ID.
`is_leaf`	`bool`	Is leaf (has no children).
`names`	`List[Name]`	Relationship to associated names.
`ranked_lineage`	`RankedLineage`	Relationship to associated ranked lineage.

Source code in src/biokb_taxtree/db/models.py

class Node(Base):
    """Model representing a taxonomy node in the GenBank taxonomy database.


    Attributes:
        tax_id (int): Node ID in GenBank taxonomy database (primary key).
        parent_tax_id (int): Parent node ID in GenBank taxonomy database.
        rank (str): Rank of this node (e.g., superkingdom, kingdom).
        embl_code (Optional[str]): Locus-name prefix; not unique.
        division_id (int): Taxonomy database division ID.
        inherited_div_flag (bool): 1 if node inherits division from parent.
        genetic_code_id (int): GenBank genetic code ID.
        inherited_gc_flag (bool): 1 if node inherits genetic code from parent.
        mitochondrial_genetic_code_id (int): GenBank mitochondrial genetic code ID.
        inherited_mgc_flag (bool): 1 if node inherits mitochondrial gencode from parent.
        genbank_hidden_flag (bool): 1 if name is suppressed in GenBank entry lineage.
        hidden_subtree_root_flag (bool): 1 if this subtree has no sequence data yet.
        comments (Optional[str]): Free-text comments and citations.
        plastid_genetic_code_id (Optional[int]): GenBank plastid genetic code ID.
        inherited_pgc_flag (Optional[bool]): 1 if node inherits plastid gencode from parent.
        specified_species (Optional[bool]): 1 if species in the node's lineage has formal name.
        hydrogenosome_genetic_code_id (Optional[int]): GenBank hydrogenosome genetic code ID.
        inherited_hgc_flag (Optional[bool]): 1 if node inherits hydrogenosome gencode from parent.
        tree_id (int): Sorted tree ID.
        tree_parent_id (Optional[int]): Sorted tree parent ID.
        level (int): Level in the tree.
        right_tree_id (int): Right tree ID.
        is_leaf (bool): Is leaf (has no children).
        names (List[Name]): Relationship to associated names.
        ranked_lineage (RankedLineage): Relationship to associated ranked lineage."""

    __tablename__ = Base._prefix + "node"

    tax_id: Mapped[int] = mapped_column(
        primary_key=True, comment="node id in GenBank taxonomy database", unique=True
    )
    parent_tax_id: Mapped[int] = mapped_column(
        comment=" parent node id in GenBank taxonomy database", index=True
    )
    rank: Mapped[str] = mapped_column(
        String(20), comment="rank of this node (superkingdom, kingdom, ...) "
    )
    embl_code: Mapped[Optional[str]] = mapped_column(
        String(2), comment="locus-name prefix; not unique"
    )
    division_id: Mapped[int] = mapped_column(comment="taxonomy database division id")
    inherited_div_flag: Mapped[bool] = mapped_column(
        comment="1 if node inherits division from parent"
    )
    genetic_code_id: Mapped[int] = mapped_column(comment="GenBank genetic code id")
    inherited_gc_flag: Mapped[bool] = mapped_column(
        comment="1 if node inherits genetic code from parent"
    )
    mitochondrial_genetic_code_id: Mapped[int] = mapped_column(
        comment="GenBank genetic code id"
    )
    inherited_mgc_flag: Mapped[bool] = mapped_column(
        comment="1 if node inherits mitochondrial gencode from parent"
    )
    genbank_hidden_flag: Mapped[bool] = mapped_column(
        comment="1 if name is suppressed in GenBank entry lineage"
    )
    hidden_subtree_root_flag: Mapped[bool] = mapped_column(
        comment="1 if this subtree has no sequence data yet"
    )
    comments: Mapped[Optional[str]] = mapped_column(
        Text, comment="free-text comments and citations"
    )
    plastid_genetic_code_id: Mapped[Optional[int]] = mapped_column(
        comment="GenBank genetic code id"
    )
    inherited_pgc_flag: Mapped[Optional[bool]] = mapped_column(
        comment="1 if node inherits plastid gencode from parent"
    )
    specified_species: Mapped[Optional[bool]] = mapped_column(
        comment="1 if species in the node's lineage has formal name"
    )
    hydrogenosome_genetic_code_id: Mapped[Optional[int]] = mapped_column(
        comment="GenBank genetic code id"
    )
    inherited_hgc_flag: Mapped[Optional[bool]] = mapped_column(
        comment="1 if node inherits hydrogenosome gencode from parent"
    )
    tree_id: Mapped[int] = mapped_column(comment="Sorted tree ID", index=True)
    tree_parent_id: Mapped[Optional[int]] = mapped_column(
        comment="Sorted tree ID", index=True
    )
    level: Mapped[int] = mapped_column(comment="Level in the tree")
    right_tree_id: Mapped[int] = mapped_column(comment="Level in the tree", index=True)
    is_leaf: Mapped[bool] = mapped_column(
        comment="Is leaf (has no children)", index=True
    )

    # relationships
    names: Mapped[list["Name"]] = relationship(back_populates="node")
    ranked_lineage: Mapped["RankedLineage"] = relationship(back_populates="node")

    def __repr__(self) -> str:
        return (
            f"<{self.__class__.__name__} ("
            f"tax_id={self.tax_id}, "
            f"parent_tax_id={self.parent_tax_id}, "
            f"names= {[x.name_txt for x in self.names]})>"
        )

`Order`

Bases: Base

Model representing order.

Attributes:

Name	Type	Description
`id`	`int`	Primary key, ID of the order.
`name`	`str`	Name of the order.

Source code in src/biokb_taxtree/db/models.py

class Order(Base):
    """Model representing order.

    Attributes:
        id (int): Primary key, ID of the order.
        name (str): Name of the order.
    """

    __tablename__ = Base._prefix + "order"

    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
    name: Mapped[str] = mapped_column(
        String(255), nullable=False, comment="Name of the order", index=True
    )
    # relationships
    ranked_lineages: Mapped[list[RankedLineage]] = relationship(back_populates="order")

`Phylum`

Bases: Base

Model representing phylum.

Attributes:

Name	Type	Description
`id`	`int`	Primary key, ID of the phylum.
`name`	`str`	Name of the phylum.

Source code in src/biokb_taxtree/db/models.py

class Phylum(Base):
    """Model representing phylum.

    Attributes:
        id (int): Primary key, ID of the phylum.
        name (str): Name of the phylum.
    """

    __tablename__ = Base._prefix + "phylum"

    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
    name: Mapped[str] = mapped_column(
        String(255), nullable=False, comment="Name of the phylum", index=True
    )
    # relationships
    ranked_lineages: Mapped[list[RankedLineage]] = relationship(back_populates="phylum")

`RankedLineage`

Bases: Base

Model representing the ranked lineage of a taxonomy node.

Attributes:

Name	Type	Description
`id`	`int`	Primary key.
`tax_name`	`str`	Scientific name of the organism.
`species`	`Optional[str]`	Name of a species (coincide with organism name for species-level nodes).
`genus`	`Optional[str]`	Genus name.
`family`	`Optional[str]`	Family name.
`order`	`Optional[str]`	Order name.
`class_`	`Optional[str]`	Class name.
`phylum`	`Optional[str]`	Phylum name.
`kingdom`	`Optional[str]`	Kingdom name.
`domain`	`Optional[str]`	Domain name.
`tax_id`	`int`	Foreign key to the associated Node.
`node`	`Node`	Relationship to the associated Node.

Source code in src/biokb_taxtree/db/models.py

class RankedLineage(Base):
    """Model representing the ranked lineage of a taxonomy node.

    Attributes:
        id (int): Primary key.
        tax_name (str): Scientific name of the organism.
        species (Optional[str]): Name of a species (coincide with organism name for species-level nodes).
        genus (Optional[str]): Genus name.
        family (Optional[str]): Family name.
        order (Optional[str]): Order name.
        class_ (Optional[str]): Class name.
        phylum (Optional[str]): Phylum name.
        kingdom (Optional[str]): Kingdom name.
        domain (Optional[str]): Domain name.
        tax_id (int): Foreign key to the associated Node.
        node (Node): Relationship to the associated Node.
    """

    __tablename__ = Base._prefix + "ranked_lineage"

    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)

    tax_name: Mapped[str] = mapped_column(
        String(255), comment="scientific name of the organism"
    )
    species: Mapped[Optional[str]] = mapped_column(
        String(255),
        comment="name of a species (coincide with organism name for species-level nodes)",
    )

    # foreign keys
    tax_id: Mapped[int] = mapped_column(
        ForeignKey(Base._prefix + "node.tax_id"),
        nullable=False,
        unique=True,
        comment="node id",
    )
    # many to one relationship
    node: Mapped[Node] = relationship(
        back_populates="ranked_lineage", single_parent=True
    )
    # foreign key relationships
    domain_id: Mapped[Optional[int]] = mapped_column(
        ForeignKey(Base._prefix + "domain.id"), nullable=True
    )
    domain: Mapped[Optional["Domain"]] = relationship(back_populates="ranked_lineages")
    kingdom_id: Mapped[Optional[int]] = mapped_column(
        ForeignKey(Base._prefix + "kingdom.id"), nullable=True
    )
    kingdom: Mapped[Optional["Kingdom"]] = relationship(
        back_populates="ranked_lineages",
    )
    phylum_id: Mapped[Optional[int]] = mapped_column(
        ForeignKey(Base._prefix + "phylum.id"), nullable=True
    )
    phylum: Mapped[Optional["Phylum"]] = relationship(
        back_populates="ranked_lineages",
    )
    class__id: Mapped[Optional[int]] = mapped_column(
        ForeignKey(Base._prefix + "class_.id"), nullable=True
    )
    class_: Mapped[Optional["Class_"]] = relationship(
        back_populates="ranked_lineages",
    )
    order_id: Mapped[Optional[int]] = mapped_column(
        ForeignKey(Base._prefix + "order.id"), nullable=True
    )
    order: Mapped[Optional["Order"]] = relationship(
        back_populates="ranked_lineages",
    )
    family_id: Mapped[Optional[int]] = mapped_column(
        ForeignKey(Base._prefix + "family.id"), nullable=True
    )
    family: Mapped[Optional["Family"]] = relationship(
        back_populates="ranked_lineages",
    )
    genus_id: Mapped[Optional[int]] = mapped_column(
        ForeignKey(Base._prefix + "genus.id"), nullable=True
    )
    genus: Mapped[Optional["Genus"]] = relationship(
        back_populates="ranked_lineages",
    )

    def __repr__(self) -> str:
        return (
            f"<{self.__class__.__name__} ("
            f"tax_name={self.tax_name}, "
            f"species={self.species}, "
            f"genus={self.genus.name if self.genus else None}, "
            f"family={self.family.name if self.family else None}, "
            f"order={self.order.name if self.order else None}, "
            f"class_={self.class_.name if self.class_ else None}, "
            f"phylum={self.phylum.name if self.phylum else None}, "
            f"kingdom={self.kingdom.name if self.kingdom else None}, "
            f"domain={self.domain.name if self.domain else None})>"
        )

API Reference

biokb_taxtree.db.models

Class_

Domain

Family

Genus

Kingdom

Name

rank property

Node

Order

Phylum

RankedLineage

`Class_`

`Domain`

`Family`

`Genus`

`Kingdom`

`Name`

`rank` `property`

`Node`

`Order`

`Phylum`

`RankedLineage`