mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-07-27 19:26:50 +00:00
Document statistics change to require either/both 'max_age' and 'sampling_size' (#24878)
This commit is contained in:
Thomas Dietrich
GitHub
parent
2593f294ea
commit
12b87e9db9
@ -18,21 +18,19 @@ ha_integration_type: integration
|
||||
|
||||
The `statistics` sensor platform observes the state of a source sensor and provides aggregated 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 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. A number of characteristics is supported by each, please check below.
|
||||
The statistics sensor updates with every update of the source sensor, for which the numeric `sensor` and `binary_sensor` are supported. The time period and/or number of recent state changes, which should be considered, must be given in configuration. Check the configuration section below for details.
|
||||
|
||||
Assuming the [`recorder`](/integrations/recorder/) integration is running, historical sensor data is read from the database on startup and is available immediately after a restart of the platform. If the [`recorder`](/integrations/recorder/) integration is *not* running, it can take some time for the sensor to start reporting data because some characteristics calculations require more than one source sensor value.
|
||||
|
||||
<div class='note tip'>
|
||||
|
||||
The `statistics` integration is different to a [Long-term Statistics](https://developers.home-assistant.io/docs/core/entity/sensor/#long-term-statistics). More details on the differences can be found in the [2021.8.0 release notes](/blog/2021/08/04/release-20218/#long-term-statistics).
|
||||
The `statistics` integration is different to [Long-term Statistics](https://developers.home-assistant.io/docs/core/entity/sensor/#long-term-statistics). More details on the differences can be found in the [2021.8.0 release notes](/blog/2021/08/04/release-20218/#long-term-statistics).
|
||||
|
||||
</div>
|
||||
|
||||
## Characteristics
|
||||
|
||||
The following statistical characteristics are available. 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/or `max_age`, as most characteristics are directly influenced by these settings.
|
||||
|
||||
### Numeric Source Sensor
|
||||
|
||||
@ -76,8 +74,8 @@ The following characteristic are supported for `binary_sensor` source sensors:
|
||||
| `average_step` | A percentage of time across all stored measurements, in which the binary source sensor was "On". If over the course of one hour, movement was detected for 6 minutes, the `average_step` is 10%.
|
||||
| `average_timeless` | The percentage of stored measurements, for which the binary source sensor was "On". Time in on/off states is ignored. If over the course of one hour, a single movement was detected, the `average_timeless` is 33.3% (assuming the stored measurements "Off", "On", "Off"). Equal to `mean`.
|
||||
| `count` | The number of stored source sensor readings.
|
||||
| `count_on` | The number of stored source sensor readings with the value "On". Be aware that only value changes are registered by default, except if the source sensor has the property `force_update`.
|
||||
| `count_off` | The number of stored source sensor readings with the value "Off". Be aware that only value changes are registered by default, except if the source sensor has the property `force_update`.
|
||||
| `count_on` | The number of stored source sensor readings with the value "On". Be aware that only value changes are registered by default, except if the source sensor has the property `force_update` set to true.
|
||||
| `count_off` | The number of stored source sensor readings with the value "Off". Be aware that only value changes are registered by default, except if the source sensor has the property `force_update` set to true.
|
||||
| `datetime_newest` | The timestamp of the newest measurement.
|
||||
| `datetime_oldest` | The timestamp of the oldest measurement.
|
||||
| `mean` | The percentage of stored measurements, for which the binary source sensor was "On". Time in on/off states is ignored. If over the course of one hour, a single movement was detected, the `average_timeless` is 33.3% (assuming the stored measurements "Off", "On", "Off").
|
||||
@ -89,7 +87,7 @@ A statistics sensor presents the following attributes for context about its inte
|
||||
| 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.
|
||||
| `buffer_usage_ratio` | Only when `sampling_size` is defined. Ratio (0.0-1.0) of the configured buffer 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
|
||||
@ -105,6 +103,11 @@ sensor:
|
||||
max_age:
|
||||
hours: 24
|
||||
|
||||
- platform: statistics
|
||||
entity_id: binary_sensor.movement
|
||||
state_characteristic: count_on
|
||||
sampling_size: 100
|
||||
|
||||
- platform: statistics
|
||||
name: "Bathroom humidity change over 5 minutes"
|
||||
entity_id: sensor.bathroom_humidity
|
||||
@ -113,10 +116,6 @@ sensor:
|
||||
minutes: 5
|
||||
sampling_size: 50
|
||||
precision: 1
|
||||
|
||||
- platform: statistics
|
||||
entity_id: binary_sensor.movement
|
||||
state_characteristic: count
|
||||
```
|
||||
|
||||
{% configuration %}
|
||||
@ -130,17 +129,15 @@ name:
|
||||
default: Stats
|
||||
type: string
|
||||
state_characteristic:
|
||||
description: The characteristic that should be used as the state of the statistics sensor (see table above). **Beware** that this parameter will become mandatory in a future version. Include in your configuration. If currently omitted, the default characteristic for a `sensor` source sensor is "mean", for a `binary_sensor` "count".
|
||||
required: false
|
||||
default: mean / count
|
||||
description: The characteristic that should be used as the state of the statistics sensor (see table above).
|
||||
required: true
|
||||
type: string
|
||||
sampling_size:
|
||||
description: Maximum number of source sensor measurements stored. Be sure to choose a reasonably high number if the limit should be driven by `max_age` instead.
|
||||
description: Maximum number of source sensor measurements stored. Be sure to choose a reasonably high number or omit if the samples should be driven by `max_age` instead. A statistics sensor requires `sampling_size`, `max_age`, or both to be defined.
|
||||
required: false
|
||||
default: 20
|
||||
type: integer
|
||||
max_age:
|
||||
description: Maximum age of source sensor measurements stored. Setting this to a time period will cause older values to be discarded. If omitted, the number of considered source sensor measurements is limited by `sampling_size` only. Set both parameters appropriately to create suited limits for your use case. The sensor value will become `unknown` if the source sensor is not updated within the time period.
|
||||
description: Maximum age of source sensor measurements stored. Setting this to a time period will cause older values to be discarded. If omitted, the number of considered source sensor measurements is limited by `sampling_size` only. Set both parameters appropriately to create suited limits for your use case. The sensor value will become `unknown` if the source sensor is not updated within the time period. A statistics sensor requires `sampling_size`, `max_age`, or both to be defined.
|
||||
required: false
|
||||
type: time
|
||||
percentile:
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user