Filter


The filter platform enables sensors that process the states of other entities.

filter applies a signal processing algorithm to a sensor, previous and current states, and generates a new state given the chosen algorithm. The next image depicts an original sensor and the filter sensor of that same sensor using the History Graph integration.

Configuration

To enable Filter Sensors in your installation, add the following to your configuration.yaml file:

# Example configuration.yaml entry
sensor:
  - platform: filter
    name: "filtered realistic humidity"
    entity_id: sensor.realistic_humidity
    filters:
      - filter: outlier
        window_size: 4
        radius: 4.0
      - filter: lowpass
        time_constant: 10
        precision: 2
  - platform: filter
    name: "filtered realistic temperature"
    entity_id: sensor.realistic_temperature
    filters:
      - filter: outlier
        window_size: 4
        radius: 2.0
      - filter: lowpass
        time_constant: 10
      - filter: time_simple_moving_average
        window_size: "00:05"
        precision: 2

Filters can be chained and are applied according to the order present in the configuration file.

Configuration Variables

entity_id string Required

The entity ID of the sensor to be filtered.

name string (Optional)

Name to use in the frontend.

unique_id string (Optional)

An ID that uniquely identifies the filter sensor. Set this to a unique value to allow customization through the UI.

filters list Required

Filters to be used.

filter string Required

Algorithm to be used to filter data. Available filters are lowpass, outlier, range, throttle, time_throttle and time_simple_moving_average.

precision integer (Optional, default: 2)

Defines the precision of the filtered state, through the argument of round().

window_size integer | time (Optional, default: 1)

Size of the window of previous states. Time based filters such as time_simple_moving_average will require a time period (size in time), while other filters such as outlier will require an integer (size in number of states). Time periods are in hh:mm format and must be quoted.

time_constant integer (Optional, default: 10)

See lowpass filter. Loosely relates to the amount of time it takes for a state to influence the output.

radius float (Optional, default: 2.0)

See outlier filter. Band radius from median of previous states.

type string (Optional, default: last)

See time_simple_moving_average filter. Defines the type of Simple Moving Average.

lower_bound float (Optional, default: negative infinity)

See range filter. Lower bound for filter range.

upper_bound float (Optional, default: positive infinity)

See range filter. Upper bound for filter range.

When configuring a window_size that is not a time and with a value larger than the default of 1, the database must examine nearly every stored state for that entity during Home Assistant startup. If you have modified the Recorder purge_keep_days value or have many states stored in the database for the filtered entity, this can cause your Home Assistant instance can to respond poorly during startup.

Filters

Low-pass

The Low-pass filter (lowpass) is one of signal processing most common filters, as it smooths data by shortcutting peaks and valleys.

The included Low-pass filter is very basic and is based on exponential smoothing, in which the previous data point is weighted with the new data point.

B = 1.0 / time_constant
A = 1.0 - B
LowPass(state) = A * previous_state + B * state

Outlier

The Outlier filter (outlier) is a basic Band-pass filter, as it cuts out any value outside a specific range.

The included Outlier filter will discard any value beyond a band centered on the median of the previous values, replacing it with the median value of the previous values. If inside the band, the current state is returned.

distance = abs(state - median(previous_states))

if distance > radius:
    median(previous_states)
else:
    state

Throttle

The Throttle filter (throttle) will only update the state of the sensor for the first state in the window. This means the filter will skip all other values.

To adjust the rate you need to set the window_size. To throttle a sensor down to 10%, the window_size should be set to 10, for 50% should be set to 2.

This filter is relevant when you have a sensor which produces states at a very high-rate, which you might want to throttle down for storing or visualization purposes.

Time throttle

The Time Throttle filter (time_throttle) will only update the state of the sensor for the first state in the window. This means the filter will skip all other values.

To adjust the rate you need to set the window_size. To throttle a sensor down to 1 value per minute, the window_size should be set to “00:01”.

This filter is relevant when you have a sensor which produces states at a very high inconstant rate, which you might want to throttle down to some constant rate for storing or visualization purposes.

Time Simple Moving Average

The Time SMA filter (time_simple_moving_average) is based on the paper Algorithms for Unevenly Spaced Time Series: Moving Averages and Other Rolling Operators by Andreas Eckner.

The paper defines three types/versions of the Simple Moving Average (SMA): last, next and linear. Currently only last is implemented.

Theta, as described in the paper, is the window_size parameter, and can be expressed using time notation (e.g., “00:05” for a five minutes time window).

Range

The Range filter (range) restricts incoming data to a range specified by a lower and upper bound.

All values greater then the upper bound are replaced by the upper bound and all values lower than the lower bound are replaced by the lower bound. Per default there are neither upper nor lower bound.

if new_state > upper_bound:
    upper_bound
if new_state < lower_bound:
    lower_bound
new_state