From 87e41e24250c49fa6006da99322bf16b41be9620 Mon Sep 17 00:00:00 2001 From: Vaibhav Gupta Date: Mon, 26 Jun 2017 18:45:38 +0530 Subject: [PATCH 1/2] Added hdf_writer notebook in docs --- docs/notebooks/hdf_writer.ipynb | 277 ++++++++++++++++++++++++++++++++ 1 file changed, 277 insertions(+) create mode 100644 docs/notebooks/hdf_writer.ipynb diff --git a/docs/notebooks/hdf_writer.ipynb b/docs/notebooks/hdf_writer.ipynb new file mode 100644 index 00000000000..c6159f931e7 --- /dev/null +++ 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.
\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
\n", + "`path` : Path inside the HDF store to store the `elements`
\n", + "`name` : Name of the group inside HDF store, under which properties will be saved.
\n", + "If not specified , then it uses the value specified in `hdf_name` attribute.
\n", + "If `hdf_name` is also not defined , then it converts the Class name into Snake Case, and uses this value.
\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": [ + "\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.
" + ] + }, + { + "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": [ + "\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.
\n", + "That\\`s why , `PlasmaWriterMixin` (which extends `HDFWriterMixin`) changes how the properties of `BasePlasma` class will be collected, by changing `get_properties` function.
\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": [ + "\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 +} From 75778e0dd72c7738a93594ddb7e073a8efe84584 Mon Sep 17 00:00:00 2001 From: Vaibhav Gupta Date: Mon, 26 Jun 2017 19:03:29 +0530 Subject: [PATCH 2/2] Add reference of notebook in docs --- docs/to_hdf.rst | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/to_hdf.rst b/docs/to_hdf.rst index d5b7c48ac26..d2f92a8fcdb 100644 --- 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` \ No newline at end of file +: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` \ No newline at end of file