notebooks/dkg_api.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "78a34c52",
   "metadata": {},
   "source": [
    "## Using the MIRA Domain Knowledge Graph REST API\n",
    "\n",
    "MIRA implements an approach to rapidly generate domain-specific knowledge graphs (DKGs) from primary sources such as available ontologies, in support of modeling. Though there can be different DKGs for different scientific domains in which modeling is performed, the technical APIs for DKGs are shared across domains.\n",
    "\n",
    "Below we demonstrate the MIRA DKG REST API on an epidemiology DKG that integrates about a dozen different relevant ontologies.\n",
    "\n",
    "### Node representation\n",
    "It is important to note that nodes in the DKG are labeled using compact URIs also known as CURIEs. For example, a node representing the Infectious Disease Ontology (IDO) entry 0000556 has the label ido:0000556. Here, the `ido` prefix comes from the standard prefix defined for IDO in the Bioregistry: https://bioregistry.io/registry/ido."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "4ea6a53f",
   "metadata": {},
   "outputs": [],
   "source": [
    "import requests"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c4893fb0",
   "metadata": {},
   "source": [
    "Below we refer to the URL of a public MIRA epidemiology DKG instance. The URL is subject to change later."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "id": "fe9aa159",
   "metadata": {},
   "outputs": [],
   "source": [
    "base = \"http://mira-epi-dkg-lb-dc1e19b273dedaa2.elb.us-east-1.amazonaws.com/api\"\n",
    "# base = \"http://localhost/api\"  # Local deployment"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2647b79b",
   "metadata": {},
   "source": [
    "### Export lexical information from the DKG\n",
    "There is a dedicated endpoint for exporting all lexical information (names, synonyms, descriptions) for each DKG node. This can be useful for systems that do information extraction from unstructured sources and attempt to do named entity recognition, normalization, and disambiguation."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "d09f4030",
   "metadata": {},
   "outputs": [],
   "source": [
    "res = requests.get(base + \"/lexical\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7a57e0a9",
   "metadata": {},
   "source": [
    "The result is a list of lists, where elements in each list include the CURIE label of the node, its standard name, its list of synonyms and its description."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "f5f74e0c",
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[{'id': 'wikidata:Q98642859',\n",
       "  'name': 'electronvolt square metre per kilogram',\n",
       "  'description': 'unit of total mass stopping power',\n",
       "  'synonyms': []},\n",
       " {'id': 'wikidata:Q98643033',\n",
       "  'name': 'joule square metre per kilogram',\n",
       "  'description': 'unit of total mass stopping power',\n",
       "  'synonyms': []},\n",
       " {'id': 'wikidata:Q98793302', 'name': 'quart (UK)', 'synonyms': []},\n",
       " {'id': 'wikidata:Q98793408', 'name': 'liquid quart (US)', 'synonyms': []},\n",
       " {'id': 'wikidata:Q98793687',\n",
       "  'name': 'dry quart (US)',\n",
       "  'description': 'unit of volume',\n",
       "  'synonyms': []}]"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "res.json()[20000:20005]"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ff030855",
   "metadata": {},
   "source": [
    "### Structured graph pattern queries in the DKG\n",
    "We next look at REST API queries to the DKG that return matches based on simple structural patterns in the graph."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "id": "86a13498",
   "metadata": {},
   "outputs": [],
   "source": [
    "def query(payload, **_payload):\n",
    "    payload.update(_payload)\n",
    "    res = requests.post(base + \"/relations\", json=payload)\n",
    "    return res.json()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6236ae78",
   "metadata": {},
   "source": [
    "#### Find relations with a given type of source node\n",
    "Example: Query for relations with Vaccine Ontology (vo) source nodes"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "d11f9422",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[{'subject': 'vo:0000000',\n",
       "  'predicate': 'rdfs:subClassOf',\n",
       "  'object': 'vo:0000420'},\n",
       " {'subject': 'vo:0000000',\n",
       "  'predicate': 'rdfs:subClassOf',\n",
       "  'object': 'vo:0000420'}]"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "query({\"source_type\": \"vo\", \"limit\": 2})"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "de638521",
   "metadata": {},
   "source": [
    "#### Find relations with a given type of target node\n",
    "Example: Query for relations with Symptom Ontology (symp) target nodes"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "44790cf1",
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[{'subject': 'doid:0060859',\n",
       "  'predicate': 'ro:0002452',\n",
       "  'object': 'symp:0000001'},\n",
       " {'subject': 'symp:0000375',\n",
       "  'predicate': 'rdfs:subClassOf',\n",
       "  'object': 'symp:0000001'}]"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "query({\"target_type\": \"symp\", \"limit\": 2})"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f4566952",
   "metadata": {},
   "source": [
    "#### Find relations between a given type of source node and target node\n",
    "Example: Query for relations from Disease Ontology (doid) to Symptom Ontology (symp) nodes"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "b7913616",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[{'subject': 'doid:0060859',\n",
       "  'predicate': 'ro:0002452',\n",
       "  'object': 'symp:0000001'},\n",
       " {'subject': 'doid:0060188',\n",
       "  'predicate': 'ro:0002452',\n",
       "  'object': 'symp:0000001'}]"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "query({\"source_type\": \"doid\", \"target_type\": \"symp\", \"limit\": 2})"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e8524ab6",
   "metadata": {},
   "source": [
    "#### Find relations with a specific source node\n",
    "Example: Query for relations whose start node is dientamoebiasis (doid:946)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "2c848331",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[{'subject': 'doid:946', 'predicate': 'ro:0002452', 'object': 'symp:0019177'},\n",
       " {'subject': 'doid:946', 'predicate': 'ro:0002452', 'object': 'symp:0000570'}]"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "query({\"source_curie\": \"doid:946\", \"limit\": 2})"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f1fb9f73",
   "metadata": {},
   "source": [
    "#### Find relations with a specific target node\n",
    "Example: Query for relations whose target node is diarrhea (symp:0000570)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "e1cae9dd",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[{'subject': 'symp:0020011',\n",
       "  'predicate': 'rdfs:subClassOf',\n",
       "  'object': 'symp:0000570'},\n",
       " {'subject': 'symp:0000738',\n",
       "  'predicate': 'rdfs:subClassOf',\n",
       "  'object': 'symp:0000570'}]"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "query({\"target_curie\": \"symp:0000570\", \"limit\": 2})"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6e44e143",
   "metadata": {},
   "source": [
    "#### Adding relation type constraints\n",
    "You can expand on the examples above to add not only source/target constraints but also constraints on the types of relations that are considered. For example, one can find relations that represent taxonomical subclasses using the `rdfs:subClassOf` relation type. "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9e12e9eb",
   "metadata": {},
   "source": [
    "Example: Query for subclass relations of a term in the Basic Formal Ontology (bfo:0000002)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "id": "190310a1",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[{'subject': 'bfo:0000002',\n",
       "  'predicate': 'rdfs:subClassOf',\n",
       "  'object': 'bfo:0000001'},\n",
       " {'subject': 'bfo:0000002',\n",
       "  'predicate': 'rdfs:subClassOf',\n",
       "  'object': 'bfo:0000001'}]"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "query({\"source_curie\": \"bfo:0000002\", \"relation\": \"rdfs:subClassOf\", \"limit\": 2})"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5ecfa9c2",
   "metadata": {},
   "source": [
    "#### Adding constraints on path length\n",
    "You can also specify the maximum path length (\"number of hops\") surrounding a node for a query.\n",
    "\n",
    "Example: Find subclass relations of bfo:0000002 that are at most 2 hops away."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "id": "97ec21a4",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[{'subject': 'bfo:0000002',\n",
       "  'predicate': ['rdfs:subClassOf'],\n",
       "  'object': 'bfo:0000001'},\n",
       " {'subject': 'bfo:0000002',\n",
       "  'predicate': ['rdfs:subClassOf', 'rdfs:subClassOf'],\n",
       "  'object': 'owl:Thing'}]"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "query(\n",
    "    {\n",
    "        \"source_curie\": \"bfo:0000002\",\n",
    "        \"relation\": \"rdfs:subClassOf\",\n",
    "        \"relation_max_hops\": 2,\n",
    "        \"limit\": 2,\n",
    "    }\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "id": "9937ef2e",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[{'subject': 'bfo:0000002',\n",
       "  'predicate': ['rdfs:subClassOf'],\n",
       "  'object': 'bfo:0000001'},\n",
       " {'subject': 'bfo:0000002',\n",
       "  'predicate': ['rdfs:subClassOf', 'rdfs:subClassOf'],\n",
       "  'object': 'owl:Thing'},\n",
       " {'subject': 'bfo:0000002',\n",
       "  'predicate': ['rdfs:subClassOf', 'bfo:0000108'],\n",
       "  'object': 'bfo:0000008'},\n",
       " {'subject': 'bfo:0000002',\n",
       "  'predicate': ['rdfs:subClassOf', 'bfo:0000108', 'rdfs:subClassOf'],\n",
       "  'object': 'bfo:0000003'},\n",
       " {'subject': 'bfo:0000002',\n",
       "  'predicate': ['rdfs:subClassOf',\n",
       "   'bfo:0000108',\n",
       "   'rdfs:subClassOf',\n",
       "   'rdfs:subClassOf'],\n",
       "  'object': 'bfo:0000001'},\n",
       " {'subject': 'bfo:0000002',\n",
       "  'predicate': ['rdfs:subClassOf',\n",
       "   'bfo:0000108',\n",
       "   'rdfs:subClassOf',\n",
       "   'rdfs:subClassOf',\n",
       "   'rdfs:subClassOf'],\n",
       "  'object': 'owl:Thing'}]"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Query for specific source + relation over a variable number of hops\n",
    "query(\n",
    "    {\n",
    "        \"source_curie\": \"bfo:0000002\",\n",
    "        \"relation\": \"rdfs:subClassOf\",\n",
    "        \"relation_max_hops\": 0,\n",
    "        \"distinct\": True,\n",
    "    }\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4eacb9c7",
   "metadata": {},
   "source": [
    "#### Querying over unconstrained path lengths\n",
    "One can query for relations by setting `relation_max_hops` to 0, which will return all paths matching the given constraints irrespective of length.\n",
    "\n",
    "Example: Get all taxonomical ancestors of a given node (doid:946). (For the sake of running this example faster, we limit the number of results to 10.)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "id": "ca148dcd",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[{'subject': 'doid:946',\n",
       "  'predicate': ['rdfs:subClassOf'],\n",
       "  'object': 'doid:2789'},\n",
       " {'subject': 'doid:946',\n",
       "  'predicate': ['rdfs:subClassOf', 'rdfs:subClassOf'],\n",
       "  'object': 'doid:1398'},\n",
       " {'subject': 'doid:946',\n",
       "  'predicate': ['rdfs:subClassOf', 'rdfs:subClassOf', 'rdfs:subClassOf'],\n",
       "  'object': 'doid:0050117'},\n",
       " {'subject': 'doid:946',\n",
       "  'predicate': ['rdfs:subClassOf',\n",
       "   'rdfs:subClassOf',\n",
       "   'rdfs:subClassOf',\n",
       "   'rdfs:subClassOf'],\n",
       "  'object': 'doid:4'},\n",
       " {'subject': 'doid:946',\n",
       "  'predicate': ['rdfs:subClassOf',\n",
       "   'rdfs:subClassOf',\n",
       "   'rdfs:subClassOf',\n",
       "   'rdfs:subClassOf',\n",
       "   'rdfs:subClassOf'],\n",
       "  'object': 'ogms:0000031'},\n",
       " {'subject': 'doid:946',\n",
       "  'predicate': ['rdfs:subClassOf',\n",
       "   'rdfs:subClassOf',\n",
       "   'rdfs:subClassOf',\n",
       "   'rdfs:subClassOf',\n",
       "   'rdfs:subClassOf',\n",
       "   'rdfs:subClassOf'],\n",
       "  'object': 'bfo:0000016'},\n",
       " {'subject': 'doid:946',\n",
       "  'predicate': ['rdfs:subClassOf',\n",
       "   'rdfs:subClassOf',\n",
       "   'rdfs:subClassOf',\n",
       "   'rdfs:subClassOf',\n",
       "   'rdfs:subClassOf',\n",
       "   'rdfs:subClassOf',\n",
       "   'rdfs:subClassOf'],\n",
       "  'object': 'bfo:0000017'},\n",
       " {'subject': 'doid:946',\n",
       "  'predicate': ['rdfs:subClassOf',\n",
       "   'rdfs:subClassOf',\n",
       "   'rdfs:subClassOf',\n",
       "   'rdfs:subClassOf',\n",
       "   'rdfs:subClassOf',\n",
       "   'rdfs:subClassOf',\n",
       "   'rdfs:subClassOf',\n",
       "   'rdfs:subClassOf'],\n",
       "  'object': 'bfo:0000020'},\n",
       " {'subject': 'doid:946',\n",
       "  'predicate': ['rdfs:subClassOf',\n",
       "   'rdfs:subClassOf',\n",
       "   'rdfs:subClassOf',\n",
       "   'rdfs:subClassOf',\n",
       "   'rdfs:subClassOf',\n",
       "   'rdfs:subClassOf',\n",
       "   'rdfs:subClassOf',\n",
       "   'rdfs:subClassOf',\n",
       "   'rdfs:subClassOf'],\n",
       "  'object': 'bfo:0000002'},\n",
       " {'subject': 'doid:946',\n",
       "  'predicate': ['rdfs:subClassOf',\n",
       "   'rdfs:subClassOf',\n",
       "   'rdfs:subClassOf',\n",
       "   'rdfs:subClassOf',\n",
       "   'rdfs:subClassOf',\n",
       "   'rdfs:subClassOf',\n",
       "   'rdfs:subClassOf',\n",
       "   'rdfs:subClassOf',\n",
       "   'rdfs:subClassOf',\n",
       "   'rdfs:subClassOf'],\n",
       "  'object': 'bfo:0000001'}]"
      ]
     },
     "execution_count": 24,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "query(\n",
    "    {\n",
    "        \"source_curie\": \"doid:946\",\n",
    "        \"relation\": [\"rdfs:subClassOf\", \"part_of\"],\n",
    "        \"relation_max_hops\": 0,\n",
    "        \"distinct\": True,\n",
    "        \"limit\": 10,\n",
    "    }\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c03c1095",
   "metadata": {},
   "source": [
    "#### Including node properties in results\n",
    "You can use the `full: True` parameter to return results such that not only node CURIEs but all node properties (name, etc.) are returned as well. This should be used with care since the payload can get large in size, and is often redundant.\n",
    "\n",
    "Example: Find relations whose target is symp:0000570 with full node details."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "id": "f9f4f4f5",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[{'subject': {'id': 'symp:0020011',\n",
       "   'name': 'bloody diarrhea',\n",
       "   'type': 'class',\n",
       "   'obsolete': False,\n",
       "   'description': None,\n",
       "   'synonyms': [],\n",
       "   'alts': [],\n",
       "   'xrefs': [],\n",
       "   'labels': [],\n",
       "   'properties': {}},\n",
       "  'predicate': {'pred': 'rdfs:subClassOf',\n",
       "   'source': 'symp',\n",
       "   'version': '2022-10-20',\n",
       "   'graph': 'http://purl.obolibrary.org/obo/symp.owl'},\n",
       "  'object': {'id': 'symp:0000570',\n",
       "   'name': 'diarrhea',\n",
       "   'type': 'class',\n",
       "   'obsolete': False,\n",
       "   'description': 'Diarrhea is a feces and droppng symptom involving the abnormally frequent intestinal evacuations with more or less fluid stools.',\n",
       "   'synonyms': [{'value': 'the runs', 'type': 'oboinowl:hasExactSynonym'},\n",
       "    {'value': 'diarrhoea', 'type': 'oboinowl:hasExactSynonym'},\n",
       "    {'value': 'loose bowels', 'type': 'oboinowl:hasExactSynonym'},\n",
       "    {'value': 'loose bowel', 'type': 'oboinowl:hasExactSynonym'},\n",
       "    {'value': 'bacterial gastroenteritis', 'type': 'oboinowl:hasExactSynonym'},\n",
       "    {'value': 'fecal incontinence', 'type': 'oboinowl:hasExactSynonym'},\n",
       "    {'value': 'incontinence of feces', 'type': 'oboinowl:hasExactSynonym'}],\n",
       "   'alts': [],\n",
       "   'xrefs': [],\n",
       "   'labels': [],\n",
       "   'properties': {}}},\n",
       " {'subject': {'id': 'symp:0000738',\n",
       "   'name': 'yellowish green diarrhea',\n",
       "   'type': 'class',\n",
       "   'obsolete': False,\n",
       "   'description': None,\n",
       "   'synonyms': [],\n",
       "   'alts': [],\n",
       "   'xrefs': [],\n",
       "   'labels': [],\n",
       "   'properties': {}},\n",
       "  'predicate': {'pred': 'rdfs:subClassOf',\n",
       "   'source': 'symp',\n",
       "   'version': '2022-10-20',\n",
       "   'graph': 'http://purl.obolibrary.org/obo/symp.owl'},\n",
       "  'object': {'id': 'symp:0000570',\n",
       "   'name': 'diarrhea',\n",
       "   'type': 'class',\n",
       "   'obsolete': False,\n",
       "   'description': 'Diarrhea is a feces and droppng symptom involving the abnormally frequent intestinal evacuations with more or less fluid stools.',\n",
       "   'synonyms': [{'value': 'the runs', 'type': 'oboinowl:hasExactSynonym'},\n",
       "    {'value': 'diarrhoea', 'type': 'oboinowl:hasExactSynonym'},\n",
       "    {'value': 'loose bowels', 'type': 'oboinowl:hasExactSynonym'},\n",
       "    {'value': 'loose bowel', 'type': 'oboinowl:hasExactSynonym'},\n",
       "    {'value': 'bacterial gastroenteritis', 'type': 'oboinowl:hasExactSynonym'},\n",
       "    {'value': 'fecal incontinence', 'type': 'oboinowl:hasExactSynonym'},\n",
       "    {'value': 'incontinence of feces', 'type': 'oboinowl:hasExactSynonym'}],\n",
       "   'alts': [],\n",
       "   'xrefs': [],\n",
       "   'labels': [],\n",
       "   'properties': {}}}]"
      ]
     },
     "execution_count": 25,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "query({\"target_curie\": \"symp:0000570\", \"limit\": 2, \"full\": True})"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.10.12"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}