{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "# How to traverse to GO children and descendants\n",
        "\n",
        "Traverse immediate children or all descendants with or without user-specified optional relationships\n",
        "\n",
        "\n",
        "  * **Children and Descendants described**\n",
        "  * **Code to get Children and Descendants**\n",
        "    * **Get children through *is_a* relationship**\n",
        "    * **Get children through *is_a* relationship and optional relationship, *part_of*.**\n",
        "    * **Get descendants through *is_a* relationship**\n",
        "    * **Get descendants through *is_a* relationship and optional relationship, *part_of*.**"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Children and Descendants\n",
        "\n",
        "### Children\n",
        "\n",
        "Children are terms directly below a GO term\n",
        "\n",
        "### Descendants\n",
        "\n",
        "Descendants are all terms below a GO term in the hierarchy"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "import os\n",
        "from goatools.obo_parser import GODag\n",
        "\n",
        "# Load a small test GO DAG and all the optional relationships,\n",
        "# like 'regulates' and 'part_of'\n",
        "godag = GODag('../tests/data/heartjogging.obo',\n",
        "              optional_attrs={'relationship'})"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "#### Get children through *is_a* relationship\n",
        "\n",
        "Direct children through is_a relationship only"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "GO_ID = 'GO:0003143'  # embryonic heart tube morphogenesis\n",
        "goterm = godag[GO_ID]\n",
        "\n",
        "# Get direct children through is_a\n",
        "children_isa = [child.item_id for child in goterm.children]\n",
        "print('{GO} children (is_a): {C}'.format(\n",
        "    GO=GO_ID,\n",
        "    C=children_isa))"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "#### Get children through *is_a* relationship and optional relationship, *part_of*\n",
        "\n",
        "Direct children through is_a and part_of relationships"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "from goatools.godag.go_tasks import get_go2children\n",
        "\n",
        "optional_relationships = {\"part_of\"}\n",
        "# Note: GODag inherits from dict, so we pass godag directly\n",
        "go2children_partof = get_go2children(godag, optional_relationships)\n",
        "print(\"{GO} children (is_a + part_of): {C}\".format(\n",
        "    GO=GO_ID,\n",
        "    C=go2children_partof.get(GO_ID, set())))"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "#### Get descendants through *is_a* relationship\n",
        "\n",
        "All descendants through is_a only"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "# Using GOTerm method\n",
        "descendants_isa = goterm.get_all_children()\n",
        "print('{GO} descendants (is_a): {D}'.format(\n",
        "    GO=GO_ID,\n",
        "    D=sorted(descendants_isa)))"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "#### Get descendants through *is_a* relationship and optional relationship, *part_of*\n",
        "\n",
        "All descendants through is_a and part_of relationships"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "from goatools.godag.go_tasks import get_go2descendants\n",
        "\n",
        "go2descendants_partof = get_go2descendants(godag.values(), optional_relationships)\n",
        "print('{GO} descendants (is_a + part_of): {D}'.format(\n",
        "    GO=GO_ID,\n",
        "    D=sorted(go2descendants_partof.get(GO_ID, set()))))"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "#### Alternative: Use GOTerm.get_all_lower() for all relationships\n",
        "\n",
        "This method automatically includes all relationship types"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "# Get all descendants through is_a and ALL relationships\n",
        "all_lower = goterm.get_all_lower()\n",
        "print('{GO} descendants (is_a + all relationships): {D}'.format(\n",
        "    GO=GO_ID,\n",
        "    D=sorted(all_lower)))\n",
        "\n",
        "# Show the additional descendants found through relationships\n",
        "additional = all_lower - descendants_isa\n",
        "if additional:\n",
        "    print(\"\\nAdditional descendants through relationships:\")\n",
        "    for goid in sorted(additional):\n",
        "        desc_term = godag[goid]\n",
        "        print(f\"  {goid}: {desc_term.name}\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Summary\n",
        "\n",
        "To get descendants with relationships in GOAtools:\n",
        "\n",
        "1. **Load GO DAG with relationships**: Use `optional_attrs={'relationship'}` when loading\n",
        "2. **For a single GO term**:\n",
        "   - `goterm.get_all_children()` - descendants through is_a only\n",
        "   - `goterm.get_all_lower()` - descendants through is_a + all relationships\n",
        "3. **For multiple GO terms (batch processing)**:\n",
        "   - `get_go2descendants(godag.values(), relationships=None)` - is_a only\n",
        "   - `get_go2descendants(godag.values(), relationships=True)` - is_a + all relationships\n",
        "   - `get_go2descendants(godag.values(), relationships={'part_of'})` - is_a + selected relationships\n",
        "4. **For hierarchy visualization**: Use `wr_hier.py -r` command-line tool"
      ]
    }
  ],
  "metadata": {
    "kernelspec": {
      "display_name": "Python 3",
      "language": "python",
      "name": "python3"
    },
    "language_info": {
      "name": "python",
      "version": "3.x"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 4
}