cwpk-20-basic-management-1.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<h1 id=\"CWPK-#20:-Basic-Knowledge-Graph-Management---I\">CWPK #20: Basic Knowledge Graph Management - I</h1>\n",
    "<h2 id=\"It's-Time-to-Learn-How-to-Do-Some-Productive-Work\">It's Time to Learn How to Do Some Productive Work</h2>\n",
    "<div style=\"float: left; width: 305px; margin-right: 10px;\"><img title=\"Cooking with KBpedia\" src=\"http://kbpedia.org/cwpk-files/cooking-with-kbpedia-305.png\" width=\"305\" /></div>\n",
    "<p>Our previous installments of the <a href=\"https://www.mkbergman.com/cooking-with-python-and-kbpedia/\" target=\"_blank\" rel=\"noopener\"><em>Cooking with Python and KBpedia</em></a> series relied on the full knowledge graph, <code>kbpedia_reference_concepts.owl</code>. That approach was useful to test out whether our current <a href=\"https://en.wikipedia.org/wiki/Python_(programming_language)\" target=\"_blank\" rel=\"noopener\">Python</a> and <a href=\"https://en.wikipedia.org/wiki/Project_Jupyter\" target=\"_blank\" rel=\"noopener\">Jupyter Notebook</a> configurations were adequate to handle the entire 58,000 reference concepts (RCs) in <a href=\"https://kbpedia.org/\" target=\"_blank\" rel=\"noopener\">KBpedia</a>. However, a file that large makes finding and navigating stuff a bit harder. For this installment, and a few that come thereafter, we will restrict our example to the much smaller <a href=\"https://en.wikipedia.org/wiki/Upper_ontology\" target=\"_blank\" rel=\"noopener\">upper ontology</a> to KBpedia, KKO (Kbpedia Knowledge Ontology). This ontology only has hundreds of concepts, but has the full suite of functionality and component types found in the full system.</p>\n",
    "<p>In today's installment we will apply some of the basic commands in <a href=\"http://www.lesfleursdunormal.fr/static/informatique/owlready/index_en.html\" target=\"_blank\" rel=\"noopener\">owlready2</a> we learned in the last installment. Owlready2 is the <a href=\"https://en.wikipedia.org/wiki/Application_programming_interface\" target=\"_blank\" rel=\"noopener\">API</a> to our <a href=\"https://en.wikipedia.org/wiki/Web_Ontology_Language\" target=\"_blank\" rel=\"noopener\">OWL2</a> knowledge graphs. In today's installment we will explore the standard <a href=\"https://en.wikipedia.org/wiki/Create,_read,_update_and_delete\" target=\"_blank\" rel=\"noopener\">CRUD</a> (<em>create-read-update-delete</em>) actions against the classes (reference concepts) in our graph. Since our efforts to date have focused on the R in CRUD (for reading), our emphasis today will be on class creation, updates and deletions.</p>\n",
    "<p>Remember, you may find the KKO reference file that we use for this installment, <code>kko.owl</code> where you first stored your KBpedia reference files. (What I call <code>main</code> in the code snippet below.)</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Load KKO\n",
    "<div style=\"background-color:#eee; border:1px dotted #aaa; vertical-align:middle; margin:15px 60px; padding:8px;\"><strong>Which environment?</strong> The specific load routine you should choose below depends on whether you are using the online MyBinder service (the 'raw' version) or local files. See <a href=\"https://www.mkbergman.com/2347/cwpk-17-choosing-and-installing-an-owl-api/\"><strong>CWPK #17</strong></a> for further details.</div>\n",
    "\n",
    "#### Local File Option\n",
    "\n",
    "Like in the last installment, we will follow good practice and use an absolute file or Web address to identify our existing ontology, KKO in this case. Unlike the last installment, we will comment out the little snippet of code we added to provide screen feedback that the file is properly referenced. (If you have any doubts, remove the comment character (<code>#</code>) to restore the feedback):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "main = 'C:/1-PythonProjects/kbpedia/sandbox/kko.owl' \n",
    "# with open(main) as fobj:                         # we are not commenting out the code to scroll through the file    \n",
    "#    for line in fobj:\n",
    "#        print (line)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Again, you <code>shift+enter</code> or pick Run from the main menu to execute the cell contents. (If you chose to post the code lines to screen, you may clear the file listing from the screen by choosing Cell &rarr; All Output &rarr; Clear.)\n",
    "\n",
    "We will next consolidate multiple steps from the prior installment to make absolute file references for the imported SKOS ontology and then to actually load the files:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "skos_file = 'http://www.w3.org/2004/02/skos/core'\n",
    "\n",
    "from owlready2 import *\n",
    "kko = get_ontology(main).load()\n",
    "\n",
    "skos = get_ontology(skos_file).load()\n",
    "kko.imported_ontologies.append(skos) \n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### MyBinder Option\n",
    "If you are running this notebook online, do **NOT** run the above routines, since we will use the GitHub files, but now consolidate all steps into a single cell:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "kko_file = 'https://raw.githubusercontent.com/Cognonto/CWPK/master/sandbox/builds/ontologies/kko.owl' \n",
    "skos_file = 'http://www.w3.org/2004/02/skos/core'\n",
    "\n",
    "from owlready2 import *\n",
    "kko = get_ontology(kko_file).load()\n",
    "\n",
    "skos = get_ontology(skos_file).load()\n",
    "kko.imported_ontologies.append(skos) "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Check Load Results\n",
    "OK, no matter which load option you used, we can again test to see if the ontologies registered in the system, only now specifying two base IRIs in a single command:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "http://kbpedia.org/ontologies/kko# http://www.w3.org/2004/02/skos/core#\n"
     ]
    }
   ],
   "source": [
    "print(kko.base_iri,skos.base_iri)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can also confirm that the two additional ontologies have been properly imported:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[get_ontology(\"http://www.w3.org/2004/02/skos/core#\")]\n"
     ]
    }
   ],
   "source": [
    "print(kko.imported_ontologies)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Re-starting the Notebook\n",
    "\n",
    "I have alluded to it before, but let's now be explicit about how to stop-and-start a notebook, perhaps just to see whether we can clear memory and test whether all steps up to this point are working properly. To do so, go to File &rarr; Save and Checkpoint, and then File &rarr; Close and Halt. (You can insert a Rename step in there should you wish to look at multiple versions of what you are working on.)\n",
    "\n",
    "Upon closing, you will be returned to the main Jupyter Notebook directory screen, where you can navigate to the active file, click on it, and then after it loads, Run the cells up to this point to reclaim your prior working state."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Inspecting KKO Contents\n",
    "\n",
    "So, we threw some steps in the process above to confirm that we were finding our files and loading them. We can now check to see if the classes have loaded properly since remaining steps focus on managing them:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "list(kko.classes())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Further, we know that KKO has a class called <code>Products</code>. We also want to see if our file load has properly captured its <code>subClassOf</code> relationships. (In its baseline configuration KKO <code>Products</code> has three sub-classes: <code>Primary ...</code>, <code>Secondary ...</code>, and <code>Tertiary ...</code>.) We will return to this cell below multiple times to confirm some of the later steps:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[kko.PrimarySectorProduct,\n",
       " kko.SecondarySectorProduct,\n",
       " kko.TertiarySectorService]"
      ]
     },
     "execution_count": 25,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "list(kko.Products.subclasses())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Create a New Class\n",
    "\n",
    "'Create' is the first part of the CRUD acronym. There are many ways to create new objects in Python and Owlready2. This section details three different examples. As you interact with these three examples, you may want to go back up to the cell above and test the <code>list(kko.Products.subclasses())</code> code against the method.\n",
    "\n",
    "The first example defines a class <code>WooProduct</code> that it assigns as a subclass of <code>Thing</code> (the root of OWL), and then we assign the class to the <code>Products</code> class. Note that in the second cell of this method we assign a value of '<code>pass</code>' to it, which is a Python convention for enabling an assignment without actual values as a placeholder for later use. You may see the '<code>pass</code>' term frequently used as scripts set up their objects in the beginning of programs."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [],
   "source": [
    "class WooProducts(Thing):\n",
    "     namespace = kko"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [],
   "source": [
    "class WooProducts(kko.Products): \n",
    "     pass"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the second method, we bypass the initial <code>Thing</code> assignment and directly assign the new class <code>WooFoo</code>:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [],
   "source": [
    "class WooFoo(kko.Products):\n",
    "     namespace = kko"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the third of our examples, we instead use the native Python method of '<code>types</code>' to do the assignment directly. This can be a useful approach when we are wanting to process longer lists of assignments directly:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [],
   "source": [
    "import types\n",
    "\n",
    "with kko:\n",
    "    ProductsFoo = types.new_class(\"ProductsFoo\", (kko.Products,))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Update a Class\n",
    "Unfortunately, there is no direct '<code>edit</code>' or '<code>update</code>' function in Owlready2. At the class level one can '<code>delete</code>' (or '<code>destroy</code>') a class (see below) and then create a new one, granted a two-step process. For properties, including class relationships such as <code>subClassOf</code>, there are built-in methods to '<code>.append</code>' or '<code>.remove</code>' the assignment without fully deleting the class or individual object. In this case, we remove <code>WooProducts</code> as a <code>subClassOf</code> <code>Products</code>:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [],
   "source": [
    "WooProducts.is_a.remove(kko.Products)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Since updates tend to occur more for object properties and values, we discuss these options further two installments from now."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Delete a Class\n",
    "Deletion occurs through a 'destroy' function that completely removes the object and all of its references from the ontology."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {},
   "outputs": [],
   "source": [
    "destroy_entity(WooProducts)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Of course, other functions are available for the use of classes and individuals. See the **Additional Documentation** below for links explaining these options."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Save the Changes\n",
    "\n",
    "When all of your desired changes are made programmatically or via an interactive session such as this one, you are then ready to save the knowledge graph out for re-use. It is generally best to write out the modified ontology under a new file name to prevent overwriting your prior version. If, after inspection, you like your changes and see no problems, you can then re-name this file back to the original name and now make it your working version going forward (of course, use the file location of your own choice)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [],
   "source": [
    "kko.save(file = \"C:/1-PythonProjects/kbpedia/sandbox/kko-test.owl\", format = \"rdfxml\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note during a save specification that you may also indicate the format of the written ontology. We have been using '<code>rdfxml</code>' as our standard format, but you may also use '<code>ntriples</code>' (or others that may arise over time for the application)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Inspect in Protege\n",
    "OK, so after saving we can inspect our new file to make sure that all of the class changes above are now accurately reflected in the formal ontology. Here is the class view for Products:\n",
    "\n",
    "<div style=\"margin: 10px auto; display: table;\">\n",
    "\n",
    "<img src=\"files/basic-management-1-1.png\" title=\"Example Markdown Cell in Edit Mode\" width=\"800\" alt=\"Example Markdown Cell in Edit Mode\" />\n",
    "\n",
    "</div>\n",
    "<div style=\"margin: 10px auto; display: table; font-style: italic;\">\n",
    "\n",
    "Figure 1: Result of KKO Class Changes\n",
    "\n",
    "</div>\n",
    "\n",
    "We can see that our file now has the updated file name (**1**), and the added classes appear in the KKO ontology (**2**).\n",
    "\n",
    "As the use of Protege proves, our changes have been written to our formal ontology correctly. If we so chose, we can now re-name back to our working file, and continue on with our work. Of course, after doing such checks beginning in our process or when we introduce new major wrinkles, we can gain confidence everything is working properly and skip labor-intensive checks as appropriate."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Additional Documentation\n",
    "\n",
    "Owlready2 has relevant additional documentation, with examples, for:\n",
    "- [Class and instance management](https://owlready2.readthedocs.io/en/latest/class.html)\n",
    "- [Class construction](https://owlready2.readthedocs.io/en/latest/restriction.html).\n",
    "\n",
    "\n",
    " <div style=\"background-color:#efefff; border:1px dotted #ceceff; vertical-align:middle; margin:15px 60px; padding:8px;\"> \n",
    "  <span style=\"font-weight: bold;\">NOTE:</span> This article is part of the <a href=\"https://www.mkbergman.com/cooking-with-python-and-kbpedia/\" style=\"font-style: italic;\">Cooking with Python and KBpedia</a> series. See the <a href=\"https://www.mkbergman.com/cooking-with-python-and-kbpedia/\"><strong>CWPK</strong> listing</a> for other articles in the series. <a href=\"http://kbpedia.org/\">KBpedia</a> has its own Web site.\n",
    "  </div>\n",
    "\n",
    "<div style=\"background-color:#ebf8e2; border:1px dotted #71c837; vertical-align:middle; margin:15px 60px; padding:8px;\"> \n",
    "\n",
    "<span style=\"font-weight: bold;\">NOTE:</span> This <strong>CWPK \n",
    "installment</strong> is available both as an online interactive\n",
    "file <a href=\"https://mybinder.org/v2/gh/Cognonto/CWPK/master\" ><img src=\"https://mybinder.org/badge_logo.svg\" style=\"display:inline-block; vertical-align: middle;\" /></a> or as a <a href=\"https://github.com/Cognonto/CWPK\" title=\"CWPK notebook\" alt=\"CWPK notebook\">direct download</a> to use locally. Make sure and pick the correct installment number. For the online interactive option, pick the <code>*.ipynb</code> file. It may take a bit of time for the interactive option to load.</div>\n",
    "\n",
    "<div style=\"background-color:#feeedc; border:1px dotted #f7941d; vertical-align:middle; margin:15px 60px; padding:8px;\"> \n",
    "<div style=\"float: left; margin-right: 5px;\"><img src=\"http://kbpedia.org/cwpk-files/warning.png\" title=\"Caution!\" width=\"32\" /></div>I am at best an amateur with Python. There are likely more efficient methods for coding these steps than what I provide. I encourage you to experiment -- which is part of the fun of Python -- and to <a href=\"mailto:mike@mkbergman.com\">notify me</a> should you make improvements.    \n",
    "\n",
    "</div>"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "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.8.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}