Extended Documentation, added SVG files, gitignore

.gitignore

@@ -0,0 +1,2 @@
+.ipynb_checkpoints
+.vscode

PROV-Model Visualisation.ipynb

@@ -1,5 +1,17 @@
 {
  "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Visualisation of PROVenance-Models\n",
+    "\n",
+    "In order to visualise the provenance models, we employ the python `prov` library.\n",
+    "Details of all required libraries including their version information can be found in the `requirements.txt`.\n",
+    "\n",
+    "First of all import the required libraries:"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 1,
@@ -12,14 +24,24 @@
     "from prov.dot import prov_to_dot"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Define some useful functions that can be employed later for the particular provenance models respectively files."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 2,
    "metadata": {},
    "outputs": [],
    "source": [
-    "# Read PROV model from RDF file\n",
     "def readProv(filename):\n",
+    "    \"\"\"\n",
+    "    Deserialise provenance information from a turtle file given as parameter.\n",
+    "    Note that the file ending 'ttl' is automatically added.\n",
+    "    \"\"\"\n",
     "    with open(\"%s.ttl\" % (filename,), 'r') as f:\n",
     "        return(ProvDocument.deserialize(source=f, format='rdf'))"
    ]
@@ -30,8 +52,11 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# Create SVG from PROV model\n",
     "def prov2svg(prov_doc, svg_filename):\n",
+    "    \"\"\"\n",
+    "    Export the provenance document (given as parameter) as SVG file under the given name.\n",
+    "    Note that the file ending 'svg' is automatically added.\n",
+    "    \"\"\"\n",
     "    prov_doc.plot(filename='%s.svg' % (svg_filename,))"
    ]
   },
@@ -41,12 +66,12 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# Create DOT from PROV model\n",
     "def prov2dot(prov_doc, dot_filename):\n",
-    "    prov_to_dot(prov_doc).write('%s.dot' % (dot_filename,))\n",
-    "    #with open(, 'w') as f:\n",
-    "    #    f.write()\n",
-    "    #    f.close()"
+    "    \"\"\"\n",
+    "    Export the provenance document (given as parameter) as DOT file under the given name.\n",
+    "    Note that the file ending 'dot' is automatically added.\n",
+    "    \"\"\"\n",
+    "    prov_to_dot(prov_doc).write('%s.dot' % (dot_filename,))"
    ]
   },
   {
@@ -55,8 +80,13 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# Extract entities from PROV model\n",
     "def prov2entities_csv(prov_doc, csv_filename):\n",
+    "    \"\"\"\n",
+    "    Create a list of entities from the given provenance document.\n",
+    "    Extract information about the 'type', 'identifier', 'prov:label', and 'da:fileType' (if available).\n",
+    "    Export the list as CSV file under the given name.\n",
+    "    Note that '_entities.csv' will be automatically added to the csv filename.\n",
+    "    \"\"\"\n",
     "    df = pd.DataFrame()\n",
     "    for r in prov_doc.get_records((ProvEntity, ProvActivity)):\n",
     "        label = \"; \".join(r.get_attribute('prov:label'))\n",
@@ -78,8 +108,13 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# Extract relations from PROV model\n",
     "def prov2rel_csv(prov_doc, csv_filename):\n",
+    "    \"\"\"\n",
+    "    Create a list of relations from the given provenance document.\n",
+    "    Extract information about the two involved elements including Identifier and type as well as their role (if available).\n",
+    "    Export the list as CSV file under the given name.\n",
+    "    Note that '_relations.csv' will be automatically added to the csv filename.\n",
+    "    \"\"\"\n",
     "    df = pd.DataFrame()\n",
     "    for r in prov_doc.get_records((ProvAssociation, ProvGeneration, ProvUsage)):\n",
     "        attrs = r.formal_attributes\n",
@@ -95,24 +130,31 @@
     "    df.sort_values(by=['type', 'com1_ID', 'com2_ID']).to_csv(\"%s_relations.csv\" % (csv_filename,))"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Now, as the helping functions are defined, search for provenance models in the folders `model-based` and `model-based/pattern`.\n",
+    "In case they are not marked as old by containing `_old` in their path, parse the document and export them into SVG as well as into DOT files using the helper functions."
+   ]
+  },
   {
    "cell_type": "code",
-   "execution_count": 7,
+   "execution_count": 8,
    "metadata": {},
    "outputs": [
     {
      "name": "stdout",
      "output_type": "stream",
      "text": [
+      "Computing 'model-based/simulation_models'...OK\n",
       "Computing 'model-based/geometry'...OK\n",
       "Computing 'model-based/context_models'...OK\n",
-      "Computing 'model-based/simulation_models'...OK\n",
       "Computing 'model-based/pattern/extract-information'...OK\n",
-      "Computing 'model-based/pattern/generation'...OK\n",
-      "Computing 'model-based/pattern/refinement'...OK\n",
-      "Computing 'model-based/pattern/composition'...OK\n",
       "Computing 'model-based/pattern/parameterisation'...OK\n",
-      "None\n"
+      "Computing 'model-based/pattern/composition'...OK\n",
+      "Computing 'model-based/pattern/refinement'...OK\n",
+      "Computing 'model-based/pattern/generation'...OK\n"
      ]
     }
    ],
@@ -126,12 +168,11 @@
     "    n = file.replace(\".ttl\", \"\")\n",
     "    print(\"Computing '%s'...\" % (n,), end='')\n",
     "    pdoc = readProv(n)\n",
-    "    #prov2svg(pdoc, n)\n",
-    "    dot = prov2dot(pdoc, n)\n",
+    "    prov2svg(pdoc, n)\n",
+    "    prov2dot(pdoc, n)\n",
     "    #prov2entities_csv(pdoc, n)\n",
     "    #prov2rel_csv(pdoc, n)\n",
-    "    print(\"OK\")\n",
-    "print(dot)"
+    "    print(\"OK\")"
    ]
   }
  ],
