trend
=====

.. py:module:: trend

.. autoapi-nested-parse::

   Trends of tile values: rising or falling over up to three hours.

   The board keeps a short history per source itself, so trends work with
   any data source and cost no extra request: at most one sample every
   SAMPLE_INTERVAL_S, dropped once older than SPAN_S. It does so for every
   number tile, so an arrow can appear as soon as a tile's trend is switched
   on. A trend compares the current value with the oldest sample: in steady
   operation one from three hours ago, after a restart the oldest there is,
   so a trend shows up within half an hour.

   The history is a dict {source ID: [[time s, value], ...]}, oldest first,
   stored as JSON on flash between wakes (HISTORY_FILE); it only changes
   when a sample is added, so the file is written at most every half hour.



Attributes
----------

.. autoapisummary::

   trend.HISTORY_FILE
   trend.SAMPLE_INTERVAL_S
   trend.SPAN_S
   trend.SLACK_S
   trend.UP
   trend.DOWN


Functions
---------

.. autoapisummary::

   trend.record
   trend.direction
   trend.sources
   trend.annotate
   trend.load
   trend.save


Module Contents
---------------

.. py:data:: HISTORY_FILE
   :value: 'trend.json'


.. py:data:: SAMPLE_INTERVAL_S
   :value: 1800


.. py:data:: SPAN_S
   :value: 10800


.. py:data:: SLACK_S
   :value: 60


.. py:data:: UP
   :value: 'up'


.. py:data:: DOWN
   :value: 'down'


.. py:function:: record(history, readings, sources, now_s)

   Add the current values of `sources` to `history`.

   :param history: The previous history, or None.
   :param readings: Current readings {source ID: {"value": ...}}.
   :param sources: Source IDs to keep a history for.
   :param now_s: Current time in seconds.

   :returns: The new history; sources no longer asked for are dropped.


.. py:function:: direction(samples, value, now_s, threshold)

   Return UP, DOWN or None (steady, or no older value yet).

   :param samples: The history of one source (see `record`).
   :param value: The current value.
   :param now_s: Current time in seconds.
   :param threshold: Smallest change that counts as a trend.


.. py:function:: sources(tile_config)

   Source IDs to keep a history for: those of number tiles, each once.


.. py:function:: annotate(layout_tiles, history, readings, now_s)

   Set "arrow" (UP, DOWN or None) on layout tiles that have a "trend".

   :param layout_tiles: Tiles as tiles.to_layout returns them; changed in place.
   :param history: The history (see `record`).
   :param readings: Current readings {source ID: {"value": ...}}.
   :param now_s: Current time in seconds.


.. py:function:: load(path=HISTORY_FILE)

   Return the saved history, or an empty one.


.. py:function:: save(history, path=HISTORY_FILE)

   Store the history; a power cut leaves the previous file intact.