{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "9bd55b02",
   "metadata": {},
   "source": [
    "# Get Started\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b20e657f",
   "metadata": {},
   "source": [
    "## Install\n",
    "\n",
    "Precondition: You need a Linux Computer with an already installed Anaconda or Miniconda environment.\n",
    "\n",
    "Download ZIP-file from XXX, store it to an arbitrary work directory, say `/home/dsci/b/gendifs/`. Unzip the zip file. Among other directories you will get the subdirs `mm`, `md`, `py`. "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "66bfd6c7",
   "metadata": {},
   "source": [
    "Start Juypter. In the dasci-lab this will work:\n",
    "\n",
    "```{shell}\n",
    "cd\n",
    "jupyter notebook &\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9e8f290d",
   "metadata": {},
   "source": [
    "Change into the subdir `py` of your work directory. Among other files you should be able to detect the python program `gd05.py`."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2d8c227a",
   "metadata": {},
   "source": [
    "## Create your first GenDifS mindmap"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5e07dc4b",
   "metadata": {},
   "source": [
    "We show a full cycle of how to craft a simple taxonomical ontology with GenDifS.\n",
    "\n",
    "Say you want to formalize the example from the [SKOS-Primer, Section 4.1](https://www.w3.org/TR/skos-primer/#seccollections):\n",
    "\n",
    "      milk\n",
    "        <milk by source animal>\n",
    "          cow milk\n",
    "          goat milk\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9469abc4",
   "metadata": {},
   "source": [
    "Start freeplane. Create a new empty mindmap.  Select (CTRL-C) the following lines:\n",
    "\n",
    "    ONTOLOGY\n",
    "      milk\n",
    "        BY SOME mammal\n",
    "          cow milk\n",
    "            SOME cow\n",
    "          goat milk\n",
    "            SOME goat\n",
    "\n",
    "Paste (CTRL-V) it to the root node of the mindmap. You should get a mindmap like this:\n",
    "\n",
    "![](../images/milk_EN_initial.png)\n",
    "\n",
    "Save this mindmap to the `mm` directory within your work directory, e.g. `/home/dsci/b/gendifs/mm/milk_EN.mm`. \n",
    "\n",
    "(Of course we already have allocated this mindmap for you in the `mm` directory, see {Download}`../mm/milk_EN_initial.mm`. You may open it, and save it again to `milk_EN.mm`.)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "918963b0",
   "metadata": {},
   "source": [
    "## Use gd05.py\n",
    "\n",
    "Go back to Juypter. Navigate to the directory `py` within your work directory (in our example `/home/dsci/b/gendifs/py`).\n",
    "\n",
    "Create an new Python 3.x Jupyter Notebook, say `my_sandbox.ipynb`.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "cb936cf9",
   "metadata": {},
   "outputs": [],
   "source": [
    "from gd05 import GenDifS_Map\n",
    "import os"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ccbbbf7d",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "0c130334",
   "metadata": {},
   "source": [
    "Create an instance of Class `Ontology`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "c777f894",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "cwd into input_dir: /home/dsci/a/l/lib/gendifs_05/mm\n",
      "reading /home/dsci/a/l/lib/gendifs_05/mm > milk_EN.mm (8 nodes)\n",
      "Parsing XML: #1 start nodes\n",
      "ontology node IDs: {'ID_397914510': 'ONTOLOGY'}\n",
      "RDF: 102 498\n",
      "updated mindmap with backup to /home/dsci/a/l/lib/gendifs_05/mm/milk_EN.mm_backup_2022-09-08T15-17-01\n"
     ]
    }
   ],
   "source": [
    "mm_relative = \"../mm/milk_EN.mm\"\n",
    "\n",
    "# provide an absolute path to get well definded file locations\n",
    "mm = os.path.abspath(mm_relative)\n",
    "\n",
    "o = GenDifS_Map(mm)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "52c28577",
   "metadata": {},
   "source": [
    "The parser will read the mindmap file, parse it's content, and generate several internal and external representations of the ontology."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "18221e2b",
   "metadata": {},
   "source": [
    "### External Representations (i.e. files)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6e99a1be",
   "metadata": {},
   "source": [
    "As a first step, feedback is provided within the mindmip itself. **Warning:** This feedback will **overwrite** your file `milk_EN.mm` (and allocate a backup file directly in the `mm`-directory). To see the changes, switch back to freemind, and reload the mindmap:\n",
    "\n",
    "* Datei > aus Revisionsverlauf wiederherstellen > \"milk_EN.mm\" > Öffnen\n",
    "\n",
    "![](../images/milk_EN.png)\n",
    "\n",
    "The syntax highlight will visualize classes, other stuff, and also Errors. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "7fdcb270",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "cwd into input_dir: /home/dsci/a/l/lib/gendifs_05/mm\n",
      "reading /home/dsci/a/l/lib/gendifs_05/mm > milk_EN.mm (8 nodes)\n",
      "Parsing XML: #1 start nodes\n",
      "ontology node IDs: {'ID_397914510': 'ONTOLOGY'}\n",
      "RDF: 102 498\n",
      "updated mindmap with backup to /home/dsci/a/l/lib/gendifs_05/mm/milk_EN.mm_backup_2022-09-08T15-17-20\n",
      "writing ontologies to /home/dsci/a/l/lib/gendifs_05/milk_EN.mm_ONTOLOGY/ :\n",
      "   gendifs.ttl rdflib.ttl owlrl.ttl \n"
     ]
    }
   ],
   "source": [
    "o = GenDifS_Map(mm, write_ontology = True)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5f2b408c",
   "metadata": {},
   "source": [
    "You also will get 3 representations of your ontology:\n",
    "* {Download}`../milk_EN.mm_ONTOLOGY/gendifs.ttl`: the raw Turle code produced by GenDifS itself\n",
    "* {Download}`../milk_EN.mm_ONTOLOGY/rdflib.ttl`: the turtle code exported by rdflib\n",
    "* {Download}`../milk_EN.mm_ONTOLOGY/owlrl.ttl`: the turtle code exported by owlrl after applying a full deductive closure inferencing\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e6c67536",
   "metadata": {},
   "source": [
    "Each of these ttl-files load into Protegé directly. However, they look somewhat crowded:\n",
    "\n",
    "![](../images/milk_EN_protege.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "33eeb96d",
   "metadata": {},
   "source": [
    "### Internal Representations"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cb7553fb",
   "metadata": {},
   "source": [
    "The external representations correspond with internal representations:\n",
    "\n",
    "* `o.ttl`: The raw GenDifS ttl, given as a string\n",
    "* `o.rdflib`: A rdflib-Graph, as it is after importing the raw GenDifS-ttl\n",
    "* `o.owlrl`: The rdflib-Graph, after applying owlrl-inferencing."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "2a78feea",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "            # namespaces to be aligned by the user\n",
      "            @prefix ex: <http://mm2ttl.net/namespace/ex#> .  # examples of OWL A-Box\n",
      "            @prefix cpt: <http://mm2ttl.net/namespace/cpt#> .    # concept; instance of skos:concept\n",
      "            @prefix : <http://mm2ttl.net/namespace/default#> .\n"
     ]
    }
   ],
   "source": [
    "print(o.ttl[0:300]) # GenDifS simply exports to Turtle (*.ttl), i.e. a human readable text file"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "296d0c52",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<class 'rdflib.graph.Graph'>: 102 triples\n"
     ]
    }
   ],
   "source": [
    "print(f\"{type(o.rdflib)}: {len(o.rdflib)} triples\") # a more complex and powerful python object"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0f66f935",
   "metadata": {},
   "source": [
    "rdflib allows to query it's graphs via SPARQL:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "99a3e7e0",
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "http://mm2ttl.net/namespace/ex#milk_ID_564335606 http://www.w3.org/1999/02/22-rdf-syntax-ns#type http://mm2ttl.net/namespace/default#milk\n",
      "http://mm2ttl.net/namespace/ex#milk_ID_1716031630 http://www.w3.org/1999/02/22-rdf-syntax-ns#type http://mm2ttl.net/namespace/default#milk\n",
      "http://mm2ttl.net/namespace/ex#milk_ID_1716031630 http://mm2ttl.net/namespace/default#has_source http://mm2ttl.net/namespace/ex#cow_ID_1716031630\n",
      "http://mm2ttl.net/namespace/ex#milk_ID_1716031630 http://mm2ttl.net/namespace/ex#classifyLike http://mm2ttl.net/namespace/ex#cow%20milk_ID_1716031630\n",
      "http://mm2ttl.net/namespace/ex#milk_ID_1490639552 http://www.w3.org/1999/02/22-rdf-syntax-ns#type http://mm2ttl.net/namespace/default#milk\n",
      "http://mm2ttl.net/namespace/ex#milk_ID_1490639552 http://mm2ttl.net/namespace/default#has_source http://mm2ttl.net/namespace/ex#goat_ID_1490639552\n",
      "http://mm2ttl.net/namespace/ex#milk_ID_1490639552 http://mm2ttl.net/namespace/ex#classifyLike http://mm2ttl.net/namespace/ex#goat%20milk_ID_1490639552\n"
     ]
    }
   ],
   "source": [
    "my_query = \"\"\"\n",
    "SELECT DISTINCT ?s ?p ?o\n",
    "WHERE {\n",
    "    ?s ?p ?o .\n",
    "    ?s rdf:type :milk \n",
    "}\"\"\"\n",
    "\n",
    "for row in o.rdflib.query(my_query):\n",
    "    print(row.s, row.p, row.o)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "7b3be0c8",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<class 'rdflib.graph.Graph'>: 498 triples\n"
     ]
    }
   ],
   "source": [
    "print(f\"{type(o.owlrl)}: {len(o.owlrl)} triples\")"
   ]
  }
 ],
 "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.9.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}