@@ -151,7 +192,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.5.3"
+   "version": "3.7.2"
   }
  },
  "nbformat": 4,

README.md

@@ -1,13 +1,34 @@
 # PROV-Bio-electric-Systems
 
-A Collection of W3C PROVenance Model for the Numerical Modelling and Finite Element Simulation Processes of Bio-electric Systems.
+A collection of W3C PROVenance models for the numerical modelling and finite element simulation processes of bio-electric systems.
+Details about these models can be found in
+
+M. Schröder, H. Raben, F. Krüger, A. Ruscheinski, U. van Rienen, A. Uhrmacher, and S. Spors, “PROVenance Patterns in Numerical Modelling and Finite Element Simulation  Processes of Bio-electric Systems,” 41st Annual International Conference of the IEEE Engineering in Medicine and Biology Society (EMBC), Jul. 2019. To Appear.
+
+## Usage
 
 The folder `model-based` contains a set of provenance models that correspond to the process described in
 
 U. van Rienen, U. Zimmermann, H. Raben, and P. W. Kämmerer, “Preliminary numerical study on electrical stimulation at alloplastic reconstruction plates of the mandible,” Scientific Computing in Electrical Engineering, Jan. 2018. [Online]. Available: http://dx.doi.org/10.1007/978-3-319-75538-0_1
 
 Along with the model, we provide a set of pattern (`model-based/pattern`), that we identified during analysis.
 
-These models are published under the Creative Commons CC-BY 4.0 license (https://creativecommons.org/licenses/by/4.0/), please attribute them as:
+In order to visualise the Turtle specification (`*.ttl` files) the Jupyter notebook `PROV-Model Visualisation.ipynb` was used.
+To execute this notebook, make sure the `requirements.txt` are installed appropriately:
+
+```
+pip install -r requirements.txt
+```
+
+The software was tested using Jupyter v4.4.0 and Python v3.5.3.
+Alternatively, launch this repository in mybinder.org:
+
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/SFB-ELAINE/PROV-Bio-electric-Systems/master)
+
+## License
+
+[![Creative Commons License](https://i.creativecommons.org/l/by/4.0/88x31.png)](http://creativecommons.org/licenses/by/4.0/)
+
+This work is licensed under a [Creative Commons Attribution 4.0 International License](http://creativecommons.org/licenses/by/4.0/), please attribute them as:
 
 Max Schröder, Hendrikje Raben, Frank Krüger, Andreas Ruscheinski, Ursula van Rienen, Adelinde Uhrmacher, and Sascha Spors, “PROVenace Models for Bio-electric Systems,” https://github.com/SFB-ELAINE/PROV-Bio-electric-Systems