doc/derived_measurements.rst - platform/external/devlib - Gitiles

 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 ``DerivedMetric``'s.

 .. 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 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)

    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
 ~~~~~~~~~~~~~~

 .. class:: DerivedMetric

   Represents a metric derived from previously collected ``Measurement``s.
   Unlike, a ``Measurement``, this was not measured directly from the target.


 .. attribute:: DerivedMetric.name

    The name of the derived metric. This uniquely defines a metric -- two
    ``DerivedMetric`` objects with the same ``name`` represent to instances of
    the same metric (e.g. computed from two different inputs).

 .. attribute:: DerivedMetric.value

    The ``numeric`` value of the metric that has been computed for a particular
    input.

 .. attribute:: DerivedMetric.measurement_type

    The ``MeasurementType`` of the metric. This indicates which conceptual
    category the metric falls into, its units, and conversions to other
    measurement types.

 .. attribute:: DerivedMetric.units

    The units in which the metric's value is expressed.


 Available Derived Measurements
 -------------------------------

 .. 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.

    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)

    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"``.


 FPS / Rendering
 ~~~~~~~~~~~~~~~

 .. class:: DerivedGfxInfoStats(drop_threshold=5, suffix='-fps', filename=None, outdir=None)

    Produces FPS (frames-per-second) and other dervied statistics from
    :class:`GfxInfoFramesInstrument` output. This takes several optional
    parameters in creation:

    :param drop_threshold: FPS in an application, such as a game, which this
                           processor is primarily targeted at, cannot reasonably
                           drop to a very low value. This is specified to this
                           threhold. If an FPS for a frame is computed to be
                           lower than this treshold, it will be dropped on the
                           assumption that frame rednering was suspended by the
                           system (e.g. when idling), or there was some sort of
                           error, and therefore this should be used in
                           performance calculations. defaults to ``5``.
    :param  suffix: The name of the gerated per-frame FPS csv file will be
                    derived from the input frames csv file by appending this
                    suffix. This cannot be specified at the same time as
                    a ``filename``.
    :param filename: As an alternative to the suffix, a complete file name for
                     FPS csv can be specified. This cannot be used at the same
                     time as the ``suffix``.
    :param outdir: By default, the FPS csv file will be placed in the same
                   directory as the input frames csv file. This can be changed
                   by specifying an alternate directory here

    .. warning:: Specifying both ``filename`` and ``oudir`` will mean that exactly
                 the same file will be used for FPS output on each invocation of
                 ``process()`` (even for different inputs) resulting in previous
                 results being overwritten.

 .. method:: DerivedGfxInfoStats.process(measurement_csv)

    Process the fames csv generated by :class:`GfxInfoFramesInstrument` and
    returns a list containing exactly three entries: :class:`DerivedMetric`\ s
    ``fps`` and ``total_frames``, followed by a :class:`MeasurentCsv` containing
    per-frame FPSs values.

 .. method:: DerivedGfxInfoStats.process_raw(gfxinfo_frame_raw_file)

    As input, this takes a single argument, which should be the path to the raw
    output file of  :class:`GfxInfoFramesInstrument`. The returns stats
    accumulated by gfxinfo. At the time of wrinting, the stats (in order) are:
    ``janks``, ``janks_pc`` (percentage of all frames),
    ``render_time_50th_ptile`` (50th percentile, or median, for time to render a
    frame), ``render_time_90th_ptile``, ``render_time_95th_ptile``,
    ``render_time_99th_ptile``, ``missed_vsync``, ``hight_input_latency``,
    ``slow_ui_thread``, ``slow_bitmap_uploads``, ``slow_issue_draw_commands``.
    Please see the `gfxinfo documentation`_ for details.

 .. _gfxinfo documentation: https://developer.android.com/training/testing/performance.html


 .. class:: DerivedSurfaceFlingerStats(drop_threshold=5, suffix='-fps', filename=None, outdir=None)

    Produces FPS (frames-per-second) and other dervied statistics from
    :class:`SurfaceFlingerFramesInstrument` output. This takes several optional
    parameters in creation:

    :param drop_threshold: FPS in an application, such as a game, which this
                           processor is primarily targeted at, cannot reasonably
                           drop to a very low value. This is specified to this
                           threhold. If an FPS for a frame is computed to be
                           lower than this treshold, it will be dropped on the
                           assumption that frame rednering was suspended by the
                           system (e.g. when idling), or there was some sort of
                           error, and therefore this should be used in
                           performance calculations. defaults to ``5``.
    :param  suffix: The name of the gerated per-frame FPS csv file will be
                    derived from the input frames csv file by appending this
                    suffix. This cannot be specified at the same time as
                    a ``filename``.
    :param filename: As an alternative to the suffix, a complete file name for
                     FPS csv can be specified. This cannot be used at the same
                     time as the ``suffix``.
    :param outdir: By default, the FPS csv file will be placed in the same
                   directory as the input frames csv file. This can be changed
                   by specifying an alternate directory here

    .. warning:: Specifying both ``filename`` and ``oudir`` will mean that exactly
                 the same file will be used for FPS output on each invocation of
                 ``process()`` (even for different inputs) resulting in previous
                 results being overwritten.

 .. method:: DerivedSurfaceFlingerStats.process(measurement_csv)

    Process the fames csv generated by :class:`SurfaceFlingerFramesInstrument` and
    returns a list containing exactly three entries: :class:`DerivedMetric`\ s
    ``fps`` and ``total_frames``, followed by a :class:`MeasurentCsv` containing
    per-frame FPSs values, followed by ``janks`` ``janks_pc``, and
    ``missed_vsync`` metrics.
	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 ``DerivedMetric``'s.

	.. 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 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)

	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
	~~~~~~~~~~~~~~

	.. class:: DerivedMetric

	Represents a metric derived from previously collected ``Measurement``s.
	Unlike, a ``Measurement``, this was not measured directly from the target.


	.. attribute:: DerivedMetric.name

	The name of the derived metric. This uniquely defines a metric -- two
	``DerivedMetric`` objects with the same ``name`` represent to instances of
	the same metric (e.g. computed from two different inputs).

	.. attribute:: DerivedMetric.value

	The ``numeric`` value of the metric that has been computed for a particular
	input.

	.. attribute:: DerivedMetric.measurement_type

	The ``MeasurementType`` of the metric. This indicates which conceptual
	category the metric falls into, its units, and conversions to other
	measurement types.

	.. attribute:: DerivedMetric.units

	The units in which the metric's value is expressed.


	Available Derived Measurements
	-------------------------------

	.. 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.

	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)

	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"``.


	FPS / Rendering
	~~~~~~~~~~~~~~~

	.. class:: DerivedGfxInfoStats(drop_threshold=5, suffix='-fps', filename=None, outdir=None)

	Produces FPS (frames-per-second) and other dervied statistics from
	:class:`GfxInfoFramesInstrument` output. This takes several optional
	parameters in creation:

	:param drop_threshold: FPS in an application, such as a game, which this
	processor is primarily targeted at, cannot reasonably
	drop to a very low value. This is specified to this
	threhold. If an FPS for a frame is computed to be
	lower than this treshold, it will be dropped on the
	assumption that frame rednering was suspended by the
	system (e.g. when idling), or there was some sort of
	error, and therefore this should be used in
	performance calculations. defaults to ``5``.
	:param suffix: The name of the gerated per-frame FPS csv file will be
	derived from the input frames csv file by appending this
	suffix. This cannot be specified at the same time as
	a ``filename``.
	:param filename: As an alternative to the suffix, a complete file name for
	FPS csv can be specified. This cannot be used at the same
	time as the ``suffix``.
	:param outdir: By default, the FPS csv file will be placed in the same
	directory as the input frames csv file. This can be changed
	by specifying an alternate directory here

	.. warning:: Specifying both ``filename`` and ``oudir`` will mean that exactly
	the same file will be used for FPS output on each invocation of
	``process()`` (even for different inputs) resulting in previous
	results being overwritten.

	.. method:: DerivedGfxInfoStats.process(measurement_csv)

	Process the fames csv generated by :class:`GfxInfoFramesInstrument` and
	returns a list containing exactly three entries: :class:`DerivedMetric`\ s
	``fps`` and ``total_frames``, followed by a :class:`MeasurentCsv` containing
	per-frame FPSs values.

	.. method:: DerivedGfxInfoStats.process_raw(gfxinfo_frame_raw_file)

	As input, this takes a single argument, which should be the path to the raw
	output file of :class:`GfxInfoFramesInstrument`. The returns stats
	accumulated by gfxinfo. At the time of wrinting, the stats (in order) are:
	``janks``, ``janks_pc`` (percentage of all frames),
	``render_time_50th_ptile`` (50th percentile, or median, for time to render a
	frame), ``render_time_90th_ptile``, ``render_time_95th_ptile``,
	``render_time_99th_ptile``, ``missed_vsync``, ``hight_input_latency``,
	``slow_ui_thread``, ``slow_bitmap_uploads``, ``slow_issue_draw_commands``.
	Please see the `gfxinfo documentation`_ for details.

	.. _gfxinfo documentation: https://developer.android.com/training/testing/performance.html


	.. class:: DerivedSurfaceFlingerStats(drop_threshold=5, suffix='-fps', filename=None, outdir=None)

	Produces FPS (frames-per-second) and other dervied statistics from
	:class:`SurfaceFlingerFramesInstrument` output. This takes several optional
	parameters in creation:

	:param drop_threshold: FPS in an application, such as a game, which this
	processor is primarily targeted at, cannot reasonably
	drop to a very low value. This is specified to this
	threhold. If an FPS for a frame is computed to be
	lower than this treshold, it will be dropped on the
	assumption that frame rednering was suspended by the
	system (e.g. when idling), or there was some sort of
	error, and therefore this should be used in
	performance calculations. defaults to ``5``.
	:param suffix: The name of the gerated per-frame FPS csv file will be
	derived from the input frames csv file by appending this
	suffix. This cannot be specified at the same time as
	a ``filename``.
	:param filename: As an alternative to the suffix, a complete file name for
	FPS csv can be specified. This cannot be used at the same
	time as the ``suffix``.
	:param outdir: By default, the FPS csv file will be placed in the same
	directory as the input frames csv file. This can be changed
	by specifying an alternate directory here

	.. warning:: Specifying both ``filename`` and ``oudir`` will mean that exactly
	the same file will be used for FPS output on each invocation of
	``process()`` (even for different inputs) resulting in previous
	results being overwritten.

	.. method:: DerivedSurfaceFlingerStats.process(measurement_csv)

	Process the fames csv generated by :class:`SurfaceFlingerFramesInstrument` and
	returns a list containing exactly three entries: :class:`DerivedMetric`\ s
	``fps`` and ``total_frames``, followed by a :class:`MeasurentCsv` containing
	per-frame FPSs values, followed by ``janks`` ``janks_pc``, and
	``missed_vsync`` metrics.