added unit_of_measurement and lambdas

Author: David Buezas

dist/plotly-graph-card.js

@@ -9,10 +9,9 @@ You may find some extra info there in this link
 
 ## Share and see what others are doing with this
 
-Check out the [Discussion](https://github.com/dbuezas/lovelace-plotly-graph-card/discussions) section  (new!)
+Check out the [Discussion](https://github.com/dbuezas/lovelace-plotly-graph-card/discussions) section (new!)
 Eventually I hope we accumulate a bunch of nice looking plots and yaml examples there :)
 
-
 ## Install through HACS
 
 1. Go to `HACS` / `Frontend` / `click [⋮] on the top right` / `Custom Repositories`
@@ -108,15 +107,110 @@ For now only the only allowed chart types are:
 - Bar charts https://plotly.com/javascript/bar-charts/#basic-bar-chart
 - Line and scatter https://plotly.com/javascript/line-and-scatter/
 
-## entities:
+## Entities:
 
 - `entities` translates to the `data` argument in PlotlyJS
 
   - each `entity` will be translated to a trace inside the data array.
     - `x` (states) and `y` (timestamps of stored states)
-    - you can add any attribute that works in a trace
+    - you can add any attribute that works in a plotly trace
+    - see https://plotly.com/javascript/reference/scatter/#scatter-line for more
+
+```yaml
+entities:
+  - entity: sensor.temperature
+  - entity: sensor.humidity
+```
+
+## Extra entity attributes:
+
+```yaml
+entities:
+  - entity: sensor.temperature_in_celsius
+    name: living temperature in Farenheit # Overrides the entity name
+    lambda: |- # Transforms the data
+      (ys) => ys.map(y => (y × 9/5) + 32)
+    unit_of_measurement: °F # Overrides the unit
+```
+
+### `lambda:` transforms
+
+`lambda` takes a js function (as a string) to pre process the data before plotting it. Here you can do things like normalisation, integration. For example:
+
+#### Normalisation wrt to last
 
-- see https://plotly.com/javascript/reference/scatter/#scatter-line for more
+```yaml
+type: custom:plotly-graph
+entities:
+  - entity: sensor.my_sensor
+     lambda: |-
+        (ys) => ys.map(y => y/ys[ys.length-1])
+```
+
+#### Normalisation wrt to first fetched value
+
+```yaml
+  - entity: sensor.my_sensor
+     lambda: |-
+        (ys) => ys.map(y => y/ys[0])
+```
+
+note: `ys[0]` represents the first "known" value, which is the value furthest to the past among the downloaded data. This value will change if you scroll, zoom out, change the hours_to_show, or just let time pass.
+
+#### Accumulated value
+
+```yaml
+  - entity: sensor.my_sensor
+     unit_of_measurement: "total pulses"
+     lambda: |-
+        (ys) => {
+          let accumulator = 0;
+          return ys.map(y => accumulator + y)
+        }
+```
+
+#### Derivative
+
+```yaml
+  - entity: sensor.my_sensor
+     unit_of_measurement: "pulses / second"
+     lambda: |-
+        (ys, xs) => {
+          let last = {
+            x: new Date(),
+            y: 0,
+          }
+          return ys.map((y, index) => {
+            const x = xs[index];
+            const dateDelta = x - last.x;
+            accumulator += (y - last.y) / dateDelta;
+            last = { x, y };
+            return accumulator;
+          })
+        }
+```
+
+#### Right hand riemann integration
+
+```yaml
+  - entity: sensor.my_sensor
+     unit_of_measurement: "kWh"
+     lambda: |-
+        (ys, xs) => {
+          let accumulator = 0;
+          let last = {
+            x: new Date(),
+            y: 0,
+          }
+          return ys.map((y, index) => {
+            const x = xs[index]
+            const dateDelta = x - last.x;
+            accumulator += last.y * dateDelta;
+            last = { x, y };
+            return accumulator;
+          })
+        }
+```
 
 ## layout:
 

readme.md

@@ -183,6 +183,10 @@ export class PlotlyGraph extends HTMLElement {
     config.entities = config.entities.map((entity) =>
       typeof entity === "string" ? { entity } : entity
     );
+    config.entities = config.entities.map((entity) => ({
+      ...entity,
+      lambda: entity.lambda ? window.eval(entity.lambda) : (y: number[]) => y,
+    }));
     if (config.title) {
       config = {
         ...config,
@@ -218,9 +222,22 @@ export class PlotlyGraph extends HTMLElement {
     );
     while (!this.hass) await sleep(100);
     await this.cache.update(range, !this.isBrowsing, entityNames, this.hass);
-
     await this.plot();
   };
+  getAllUnitsOfMeasurement() {
+    const all = this.config.entities.map(({ entity }) =>
+      this.getUnitOfMeasurement(entity)
+    );
+    return Array.from(new Set(all));
+  }
+  getUnitOfMeasurement(entityName: string) {
+    return (
+      this.config.entities.find((trace) => trace.entity === entityName)
+        ?.unit_of_measurement ||
+      this.cache.attributes[entityName]?.unit_of_measurement ||
+      ""
+    );
+  }
   getThemedLayout() {
     const styles = window.getComputedStyle(this.contentEl);
     let haTheme = {
@@ -238,17 +255,19 @@ export class PlotlyGraph extends HTMLElement {
     const entities = this.config.entities;
     const { histories, attributes } = this.cache;
 
-    const units = Array.from(
-      new Set(Object.values(attributes).map((a) => a.unit_of_measurement))
-    );
+    const units = this.getAllUnitsOfMeasurement();
 
     return entities.map((trace) => {
       const entity_id = trace.entity;
       const history = histories[entity_id] || {};
       const attribute = attributes[entity_id] || {};
-      const unit = attribute.unit_of_measurement;
+      const unit = this.getUnitOfMeasurement(entity_id);
       const yaxis_idx = units.indexOf(unit);
       const name = trace.name || attribute.friendly_name || entity_id;
+      const xs = history.map(({ last_changed }) => new Date(last_changed));
+      const ys = history.map(({ state }) =>
+        state === "unavailable" ? undefined : state
+      );
       return merge(
         {
           entity_id,
@@ -259,10 +278,8 @@ export class PlotlyGraph extends HTMLElement {
             width: 1,
             shape: "hv",
           },
-          x: history.map(({ last_changed }) => new Date(last_changed)),
-          y: history.map(({ state }) =>
-            state === "unavailable" ? undefined : state
-          ),
+          x: xs,
+          y: trace.lambda(ys, xs),
           yaxis: "y" + (yaxis_idx == 0 ? "" : yaxis_idx + 1),
         },
         trace
@@ -272,9 +289,7 @@ export class PlotlyGraph extends HTMLElement {
 
   getLayout(): Plotly.Layout {
     const { attributes } = this.cache;
-    const units = Array.from(
-      new Set(Object.values(attributes).map((a) => a.unit_of_measurement))
-    );
+    const units = this.getAllUnitsOfMeasurement();
 
     const yAxisTitles = Object.fromEntries(
       units.map((unit, i) => ["yaxis" + (i == 0 ? "" : i + 1), { title: unit }])

src/plotly-graph-card.ts

@@ -4,6 +4,8 @@ export type Config = {
   refresh_interval?: number; // in seconds
   entities: (Partial<Plotly.PlotData> & {
     entity: string;
+    unit_of_measurement?: string;
+    lambda: (y: any[], x: Date[]) => number[];
   })[];
   layout?: Partial<Plotly.Layout>;
   config?: Partial<Plotly.Config>;