Merge pull request #753 from vg3095/docs_hdf

[TEP014][DOC] HDFWriter Documentation
tardis-sn · Jul 3, 2017 · 0a4d6c9 · 0a4d6c9
2 parents b6fa6ea + 75778e0
commit 0a4d6c9
Show file tree

Hide file tree

Showing 2 changed files with 286 additions and 1 deletion.
diff --git a/docs/notebooks/hdf_writer.ipynb b/docs/notebooks/hdf_writer.ipynb
@@ -0,0 +1,277 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Example Usage of HDFWriter \n",
+    "\n",
+    "If properties of a class needs to be saved in a hdf file, then the class should inherit from `HDFWriterMixin` as demonstrated below.\n",
+    "\n",
+    "`hdf_properties (list)` : Contains names of all the properties that needs to be saved.<br>\n",
+    "`hdf_name (str)` : Specifies the default name of the group under which the properties will be saved."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [],
+   "source": [
+    "from tardis.io.util import HDFWriterMixin\n",
+    "\n",
+    "class ExampleClass(HDFWriterMixin):\n",
+    "    hdf_properties = ['property1', 'property2']\n",
+    "    hdf_name = 'mock_setup'\n",
+    "    def __init__(self, property1, property2):\n",
+    "        self.property1 = property1\n",
+    "        self.property2 = property2\n",
+    "        "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [],
+   "source": [
+    "import numpy as np\n",
+    "import pandas as pd\n",
+    "\n",
+    "#Instantiating Object\n",
+    "property1 = np.array([4.0e14, 2, 2e14, 27.5])\n",
+    "property2 = pd.DataFrame({'one': pd.Series([1., 2., 3.], index=['a', 'b', 'c']),\n",
+    "                        'two': pd.Series([1., 2., 3., 4.], index=['a', 'b', 'c', 'd'])})\n",
+    "obj = ExampleClass(property1, property2)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "You can now save properties using `to_hdf` method.\n",
+    "\n",
+    "#### Parameters\n",
+    "`file_path` : Path where the HDF file will be saved<br>\n",
+    "`path` : Path inside the HDF store to store the `elements`<br>\n",
+    "`name` : Name of the group inside HDF store, under which properties will be saved.<br>\n",
+    "If not specified , then it uses the value specified in `hdf_name` attribute.<br>\n",
+    "If `hdf_name` is also not defined , then it converts the Class name into Snake Case, and uses this value.<br>\n",
+    "Like for example , if `name` is not passed as an argument , and `hdf_name` is also not defined for `ExampleClass` above, then , it will save properties under `example_class` group.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [],
+   "source": [
+    "obj.to_hdf(file_path='test.hdf', path='test')\n",
+    "#obj.to_hdf(file_path='test.hdf', path='test', name='hdf')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "You can now read hdf file using `pd.HDFStore` , or `pd.read_hdf`"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "<class 'pandas.io.pytables.HDFStore'>\n",
+      "File path: test.hdf\n",
+      "/test/mock_setup/property1            series       (shape->[4])  \n",
+      "/test/mock_setup/property2            frame        (shape->[4,2])\n"
+     ]
+    }
+   ],
+   "source": [
+    "#Read HDF file\n",
+    "with pd.HDFStore('test.hdf','r') as data:\n",
+    "    print data\n",
+    "    #print data['/test/mock_setup/property1']"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Saving nested class objects.\n",
+    "\n",
+    "Just extend `hdf_properties` list to include that class object. <br>"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "metadata": {
+    "collapsed": true
+   },
+   "outputs": [],
+   "source": [
+    "class NestedExampleClass(HDFWriterMixin):\n",
+    "    hdf_properties = ['property1', 'nested_object']\n",
+    "    def __init__(self, property1, nested_obj):\n",
+    "        self.property1 = property1\n",
+    "        self.nested_object = nested_obj"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "metadata": {
+    "collapsed": true
+   },
+   "outputs": [],
+   "source": [
+    "obj2 = NestedExampleClass(property1, obj)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 7,
+   "metadata": {
+    "collapsed": true
+   },
+   "outputs": [],
+   "source": [
+    "obj2.to_hdf(file_path='nested_test.hdf')"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 8,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "<class 'pandas.io.pytables.HDFStore'>\n",
+      "File path: nested_test.hdf\n",
+      "/nested_example_class/nested_object/property1            series       (shape->[4])  \n",
+      "/nested_example_class/nested_object/property2            frame        (shape->[4,2])\n",
+      "/nested_example_class/property1                          series       (shape->[4])  \n"
+     ]
+    }
+   ],
+   "source": [
+    "#Read HDF file\n",
+    "with pd.HDFStore('nested_test.hdf','r') as data:\n",
+    "    print data"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Modifed Usage\n",
+    "\n",
+    "In `BasePlasma` class, the way properties of object are collected is different. It does not uses `hdf_properties` attribute.<br>\n",
+    "That\\`s why , `PlasmaWriterMixin` (which extends `HDFWriterMixin`) changes how the properties of `BasePlasma` class will be collected, by changing `get_properties` function.<br>\n",
+    "\n",
+    "Here is a quick demonstration, if behaviour of default `get_properties` function inside `HDFWriterMixin` needs to be changed, by subclassing it to create a new `Mixin`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 9,
+   "metadata": {
+    "collapsed": true
+   },
+   "outputs": [],
+   "source": [
+    "class ModifiedWriterMixin(HDFWriterMixin):\n",
+    "    def get_properties(self):\n",
+    "        #Change behaviour here, how properties will be collected from Class\n",
+    "        data = {name: getattr(self, name) for name in self.outputs}\n",
+    "        return data"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "A demo class , using this modified mixin."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 10,
+   "metadata": {
+    "collapsed": true
+   },
+   "outputs": [],
+   "source": [
+    "class DemoClass(ModifiedWriterMixin):\n",
+    "    outputs = ['property1']\n",
+    "    hdf_name = 'demo'\n",
+    "    def __init__(self, property1):\n",
+    "        self.property1 = property1"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 11,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "<class 'pandas.io.pytables.HDFStore'>\n",
+      "File path: demo_class.hdf\n",
+      "/demo/scalars            series       (shape->[1])\n"
+     ]
+    }
+   ],
+   "source": [
+    "obj3 = DemoClass('random_string')\n",
+    "obj3.to_hdf('demo_class.hdf')\n",
+    "with pd.HDFStore('demo_class.hdf','r') as data:\n",
+    "    print data"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 2",
+   "language": "python",
+   "name": "python2"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 2
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython2",
+   "version": "2.7.13"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}
diff --git a/docs/to_hdf.rst b/docs/to_hdf.rst
@@ -5,4 +5,12 @@ Storing simulations to HDF
 You can ask TARDIS to store the state of each iteration of the simulation you are
  running. To see an example of how this can be achieved see the following jupyter notebook.
 
-:ref:`notebooks/to_hdf.ipynb`
+:ref:`notebooks/to_hdf.ipynb`
+
+
+Using HDFWriter
+===============
+
+Examples on how to use HDFWriter to store properties of a class in a HDF file.
+
+:ref:`notebooks/hdf_writer.ipynb`