From 60e69fc4e89cdf17649848729fd8b9add0e21a11 Mon Sep 17 00:00:00 2001
From: Marc Bonnici <marc.bonnici@arm.com>
Date: Fri, 18 Aug 2017 17:23:18 +0100
Subject: [PATCH] Documentation/DerivedMeasurements: Added documentation for
 new API

---
 doc/derived_measurements.rst | 69 ++++++++++++++++++++++++++++++++++++
 doc/index.rst                |  1 +
 2 files changed, 70 insertions(+)
 create mode 100644 doc/derived_measurements.rst

diff --git a/doc/derived_measurements.rst b/doc/derived_measurements.rst
new file mode 100644
index 0000000..fcd497c
--- /dev/null
+++ b/doc/derived_measurements.rst
@@ -0,0 +1,69 @@
+Derived Measurements
+=====================
+
+
+The ``DerivedMeasurements`` API provides a consistent way of performing post
+processing on a provided :class:`MeasurementCsv` file.
+
+Example
+-------
+
+The following example shows how to use an implementation of a
+:class:`DerivedMeasurement` to obtain a list of calculated ``Measurements``.
+
+.. code-block:: ipython
+
+    # Import the relevant derived measurement module
+    # in this example the derived energy module is used.
+    In [1]: from devlib import DerivedEnergyMeasurements
+
+    # Obtain a MeasurementCsv file from an instrument or create from
+    # existing .csv file. In this example an existing csv file is used which was
+    # created with a sampling rate of 100Hz
+    In [2]: from devlib import MeasurementsCsv
+    In [3]: measurement_csv = MeasurementsCsv('/example/measurements.csv', sample_rate_hz=100)
+
+    # Process the file and obtain a list of the derived measurements
+    In [4]: derived_measurements = DerivedEnergyMeasurements.process(measurement_csv)
+
+    In [5]: derived_measurements
+    Out[5]: [device_energy: 239.1854075 joules, device_power: 5.5494089227 watts]
+
+API
+---
+
+Derived Measurements
+~~~~~~~~~~~~~~~~~~~~
+
+.. class:: DerivedMeasurements()
+
+   The ``DerivedMeasurements`` class is an abstract base for implementing
+   additional classes to calculate various metrics.
+
+.. method:: DerivedMeasurements.process(measurement_csv)
+
+   Returns a list of :class:`Measurement` objects that have been calculated.
+
+
+
+Available Derived Measurements
+-------------------------------
+.. class:: DerivedEnergyMeasurements()
+
+  The ``DerivedEnergyMeasurements`` class is used to calculate average power and
+  cumulative energy for each site if the required data is present.
+
+  The calculation of cumulative energy can occur in 3 ways. If a
+  ``site`` contains ``energy`` results, the first and last measurements are extracted
+  and the delta calculated. If not, a ``timestamp`` channel will be used to calculate
+  the energy from the power channel, failing back to using the sample rate attribute
+  of the :class:`MeasurementCsv` file if timestamps are not available. If neither
+  timestamps or a sample rate are available then an error will be raised.
+
+
+.. method:: DerivedEnergyMeasurements.process(measurement_csv)
+
+  Returns a list of :class:`Measurement` objects that have been calculated for
+  the average power and cumulative energy for each site.
+
+
diff --git a/doc/index.rst b/doc/index.rst
index 2c6d72f..5f4dda5 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -19,6 +19,7 @@ Contents:
    target
    modules
    instrumentation
+   derived_measurements
    platform
    connection