Small edits

notebooks/05-nix.ipynb

@@ -19,12 +19,39 @@
     }
    },
    "source": [
-    "As you might have noticed, so far we have been dealing with a \".nix\" file that contained our data. \n",
-    "\n",
-    "Neo itself does not define a file format. When using the NixIO, the Neo objects are mapped to the NIX data model to achieve a representation that can be saved to a file.\n",
-    "\n",
-    "So, what if you have an analysis result or data that does not fit any of the Neo structures?\n",
-    "\n",
+    "As you might have noticed, so far we have been dealing with a \".nix\" file that contained our data. "
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "slideshow": {
+     "slide_type": "fragment"
+    }
+   },
+   "source": [
+    "Neo itself does not define a file format. When using the NixIO, the Neo objects are mapped to the NIX data model to achieve a representation that can be saved to a file."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "slideshow": {
+     "slide_type": "fragment"
+    }
+   },
+   "source": [
+    "So, what if you have an analysis result or data that does not fit any of the Neo structures?"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "slideshow": {
+     "slide_type": "fragment"
+    }
+   },
+   "source": [
     "The NIX data model is more general than the Neo data model and can represent a broad range of data types. "
    ]
   },
@@ -312,8 +339,17 @@
     "\n",
     "Intrestingly, `DataArray` actually only stores these quantities or measurements ('y-values') and defines the 'x-positions' using a **Dimension** descriptor.\n",
     "\n",
-    "For each dimension of the data, a dimension descriptor must be given. The information required for the particular dimension depends on the type of data being defined. NIX provides three dimension descriptors:\n",
-    "\n",
+    "For each dimension of the data, a dimension descriptor must be given. The information required for the particular dimension depends on the type of data being defined. NIX provides three dimension descriptors:"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "slideshow": {
+     "slide_type": "fragment"
+    }
+   },
+   "source": [
     "- SampledDimension: used if a dimension is sampled at regular intervals.\n",
     "- RangeDimension: used if a dimension is sampled at irregular intervals.\n",
     "- SetDimension: used for dimensions that represent categories rather than physical quantities."
@@ -1370,7 +1406,7 @@
     }
    },
    "source": [
-    "## Data and metadata"
+    "## Data and metadata in the same NIX file"
    ]
   },
   {
@@ -1381,65 +1417,6 @@
     }
    },
    "source": [
-    "### What are metadata and why are they needed?\n",
-    "\n",
-    "_Metadata is data about data._\n",
-    "\n",
-    "In science metadata describe the conditions under which the raw data of an experimental study were acquired or analysed.\n",
-    "\n",
-    "Metadata can be anything that is related to an experiment or an analysis step:\n",
-    "- stimulus; protocols\n",
-    "- environmental factors e.g. temperature, gas or liquid concentrations, ...\n",
-    "- operational information e.g. experimenter, date, time, organism, strain, ...\n",
-    "- subject information e.g. animal strain, history, ...\n",
-    "- hardware and software used, versions, updates and customizations\n",
-    "- settings\n"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {
-    "slideshow": {
-     "slide_type": "skip"
-    }
-   },
-   "source": [
-    "Traditionally, actively collected metadata will be found in spreadsheets or lab books. Further metadata is found in raw data files (header or manufacturer documentation), hardware information, code comments, etc.\n",
-    "\n",
-    "All of these information might be required to fully understand how an experiment was conducted and the data analysed.\n",
-    "\n",
-    "The organization of such metadata and their accessibility is not a trivial task, most laboratories developed their home-made solutions over time to keep track of their metadata. The collection and organization of these metadata in its own right is a tough job since experiments are diverse and may even change over time.\n"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {
-    "slideshow": {
-     "slide_type": "slide"
-    }
-   },
-   "source": [
-    "Metadata is especially important when trying to make sense of data \n",
-    "- that you are not familiar with\n",
-    "- that you have not worked with for a while\n",
-    "\n",
-    "A hard issue in this respect is that most of the metadata information is usually disconnected from the data it belongs to; searching data and retrieving the corresponding metadata or vice versa is usually not trivial, especially after a period of time has passed.\n",
-    "\n",
-    "With NIX, metadata can be stored alongside the data it belongs to.\n",
-    "\n",
-    "The process of collecting the metadata can be automatized and the results are machine readable and can be searched programatically."
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {
-    "slideshow": {
-     "slide_type": "slide"
-    }
-   },
-   "source": [
-    "### Data and metadata in the same NIX file\n",
-    "\n",
     "The entities of the NIX data model that were discussed so far carry enough information to get sufficient knowledge to understand the stored data (dimensions, units, labels). Often much more information than that is required to fully interpret the underlying experiment.\n",
     "\n",
     "NIX does not only allow to save initial data and analysed data within the same file. It also allows to create structured annotations of the experiments that were conducted and connects this information directly with the data."
@@ -1449,10 +1426,13 @@
    "cell_type": "markdown",
    "metadata": {
     "slideshow": {
-     "slide_type": "fragment"
+     "slide_type": "slide"
     }
    },
    "source": [
+    "### The odML (open metadata Markup Language) data model in NIX \n",
+    "![odML Logo](../images/odMLLogo-small.png) \n",
+    "\n",
     "Metadata in NIX files is stored according to the [odML data model](https://g-node.github.io/python-odml):\n",
     "- odML is a hierarchically structured data format that provides grouping in nestable `Sections`.\n",
     "- `Sections` can hold both `Sections` and `Properties`.\n",
@@ -1468,8 +1448,7 @@
     }
    },
    "source": [
-    "### The odML (open metadata Markup Language) data model in NIX \n",
-    "![odML Logo](../images/odMLLogo-small.png) \n",
+    "\n",
     "\n",
     "![odML metadata model](../images/nix_odML_model_simplified.png) \n"
    ]
@@ -1759,9 +1738,9 @@
     }
    },
    "source": [
-    "If we think about a collaborator who may want to build upon your results, maybe it would be good to also supply him/her with the data in the original Neo structure used to calculate these results.\n",
+    "If we think about a collaborator who may want to build upon your results, it would be good to also supply him/her with the data in the original Neo structure used to calculate these results.\n",
     "\n",
-    "Let us do so with the Neo NIXIO.\n",
+    "We can do so with the Neo NIXIO's `write` function.\n",
     "\n",
     "But first we need to close the opened `analysis_results.nix` file to open it again with Neo!"
    ]
@@ -2431,13 +2410,7 @@
       "      Shape: (2000,) Unit:uV\n",
       "      SampledDimension: {index = 1}\n",
       "    *DataArray: {name = neo.analogsignal.18037944fdf2472d9c49cff8ea26e4ff.34, type = neo.analogsignal}\n",
-      "      Shape: (2000,) Unit:uV\n"
-     ]
-    },
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
+      "      Shape: (2000,) Unit:uV\n",
       "      SampledDimension: {index = 1}\n",
       "    *DataArray: {name = neo.analogsignal.18037944fdf2472d9c49cff8ea26e4ff.35, type = neo.analogsignal}\n",
       "      Shape: (2000,) Unit:uV\n",