docs/notebooks/Working_with_Annotations.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Working with Annotations\n",
    "COPASI and SBML files can be annotated with [MIRIAM annotations](http://co.mbine.org/standards/miriam). \n",
    "These annotations describe what the model and its constituents actually represent. In basico you can \n",
    "ask for these annotations using the `get_miriam_annotation` function, simmilarly, you can set them using the \n",
    "`set_miriam_annotation` commands. \n",
    "\n",
    "So lets start as usual, loading basico:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import sys\n",
    "if '../..' not in sys.path:\n",
    "    sys.path.append('../..')\n",
    "\n",
    "\n",
    "from basico import *\n",
    "from ipywidgets import HTML\n",
    "%matplotlib inline"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Resource Lists / Updating\n",
    "For the resolving of MIRIAM entries to work, occasionally COPASI needs to update the list of MIRIAM resources. This will be necessary on systems, where the graphical user interface to COAPSI has not been installed. To see whether it is necessary, you can call: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "have_miriam_resources()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Should that call return false, simply update the resources using: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "update_miriam_resources()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    " To see the list of terms currently known by COPASI you can use the function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>is_citation</th>\n",
       "      <th>uri</th>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>resource</th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>BIND</th>\n",
       "      <td>False</td>\n",
       "      <td>http://identifiers.org/bind</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>ChEBI</th>\n",
       "      <td>False</td>\n",
       "      <td>http://identifiers.org/CHEBI</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Ensembl</th>\n",
       "      <td>False</td>\n",
       "      <td>http://identifiers.org/ensembl</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Enzyme Nomenclature</th>\n",
       "      <td>False</td>\n",
       "      <td>http://identifiers.org/ec-code</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>UniProt Knowledgebase</th>\n",
       "      <td>False</td>\n",
       "      <td>http://identifiers.org/uniprot</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                       is_citation                             uri\n",
       "resource                                                          \n",
       "BIND                         False     http://identifiers.org/bind\n",
       "ChEBI                        False    http://identifiers.org/CHEBI\n",
       "Ensembl                      False  http://identifiers.org/ensembl\n",
       "Enzyme Nomenclature          False  http://identifiers.org/ec-code\n",
       "UniProt Knowledgebase        False  http://identifiers.org/uniprot"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "get_miriam_resources().head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "and of course you can filter elements as usual, for example here to see the resources suitable for citations:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>is_citation</th>\n",
       "      <th>uri</th>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>resource</th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>PubMed</th>\n",
       "      <td>True</td>\n",
       "      <td>http://identifiers.org/pubmed</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>DOI</th>\n",
       "      <td>True</td>\n",
       "      <td>http://identifiers.org/doi</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>arXiv</th>\n",
       "      <td>True</td>\n",
       "      <td>http://identifiers.org/arxiv</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>ISBN</th>\n",
       "      <td>True</td>\n",
       "      <td>http://identifiers.org/isbn</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "          is_citation                            uri\n",
       "resource                                            \n",
       "PubMed           True  http://identifiers.org/pubmed\n",
       "DOI              True     http://identifiers.org/doi\n",
       "arXiv            True   http://identifiers.org/arxiv\n",
       "ISBN             True    http://identifiers.org/isbn"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "resources = get_miriam_resources()\n",
    "resources[resources.is_citation == True]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Displaying Annotations:\n",
    "Now we load a fully annotated model, to display its annotations:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "load_biomodel(64);"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then we can display the Notes of the model:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "059e35d03a4c4144a06529c105d6150f",
       "version_major": 2,
       "version_minor": 0
      },
      "text/plain": [
       "HTML(value='\\n  <body xmlns=\"http://www.w3.org/1999/xhtml\">\\n    <p>\\n      <b>Can yeast glycolysis be underst…"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "display(HTML(get_notes()))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Similarly, we could get to all annotations. As with the `get_notes` call, if no element is specified, the annotations of the model element will be displayed: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'creators': [{'first_name': 'Lukas',\n",
       "   'last_name': 'Endler',\n",
       "   'email': 'lukas@ebi.ac.uk',\n",
       "   'organization': 'EMBL-EBI'},\n",
       "  {'first_name': 'Harish',\n",
       "   'last_name': 'Dharuri',\n",
       "   'email': 'hdharuri@cds.caltech.edu',\n",
       "   'organization': 'California Institute of Technology'},\n",
       "  {'first_name': 'Jacky L',\n",
       "   'last_name': 'Snoep',\n",
       "   'email': 'jls@sun.ac.za',\n",
       "   'organization': 'Stellenbosh University'}],\n",
       " 'references': [{'id': '10951190',\n",
       "   'uri': 'http://identifiers.org/pubmed/10951190',\n",
       "   'resource': 'PubMed',\n",
       "   'description': ''}],\n",
       " 'descriptions': [{'id': 'MODEL6623915522',\n",
       "   'qualifier': 'is',\n",
       "   'uri': 'http://identifiers.org/biomodels.db/MODEL6623915522',\n",
       "   'resource': 'BioModels Database'},\n",
       "  {'id': 'GO:0006096',\n",
       "   'qualifier': 'is',\n",
       "   'uri': 'http://identifiers.org/GO:0006096',\n",
       "   'resource': 'Gene Ontology'},\n",
       "  {'id': 'sce00010',\n",
       "   'qualifier': 'is',\n",
       "   'uri': 'http://identifiers.org/kegg.pathway/sce00010',\n",
       "   'resource': 'KEGG Pathway'},\n",
       "  {'id': 'BIOMD0000000064',\n",
       "   'qualifier': 'is',\n",
       "   'uri': 'http://identifiers.org/biomodels.db/BIOMD0000000064',\n",
       "   'resource': 'BioModels Database'},\n",
       "  {'id': 'REACT_723',\n",
       "   'qualifier': 'is homolog to',\n",
       "   'uri': 'http://identifiers.org/reactome/REACT_723',\n",
       "   'resource': 'Reactome'},\n",
       "  {'id': '4932',\n",
       "   'qualifier': 'has taxon',\n",
       "   'uri': 'http://identifiers.org/taxonomy/4932',\n",
       "   'resource': 'Taxonomy'}],\n",
       " 'modifications': [datetime.datetime(2012, 7, 19, 18, 26, 7, tzinfo=tzutc())],\n",
       " 'created': datetime.datetime(2008, 9, 16, 14, 0, 6, tzinfo=tzutc())}"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "get_miriam_annotation()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To display the annotations of a specific species, or reaction just enter its name as the element to get the information for. Here we do this for `NADH` to return the dictionary of descriptions as given: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'descriptions': [{'id': 'C00004',\n",
       "   'qualifier': 'is',\n",
       "   'uri': 'http://identifiers.org/kegg.compound/C00004',\n",
       "   'resource': 'KEGG Compound'},\n",
       "  {'id': 'CHEBI:16908',\n",
       "   'qualifier': 'is',\n",
       "   'uri': 'http://identifiers.org/CHEBI:16908',\n",
       "   'resource': 'ChEBI'}]}"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "get_miriam_annotation(name='NADH')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Setting annotations\n",
    "Lets start over with a new model, and annotate it as we go along: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [],
   "source": [
    "new_model(name='simple model', notes='A simple decay model');"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `set_miriam_annotation` accepts the following arguments: \n",
    "\n",
    "* `creators`: a list of creator dictionary entries with: `first_name`, `last_name`, `email` and `organization`\n",
    "* `references`: a list of reference dictionary entries with: `id`, `uri`, `resource` and `description`\n",
    "* `descriptions`: a list of description dictionary entries with: `qualifier`, `resource` and `id`\n",
    "* `modifications`: a list of DateTime objects representing the modification dates\n",
    "* `created`: a DateTime object representing the creation date\n",
    "* `replace`: a boolean indicating, whether the current annotation entries should be replaced ('True' default), or if new entries should be added to the existing ones ('False')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [],
   "source": [
    "set_miriam_annotation(creators=[\n",
    "    {\n",
    "        'first_name': 'Frank', \n",
    "        'last_name': 'Bergmann', \n",
    "        'email':'fbergman@caltech.edu', \n",
    "        'organization':'Heidelberg University'\n",
    "    }], replace=True)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'creators': [{'first_name': 'Frank',\n",
       "   'last_name': 'Bergmann',\n",
       "   'email': 'fbergman@caltech.edu',\n",
       "   'organization': 'Heidelberg University'}],\n",
       " 'created': datetime.datetime(2023, 7, 6, 9, 20, 43, tzinfo=tzutc())}"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "get_miriam_annotation()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [],
   "source": [
    "set_miriam_annotation(descriptions=[\n",
    "    {\n",
    "        'qualifier': 'is',\n",
    "        'resource': 'BioModels Database', \n",
    "        'id': 'MODEL6623915522',\n",
    "    }\n",
    "])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'creators': [{'first_name': 'Frank',\n",
       "   'last_name': 'Bergmann',\n",
       "   'email': 'fbergman@caltech.edu',\n",
       "   'organization': 'Heidelberg University'}],\n",
       " 'descriptions': [{'id': 'MODEL6623915522',\n",
       "   'qualifier': 'is',\n",
       "   'uri': 'http://identifiers.org/biomodels.db/MODEL6623915522',\n",
       "   'resource': 'BioModels Database'}],\n",
       " 'created': datetime.datetime(2023, 7, 6, 9, 20, 43, tzinfo=tzutc())}"
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "get_miriam_annotation()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [],
   "source": [
    "set_miriam_annotation(references=[\n",
    "    {\n",
    "      'id': '10951190',\n",
    "      'resource': 'PubMed',\n",
    "    }\n",
    "])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'creators': [{'first_name': 'Frank',\n",
       "   'last_name': 'Bergmann',\n",
       "   'email': 'fbergman@caltech.edu',\n",
       "   'organization': 'Heidelberg University'}],\n",
       " 'references': [{'id': '10951190',\n",
       "   'uri': 'http://identifiers.org/pubmed/10951190',\n",
       "   'resource': 'PubMed',\n",
       "   'description': ''}],\n",
       " 'descriptions': [{'id': 'MODEL6623915522',\n",
       "   'qualifier': 'is',\n",
       "   'uri': 'http://identifiers.org/biomodels.db/MODEL6623915522',\n",
       "   'resource': 'BioModels Database'}],\n",
       " 'created': datetime.datetime(2023, 7, 6, 9, 20, 43, tzinfo=tzutc())}"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "get_miriam_annotation()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [],
   "source": [
    "set_miriam_annotation(modifications=[datetime.datetime.now(datetime.timezone.utc)], replace=True)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'creators': [{'first_name': 'Frank',\n",
       "   'last_name': 'Bergmann',\n",
       "   'email': 'fbergman@caltech.edu',\n",
       "   'organization': 'Heidelberg University'}],\n",
       " 'references': [{'id': '10951190',\n",
       "   'uri': 'http://identifiers.org/pubmed/10951190',\n",
       "   'resource': 'PubMed',\n",
       "   'description': ''}],\n",
       " 'descriptions': [{'id': 'MODEL6623915522',\n",
       "   'qualifier': 'is',\n",
       "   'uri': 'http://identifiers.org/biomodels.db/MODEL6623915522',\n",
       "   'resource': 'BioModels Database'}],\n",
       " 'modifications': [datetime.datetime(2023, 7, 6, 9, 20, 43, 723553, tzinfo=tzutc())],\n",
       " 'created': datetime.datetime(2023, 7, 6, 9, 20, 43, tzinfo=tzutc())}"
      ]
     },
     "execution_count": 18,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "get_miriam_annotation()"
   ]
  }
 ],
 "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.11.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}