{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# This demo notebook shows how units are treated and how to apply unit conversions\n",
    "\n",
    " Opengrid makes use of the python library **pint** for unit conversions"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "import pandas as pd\n",
    "import charts\n",
    "from opengrid.library import misc, houseprint "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Each Sensor object needs an attribute *unit*. For Fluksosensors, the units are as follows:\n",
    "\n",
    "    sensortype      unit\n",
    "    -----------------------\n",
    "    water       ==> liter\n",
    "    gas         ==> liter\n",
    "    electricity ==> Wh\n",
    "    \n",
    "When you obtain data, always use the *get_data()* methods.  These are defined for object of type Houseprint, Device, Site and Sensor. Each of these calls allows you to specify \n",
    "\n",
    "* a resampling rate ('raw', 'min', 'hour', ...)\n",
    "* whether differentiation is needed (to go from counter to flux values, eg from Wh to W)\n",
    "* a target unit\n",
    "\n",
    "The default resulting unit for counter values (diff=False) are:\n",
    "    \n",
    "    sensortype      unit\n",
    "    -----------------------\n",
    "    water       ==> liter\n",
    "    gas         ==> kWh\n",
    "    electricity ==> kWh\n",
    "    \n",
    "The default resulting unit for flux values (diff=True) are:\n",
    "    \n",
    "    sensortype      unit\n",
    "    -----------------------\n",
    "    water       ==> liter/min\n",
    "    gas         ==> W\n",
    "    electricity ==> W    \n",
    "    \n",
    "Let's look at some PV sensors."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "hp = houseprint.Houseprint()\n",
    "sensors = hp.search_sensors(type='electricity', system='solar')\n",
    "\n",
    "head = pd.Timestamp('20150617')\n",
    "tail = pd.Timestamp('20150621')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When we use the default unit, we get Watts."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "df = hp.get_data(sensors=sensors, head=head, tail=tail)\n",
    "charts.plot(df, stock=True, show='inline')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "df = hp.get_data(sensors=sensors, head=head, tail=tail, resample='day', unit='kW')\n",
    "charts.plot(df, stock=True, show='inline')\n",
    "    "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can verify the unit of the obtained dataframe.  Each series has the attribute *unit*.  However, be aware that this attribute will disappear when you do operations on df."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "for col in df:\n",
    "    print(\"The unit of the data for {} is {}\".format(col, df[col].unit))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you want to convert units youself, there is a practical function in opengrid.library.misc that computes the conversion factor to go from one unit to another."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "misc.unit_conversion_factor(source='liter/min', target='m**3/hour')"
   ]
  }
 ],
 "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.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}
