jeans/home-assistant.io
jeans/home-assistant.io
1
0
Fork 0
mirror of https://github.com/home-assistant/home-assistant.io.git synced 2025-07-23 17:27:19 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add additional statistics characteristics (#20347)

Browse Source
This commit is contained in:
Thomas Dietrich 2021-11-29 13:58:49 +01:00 committed by GitHub
parent d721c7731a
commit 7804582850
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 39 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

58
source/_integrations/statistics.markdown
View File

@ -14,9 +14,9 @@ ha_platforms:
- sensor
---
The `statistics` sensor platform observes the state of a source sensor and provides statistical characteristics about its recent past. This integration can be quite useful in automations, e.g., to trigger an action when the air humidity in the bathroom settles after a hot shower or when the number of brewed coffee over a day gets too high.
The `statistics` sensor platform observes the state of a source sensor and provides statistical characteristics about its recent past. This integration can be useful in automations, e.g., to trigger an action when the air humidity in the bathroom settles after a hot shower or when the number of brewed coffee over a day gets too high.
The created sensor presents one characteristic as its state (the `mean` value by default) and many more as attributes. The time period and/or number of recent state changes to be considered is defined as part of the sensor configuration. The sensor and its characteristics update with every source sensor update.
The statistics sensor updates with every source sensor update. The value of the sensor represents one statistical characteristic, with `mean` being the default. The time period and/or number of recent state that should be considered is an important factor here. Check the configuration section below for options.
Both `sensor` and `binary_sensor` are supported as source sensor. In the case of a binary sensor only the state changes are counted.
@ -24,28 +24,45 @@ Assuming the [`recorder`](/integrations/recorder/) integration is running, histo
## Characteristics
The following statistical characteristics are provided for the collected source sensor. Pay close attention to the right configuration of `sampling_size` and `max_age`, as most characteristics are directly related to the count of samples or the age of processed samples.
The following statistical characteristics are available. Pay close attention to the right configuration of `sampling_size` and `max_age`, as most characterists are directly related to the count of samples or the age of processed samples.
| Identifier | Description |
| ---------- | ----------- |
| State Characteristic | Description |
| -------------------- | ----------- |
| `average_linear` | The average value of stored measurements under consideration of the time distances between them. A linear interpolation is applied per measurement pair. Good suited to observe a source sensor with non-periodic sensor updates and when continuous behavior is represented by the measurements (e.g. outside temperature).
| `average_step` | The average value of stored measurements under consideration of the time distances between them. LOCF (last observation carried forward weighting) is applied, meaning, that the old value is assumed between two measurements. The resulting step function represents well the behavior of non-continuous behavior, like the set temperature of a boiler.
| `average_timeless` | The average value of stored measurements. This method assumes that all measurements are equally spaced and, therefore, time is ignored and a simple average of values is computed. Equal to `mean`.
| `change_sample` | The average change per sample. The difference between the oldest and newest measurement is divided by the number of in-between measurements (n-1).
| `change_second` | The average change per second. The difference between the oldest and newest measurement is divided by seconds between them.
| `change` | The difference between the oldest and newest measurement stored.
| `count` | The number of stored source sensor readings. This number is limited by `sampling_size` and can be low within the bounds of `max_age`.
| `total` | The sum of all source sensor measurements within the given time and sampling size limits.
| `datetime_newest` | The timestamp of the newest measurement stored.
| `datetime_oldest` | The timestamp of the oldest measurement stored.
| `distance_95_percent_of_values` | A statistical indicator derived from the standard deviation of an assumed normal distribution. 95% of all stored values fall into a range of returned size.
| `distance_99_percent_of_values` | A statistical indicator derived from the standard deviation of an assumed normal distribution. 99% of all stored values fall into a range of returned size.
| `distance_absolute` | The difference between the extreme values of measurements. Equals `value_max` minus `value_min`.
| `mean` | The average value computed for all measurements. Be aware that this does not take into account uneven time intervals between measurements.
| `median` | The [median](https://en.wikipedia.org/wiki/Mode_(statistics)#Comparison_of_mean,_median_and_mode) value computed for all measurements.
| `standard_deviation` | The [standard deviation](https://en.wikipedia.org/wiki/Standard_deviation) of an assumed normal distribution from all measurements.
| `variance` | The [variance](https://en.wikipedia.org/wiki/Standard_deviation) of an assumed normal distribution from all measurements.
| `min_value` | The smallest value among the number of measurements.
| `max_value` | The biggest value among the number of measurements.
| `min_age` | The timestamp of the oldest measurement stored.
| `max_age` | The timestamp of the newest measurement stored.
| `change` | The difference between the oldest and newest measurement stored.
| `average_change` | The difference between the oldest and newest measurement stored, divided by the number of in-between measurements (n-1).
| `change_rate` | The difference between the oldest and newest measurement stored, divided by seconds between them.
| `noisiness` | A simplified version of a signal-to-noise ratio. A high value indicates a quickly changing source sensor value, a small value will be seen for a steady source sensor. The absolute change between consecutive stored values is summed up and divided by the number of intervals.
| `quantiles` | Quantiles divide the range of a normal probability distribution of all considered source sensor measurements into continuous intervals with equal probabilities. Check the configuration parameters `quantile_intervals` and `quantile_method` for further details.
| `standard_deviation` | The [standard deviation](https://en.wikipedia.org/wiki/Standard_deviation) of an assumed normal distribution from all measurements.
| `total` | The sum of all source sensor measurements within the given time and sampling size limits.
| `value_max` | The biggest value among the number of measurements.
| `value_min` | The smallest value among the number of measurements.
| `variance` | The [variance](https://en.wikipedia.org/wiki/Standard_deviation) of an assumed normal distribution from all measurements.
## Attributes
A statistics sensor presents the following attributes for context about its internal status.
| Attribute | Description |
| --------- | ----------- |
| `age_coverage_ratio` | Only when `max_age` is defined. Ratio (0.0-1.0) of the configured age of source sensor measurements considered (time period `max_age`) covered in-between the oldest and newest stored values. A low number can indicate an unwanted mismatch between the configured limits and the source sensor behavior. The value 1.0 represents at least two values covering the full time period. Value 0 is the result of only one measurement considered. The sensor turns `Unknown` if no measurements are stored.
| `buffer_usage_ratio` | Ratio (0.0-1.0) of the configured buffer size (`sampling_size`) used by the stored source sensor measurements. A low number can indicate an unwanted mismatch between the configured limits and the source sensor behavior. The value 1.0 represents a full buffer, value 0 stands for an empty one.
| `source_value_valid` | True/false indication whether the source sensor supplies valid values to the statistics sensor (judged by the last value received).
## Configuration
Define a statistics sensor by adding the following lines to your `configuration.yaml`:
Define a statistics sensor by adding lines similar to the following examples to your `configuration.yaml`:
```yaml
sensor:
@ -54,13 +71,16 @@ sensor:
entity_id: sensor.bathroom_humidity
max_age:
hours: 24
- platform: statistics
name: "Bathroom humidity change over 5 minutes"
entity_id: sensor.bathroom_humidity
state_characteristic: change
max_age:
minutes: 5
state_characteristic: change
sampling_size: 50
precision: 1
- platform: statistics
entity_id: binary_sensor.movement
```
@ -76,7 +96,7 @@ name:
default: Stats
type: string
state_characteristic:
description: The characteristic that should be used as the state of the statistics sensor (see above). All other characteristics are provided as attributes.
description: The characteristic that should be used as the state of the statistics sensor (see table above).
required: false
default: mean
type: string
@ -95,7 +115,7 @@ precision:
default: 2
type: integer
quantile_intervals:
description: Number of continuous intervals with equal probability. Value must be an integer higher than `1`. In addition, `quantiles` will be `unknown` unless the number of quantile intervals is *lower* than the number of data points (`count`). Set it to `4` for quartiles (default) or to `100` for percentiles, for example.
description: Number of continuous intervals with equal probability. Value must be an integer higher than `1`. In addition, `quantiles` will be `unknown` unless the number of quantile intervals is *lower* than the number of data points (`count`). Set it to `4` for quartiles (default) or to `100` for percentiles, for example.
required: false
default: 4
type: integer