DerivedMeasurements: add process_raw() + doc updates

- Add process_raw() method to the API. This is inteneded to be invoked
  on any raw output (i.e. not MeasurmentCsv) generated by an Instrument.
- Both process() process_raw() are portional to be overriden by
  impolementation; the default behavior is to return an empty list.
- The output specification for both is extened to allow
  MeasurementCsv's, as well as DerivedMetric's.
- Documentation has been reworded for clarity.

devlib/derived/__init__.py

@@ -53,6 +53,8 @@ class DerivedMetric(object):
 
 class DerivedMeasurements(object):
 
-    @staticmethod
-    def process(measurements_csv):
-        raise NotImplementedError()
+    def process(self, measurements_csv):
+        return []
+
+    def process_raw(self, *args):
+        return []

doc/derived_measurements.rst

@@ -35,14 +35,29 @@ API
 Derived Measurements
 ~~~~~~~~~~~~~~~~~~~~
 
-.. class:: DerivedMeasurements()
+.. class:: DerivedMeasurements
 
-   The ``DerivedMeasurements`` class is an abstract base for implementing
-   additional classes to calculate various metrics.
+   The ``DerivedMeasurements`` class provides an API for post-processing
+   instrument output offline (i.e. without a connection to the target device) to
+   generate additional metrics.
 
 .. method:: DerivedMeasurements.process(measurement_csv)
 
-   Returns a list of :class:`DerivedMetric` objects that have been calculated.
+   Process a :class:`MeasurementsCsv`, returning  a list of
+   :class:`DerivedMetric` and/or :class:`MeasurementsCsv` objects that have been
+   derived from the input. The exact nature and ordering of the list memebers
+   is specific to indivial 'class'`DerivedMeasurements` implementations.
+
+.. method:: DerivedMeasurements.process_raw(\*args)
+
+   Process raw output from an instrument, returnin a list :class:`DerivedMetric`
+   and/or :class:`MeasurementsCsv` objects that have been derived from the
+   input. The exact nature and ordering of the list memebers is specific to
+   indivial 'class'`DerivedMeasurements` implewmentations.
+
+   The arguents to this method should be paths to raw output files generated by
+   an instrument. The number and order of expected arguments is specific to
+   particular implmentations.
 
 
 Derived Metric
@@ -78,22 +93,34 @@ Derived Metric
 
 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.
+.. note:: If a method of the API is not documented for a particular
+          implementation, that means that it s not overriden by that
+          implementation. It is still safe to call it -- an empty list will be
+          returned.
 
-  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.
+Energy
+~~~~~~
+
+.. 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:`DerivedMetric` objects that have been calculated for
-  the average power and cumulative energy for each site.
-
+   This will return total cumulative energy for each energy channel, and the
+   average power for each power channel in the input CSV. The output will contain
+   all energy metrics followed by power metrics. The ordering of both will match
+   the ordering of channels in the input. The metrics will by named based on the
+   sites of the coresponding channels according to the following patters:
+   ``"<site>_total_energy"`` and ``"<site>_average_power"``.