Add MdoHelper class (#17)

* Add MdoHelper class

Author: dkarchmer

CHANGELOG.md

@@ -1,3 +1,7 @@
+### v0.7.3 (2017-11-29)
+
+  * Add utils.mdo.MdoHelper class to help with raw stream data conversions
+
 ### v0.7.2 (2017-11-02)
 
   * Allow users to specify a verify=False option in Api() that disabled SSL certificate verification for iotile.cloud

README.md

@@ -371,6 +371,31 @@ if __name__ == '__main__':
     work.main()
 ```
 
+### Misc Utilities
+
+#### MdoHelper (advance)
+
+IOTile Cloud assumes data is transformed in multiple places using a simple Multiple, Divide and Offset (or MDO) 
+set of values. For example, streams use output_units, which include an MDO that can be used to convert the 
+internal value stored on the data stream into this output unit. The MdoHelper is a simple class to help with these
+converstions.
+
+```
+from iotile_cloud.stream.data import StreamData
+from iotile_cloud.utils.mdo import MdoHelper
+
+stream = api.stream('s--0000-0001--0000-0000-0000-0001--5001').get()
+units = stream['output_unit']
+mdo = MdoHelper(m=units.get('m', 1), d=units.get('d', 1), o=units.get('o', 0.0))
+
+# Get unmodified internal data. The 'value' member is based on some internal storage units for the given stream type
+stream_data = StreamRawData(stream['slug'], api)
+
+stream_data.initialize_from_server(lastn=100)
+for item in stream_data.data:
+    print('{0}: {1}'.format(item['timestamp'], mdo.compute_value(item['value'])))
+```
+
 ## Requirements
 
 iotile_cloud requires the following modules.

iotile_cloud/utils/mdo.py

@@ -0,0 +1,34 @@
+class MdoHelper(object):
+    _m = 1
+    _d = 1
+    _o = None
+
+    def __init__(self, m, d, o=None):
+        assert(isinstance(m, int ) and m != 0)
+        assert(isinstance(d, int ) and d != 0)
+        assert(o is None or isinstance(o, int ) or isinstance(o, float ))
+        self._m = float(m)
+        self._d = float(d)
+        if o:
+            self._o = float(o)
+
+    def compute(self, value):
+        ret_value = 0.0
+        if self._o:
+            ret_value += self._o
+        ret_value += (value * self._m / self._d)
+        return ret_value
+
+    def compute_reverse(self, value):
+        ret_value = float(value)
+        if self._o:
+            ret_value -= self._o
+        ret_value = (ret_value * self._d / self._m)
+        return ret_value
+
+    def __str__(self):
+        result = ''
+        if self._o:
+            result += '{}+'.format(self._o)
+        result += '{0}x/{1}'.format(self._m, self._d)
+        return result

tests/test_mdo.py

@@ -0,0 +1,28 @@
+import unittest2 as unittest
+
+from iotile_cloud.utils.mdo import *
+
+
+class MdoTestCase(unittest.TestCase):
+
+    def test_compute_mdo(self):
+        mdo = MdoHelper(m=1, d=1)
+        self.assertEqual(mdo.compute(5), 5)
+        self.assertEqual(mdo.compute(0), 0)
+        self.assertEqual(mdo.compute(-10), -10)
+
+        mdo = MdoHelper(m=3, d=2, o=0.5)
+        self.assertEqual(mdo.compute(5), 8.0)
+        self.assertEqual(mdo.compute(0), 0.5)
+        self.assertEqual(mdo.compute(-10), -14.5)
+
+    def test_reverse_compute_mdo(self):
+        mdo = MdoHelper(m=1, d=1)
+        self.assertEqual(mdo.compute_reverse(5), 5)
+        self.assertEqual(mdo.compute_reverse(0), 0)
+        self.assertEqual(mdo.compute_reverse(-10), -10)
+
+        mdo = MdoHelper(m=3, d=2, o=0.5)
+        self.assertEqual(mdo.compute_reverse(8.0), 5)
+        self.assertEqual(mdo.compute_reverse(0.5), 0)
+        self.assertEqual(mdo.compute_reverse(-14.5), -10)

version.py

@@ -1 +1 @@
-version = '0.7.2'
+version = '0.7.3'