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.
diff --git a/devlib/derived/__init__.py b/devlib/derived/__init__.py
index 5f7dc6e..24ac060 100644
--- a/devlib/derived/__init__.py
+++ b/devlib/derived/__init__.py
@@ -53,6 +53,8 @@
class DerivedMeasurements(object):
- @staticmethod
- def process(measurements_csv):
- raise NotImplementedError()
+ def process(self, measurements_csv):
+ return []
+
+ def process_raw(self, *args):
+ return []
diff --git a/doc/derived_measurements.rst b/doc/derived_measurements.rst
index 02a6daa..285bce6 100644
--- a/doc/derived_measurements.rst
+++ b/doc/derived_measurements.rst
@@ -35,14 +35,29 @@
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 @@
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"``.