tutorial/narci_tutorial.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## NARCI Tutorial\n",
    "\n",
    "```\n",
    "  (c) 2017\n",
    "    University of Amsterdam\n",
    "    Forschungszentrum Juelich GmbH\n",
    "    The German Neuroinformatics Node\n",
    "    Le Centre national de la recherche scientifique (CRNS)\n",
    "```\n",
    "\n",
    "\n",
    "This is a basic tutorial on using `narci` via Python library [rdflib](https://rdflib.readthedocs.io/en/stable/).  \n",
    "\n",
    "### Contents\n",
    "\n",
    "[Loading the ontology schema as RDF graph](#load)\n",
    "\n",
    "[How to use the schema: Programmaticaly within Python](#program_how)\n",
    "\n",
    "\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import sys\n",
    "is_py3 = sys.version_info.major  > 2 # This is tested with 3.6\n",
    "is_py3"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id='load'></a>\n",
    "### Loading the ontology schema as RDF graph \n",
    "\n",
    "NARCI is designed as an [OWL ontology](https://www.w3.org/OWL/) and expressed as a semantic graph via [RDF](https://www.w3.org/RDF/). Note that his loads a schema"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<Graph identifier=N7ff42f12bd0b4543a1de419e6944281a (<class 'rdflib.graph.Graph'>)>"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import rdflib\n",
    "# Use narci persistent URL in production work.\n",
    "narci_url = 'http://www.purl.org/narci/v0.2.1/schema'\n",
    "narci = rdflib.Graph()\n",
    "narci.parse(narci_url, format=\"n3\") # Read a turtle file"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id=\"program_how\"></a>\n",
    "### How to use the schema: Programmaticaly within Python\n",
    "\n",
    "NARCI schema, see `SVG` file under the repository. Here, we only use a small subset of classes and their members: \n",
    "\n",
    "* `narci:Metadata`\n",
    "    * `narci:TwoPhotonImaging`\n",
    "    * `narci:CellFromRegionOfInterest`\n",
    "    * `narci:ImageSequence`\n",
    "    * `narci:TwoImagingSystem`\n",
    "\n",
    "Let's have a dummy two sessions with the following basic entries:\n",
    "\n",
    "1. Session 1\n",
    "   ```\n",
    "   narci:TwoPhotonImaging\n",
    "       imaging_date \"2017-10-21\"\n",
    "       imaging_session_id 1\n",
    "       imaging_depth 0.1\n",
    "       \n",
    "   narci:CellFromRegionOfInterest    \n",
    "       neuronal_calcium_sensors \"CMV-GCaMP6s\"\n",
    "       ca_target_cell_size 20x20\n",
    "   \n",
    "   narci:ImageSequence\n",
    "       ca_image_cortical_z_stacks 1200\n",
    "   \n",
    "   narci:TwoImagingSystem\n",
    "       laser_wavelength 750\n",
    "   ```\n",
    "   \n",
    "2.  Session 2\n",
    "   ```\n",
    "   narci:TwoPhotonImaging\n",
    "       imaging_date \"2017-10-21\"\n",
    "       imaging_session_id 2\n",
    "       imaging_depth 0.1\n",
    "       \n",
    "   narci:CellFromRegionOfInterest\n",
    "       neuronal_calcium_sensors \"CMV-GCaMP6s\"\n",
    "       ca_target_cell_size 25x25\n",
    "\n",
    "   narci:ImageSequence\n",
    "       ca_image_cortical_z_stacks 1000\n",
    "   \n",
    "   narci:TwoImagingSystem\n",
    "       laser_wavelength 750\n",
    "   \n",
    "   ```\n",
    "\n",
    "Note that of course there are many more metadata entries, but this is just a dummy example."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# Import schema as a namespace\n",
    "from rdflib import Namespace\n",
    "# narci persistent URL in production work.\n",
    "narci_url = 'http://www.purl.org/narci/schema/'\n",
    "# This will add narci namespace, a schema via @prefix\n",
    "narci = Namespace(narci_url)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "collapsed": true,
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "# Generate Instance: Particular Experimental Metadata\n",
    "from rdflib import Graph, Literal, URIRef, BNode\n",
    "from rdflib.namespace import RDF\n",
    "calcium_metadata  = Graph()\n",
    "# Session 1 and Session 2 entries\n",
    "calcium_metadata.add((URIRef(\"#session1\"), RDF.type, narci.Metadata))\n",
    "calcium_metadata.add((URIRef(\"#session2\"), RDF.type, narci.Metadata))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# twoPhotonImaging Object 1\n",
    "twoPhotonImaging = BNode()\n",
    "calcium_metadata.add((URIRef(\"#session1\"), narci.twoPhotonImaging, twoPhotonImaging))\n",
    "calcium_metadata.add((twoPhotonImaging, narci.imaging_date, Literal(\"2017-10-21\")))\n",
    "calcium_metadata.add((twoPhotonImaging, narci.imaging_session_id, Literal(1)))\n",
    "calcium_metadata.add((twoPhotonImaging, narci.imaging_depth, Literal(0.1)))\n",
    "# twoPhotonImaging Object 2\n",
    "twoPhotonImaging = BNode()\n",
    "calcium_metadata.add((URIRef(\"#session2\"), narci.twoPhotonImaging, twoPhotonImaging))\n",
    "calcium_metadata.add((twoPhotonImaging, narci.imaging_date, Literal(\"2017-11-21\")))\n",
    "calcium_metadata.add((twoPhotonImaging, narci.imaging_session_id, Literal(2)))\n",
    "calcium_metadata.add((twoPhotonImaging, narci.imaging_depth, Literal(0.17)))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# cellFromRegionOfInterest Object 1\n",
    "cellFromRegionOfInterest = BNode()\n",
    "calcium_metadata.add((URIRef(\"#session1\"), \n",
    "                      narci.cellFromRegionOfInterest, cellFromRegionOfInterest))\n",
    "calcium_metadata.add((cellFromRegionOfInterest, narci.neuronal_calcium_sensors, \n",
    "                      Literal(\"CMV-GCaMP6s\")))\n",
    "calcium_metadata.add((cellFromRegionOfInterest, narci.ca_target_cell_size, \n",
    "                      Literal(\"20x20\")))\n",
    "# cellFromRegionOfInterest Object 2\n",
    "cellFromRegionOfInterest = BNode()\n",
    "calcium_metadata.add((URIRef(\"#session2\"), narci.cellFromRegionOfInterest, \n",
    "                      cellFromRegionOfInterest))\n",
    "calcium_metadata.add((cellFromRegionOfInterest, narci.neuronal_calcium_sensors, \n",
    "                      Literal(\"CMV-GCaMP6s\")))\n",
    "calcium_metadata.add((cellFromRegionOfInterest,narci.ca_target_cell_size, \n",
    "                      Literal(\"25x25\")))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# imageSequence Object 1\n",
    "imageSequence = BNode()\n",
    "calcium_metadata.add((URIRef(\"#session1\"), narci.imageSequence, imageSequence))\n",
    "calcium_metadata.add((imageSequence, narci.ca_image_cortical_z_stacks, Literal(\"1200\")))\n",
    "# imageSequence Object 2\n",
    "imageSequence = BNode()\n",
    "calcium_metadata.add((URIRef(\"#session2\"), narci.imageSequence, imageSequence))\n",
    "calcium_metadata.add((imageSequence, narci.ca_image_cortical_z_stacks, Literal(\"2000\")))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# twoImagingSystem Object 1\n",
    "twoImagingSystem = BNode()\n",
    "calcium_metadata.add((URIRef(\"#session1\"), narci.twoImagingSystem, twoImagingSystem))\n",
    "calcium_metadata.add((twoImagingSystem, narci.laser_wavelength, Literal(750)))\n",
    "\n",
    "# twoImagingSystem Object 2\n",
    "twoImagingSystem = BNode()\n",
    "calcium_metadata.add((URIRef(\"#session2\"), narci.twoImagingSystem, twoImagingSystem))\n",
    "calcium_metadata.add((twoImagingSystem, narci.laser_wavelength, Literal(900)))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "collapsed": true,
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "# now show the metadata\n",
    "sturtle =  calcium_metadata.serialize(format='turtle').decode(\"utf-8\") "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "@prefix ns1: <http://www.purl.org/narci/schema/> .\n",
      "@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .\n",
      "@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .\n",
      "@prefix xml: <http://www.w3.org/XML/1998/namespace> .\n",
      "@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .\n",
      "\n",
      "<#session1> a ns1:Metadata ;\n",
      "    ns1:cellFromRegionOfInterest [ ns1:ca_target_cell_size \"20x20\" ;\n",
      "            ns1:neuronal_calcium_sensors \"CMV-GCaMP6s\" ] ;\n",
      "    ns1:imageSequence [ ns1:ca_image_cortical_z_stacks \"1200\" ] ;\n",
      "    ns1:twoImagingSystem [ ns1:laser_wavelength 750 ] ;\n",
      "    ns1:twoPhotonImaging [ ns1:imaging_date \"2017-10-21\" ;\n",
      "            ns1:imaging_depth 1e-01 ;\n",
      "            ns1:imaging_session_id 1 ] .\n",
      "\n",
      "<#session2> a ns1:Metadata ;\n",
      "    ns1:cellFromRegionOfInterest [ ns1:ca_target_cell_size \"25x25\" ;\n",
      "            ns1:neuronal_calcium_sensors \"CMV-GCaMP6s\" ] ;\n",
      "    ns1:imageSequence [ ns1:ca_image_cortical_z_stacks \"2000\" ] ;\n",
      "    ns1:twoImagingSystem [ ns1:laser_wavelength 900 ] ;\n",
      "    ns1:twoPhotonImaging [ ns1:imaging_date \"2017-11-21\" ;\n",
      "            ns1:imaging_depth 1.7e-01 ;\n",
      "            ns1:imaging_session_id 2 ] .\n",
      "\n",
      "\n"
     ]
    }
   ],
   "source": [
    "print(sturtle)"
   ]
  }
 ],
 "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.6.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}