GOTerm Object
=============

A ``PyGOTerm`` represents one term in the loaded Gene Ontology.

Main fields
-----------

.. list-table::
   :header-rows: 1

   * - Field
     - Type
     - Description
   * - ``id``
     - ``str``
     - GO identifier (for example ``GO:0006397``)
   * - ``name``
     - ``str``
     - Human-readable label
   * - ``namespace``
     - ``str``
     - One of ``biological_process``, ``molecular_function``, ``cellular_component``
   * - ``definition``
     - ``str``
     - GO definition text
   * - ``parents``
     - ``list[str]``
     - Immediate ``is_a`` parents
   * - ``children``
     - ``list[str]``
     - Immediate ``is_a`` children
   * - ``depth``
     - ``int | None``
     - Maximum distance to root (longest path through the DAG)
   * - ``level``
     - ``int | None``
     - Minimum distance to root (shortest path through the DAG)
   * - ``is_obsolete``
     - ``bool``
     - Obsolescence flag
   * - ``alt_ids``
     - ``list[str]``
     - Alternate GO IDs
   * - ``replaced_by``
     - ``str | None``
     - Suggested canonical replacement for obsolete terms
   * - ``consider``
     - ``list[str]``
     - Alternative replacements
   * - ``synonyms``
     - ``list[str]``
     - Synonym strings
   * - ``xrefs``
     - ``list[str]``
     - Cross-references
   * - ``relationships``
     - ``list[tuple[str, str]]``
     - Additional relationships beyond ``is_a`` (for example ``("part_of", "GO:0006396")``)
   * - ``comment``
     - ``str | None``
     - GO comment field

Field notes
-----------

**depth vs. level**: Because GO is a DAG (not a tree), a term can have multiple paths to the root. ``depth`` is the *longest* such path and ``level`` is the *shortest*. See :doc:`ontology` for details.

**relationships**: This field contains non-``is_a`` relationships as ``(type, target_id)`` tuples -- for example ``part_of``, ``regulates``, ``has_part``. The ``parents`` and ``children`` fields only reflect ``is_a`` edges.

**None and empty values**: ``depth`` and ``level`` can be ``None`` for the root terms or if the OBO file does not provide them. ``replaced_by`` and ``comment`` are ``None`` when not present in the OBO entry. List fields (``parents``, ``children``, ``alt_ids``, ``consider``, ``synonyms``, ``xrefs``, ``relationships``) are empty lists when no values exist.

Example
-------

.. code-block:: python

   import go3

   go3.load_go_terms("go-basic.obo")
   term = go3.get_term_by_id("GO:0006397")

   print(term.id)          # "GO:0006397"
   print(term.name)        # "mRNA processing"
   print(term.namespace)   # "biological_process"
   print(term.depth)       # e.g. 7
   print(term.level)       # e.g. 5
   print(term.parents)     # list of is_a parent GO IDs
   print(term.relationships)  # e.g. [("part_of", "GO:0006396")]

Inspecting an obsolete term
----------------------------

.. code-block:: python

   import go3

   go3.load_go_terms("go-basic.obo")

   # Obsolete terms are loaded but flagged
   term = go3.get_term_by_id("GO:0005765")  # example; check your OBO for valid obsolete IDs
   print(term.is_obsolete)   # True
   print(term.replaced_by)   # replacement GO ID, or None
   print(term.consider)      # list of alternative GO IDs to consider

API reference
-------------

.. autoclass:: go3.PyGOTerm
   :members:
   :undoc-members:
   :show-inheritance: