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(self, measurements_csv):
-    def process(measurements_csv):
+        return []
-        raise NotImplementedError()
+
+    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
+   The ``DerivedMeasurements`` class provides an API for post-processing
-   additional classes to calculate various metrics.
+   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,7 +93,16 @@ Derived Metric
 
 Available Derived Measurements
 -------------------------------
-.. class:: DerivedEnergyMeasurements()
+
+.. 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.
+
+Energy
+~~~~~~
+
+.. class:: DerivedEnergyMeasurements
 
    The ``DerivedEnergyMeasurements`` class is used to calculate average power and
    cumulative energy for each site if the required data is present.
@@ -93,7 +117,10 @@ Available Derived Measurements
 
 .. method:: DerivedEnergyMeasurements.process(measurement_csv)
 
-  Returns a list of :class:`DerivedMetric` objects that have been calculated for
+   This will return total cumulative energy for each energy channel, and the
-  the average power and cumulative energy for each site.
+   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"``.