# # Statistical Functions

## # Overview

The univariate statistical functions listed below perform calculations on an array of numeric values stored in a window.

Warning

The functions cannot be invoked in filter expressions.

Functions such as `countIf`, `avgIf`, and `sumIf` perform calculations on a subset of matching values in the current window based on a boolean condition.

## # Reference

### #`avg`

``````avg() double
``````

Calculates average value. For example, `avg()` for a `5-minute` time-based window returns the average value for all samples received within this period of time.

### #`mean`

``````mean() double
``````

Calculates average value. Same as `avg()`.

### #`sum`

``````sum() double
``````

Sums all included values.

### #`min`

``````min() double
``````

Returns minimum value.

### #`max`

``````max() double
``````

Returns maximum value.

### #`wavg`

``````wavg() double
``````

Calculates weighted average. Weight is the sample index which starts from `0` for the first sample. The function assigns more weight to more recent samples, based on the sample order.

### #`wtavg`

``````wtavg() double
``````

Calculates weighted time average where sample weight is calculated according to the following formula:

``````w = (command_time.millis - time_first())/(time_last() - time_first() + 1)
``````

Times are rounded to Unix seconds.

The function assigns more weight to more recent samples, based on the difference between sample time and window start.

### #`ema`

``````ema([double factor]) double
``````

Calculates exponential moving average from values present in the window. The optional smoothing `factor` must be within the `(0, 1)` range. the default `factor` is `0.25`.

The function assigns more weight to more recent samples.

### #`count`

``````count() long
``````

Returns the number of samples in the window, excluding samples with `NaN` value.

### #`countNaN`

``````countNaN() long
``````

Returns the number of `NaN` samples in the window.

### #`percentile`

``````percentile(double n) double
``````

Calculates `n`-th percentile according to the `R6` method which uses `N+1` as the array size (`N` is the number of samples in the period) and performs linear interpolation between consecutive values. `n` must be a fractional number within the `[0, 100]` range.

### #`median`

``````median() double
``````

Returns 50% percentile (median). Same as `percentile(50)`.

### #`variance`

``````variance() double
``````

Calculates variance.

#### #`stdev`

``````stdev() double
``````

Alias: `std_dev`.

Returns standard deviation calculated as an unbiased estimator of variance for the `n - 1` sample. ### #`intercept`

``````intercept() double
``````

Calculates linear regression intercept.

### #`median_abs_dev`

``````median_abs_dev() double
``````

Returns median absolute deviation, a `robust` estimate (resistant to outliers) of the variance calculated according to the following formula:

``````median(abs(value - median(value)))
``````

Examples:

``````median_abs_dev('5 minute')
median_abs_dev(10)
``````

### #`first`

``````first() double
``````

Returns first series value. Same as `first(0)`.

### #`first(int index)`

``````first(int index) double
``````

Returns `n`-th value from start. First value has index of `0`.

### #`last`

``````last() double
``````

Returns last value. Same as `last(0)`.

### #`last(int index)`

``````last(int index) double
``````

Returns `n`-th value from last value. Last value has index of `0`.

### #`diff`

``````diff() double
``````

Calculates difference between `last` and `first` values. Same as `last() - first()`.

### #`diff(int i)`

``````diff(int i) double
``````

Calculates difference between `last(integer i)` and `first(integer i)` values. Same as `last(integer i)-first(integer i)`.

### #`diff(string interval)`

``````diff(string interval) double
``````

Calculates difference between the last value and value at `currentTime - interval`.

`interval` specified as `count unit`, for example `5 minute`.

### #`delta`

``````delta() double
``````

Calculates difference between `last` and `first` values. Same as `diff()`.

### #`new_maximum`

``````new_maximum() bool
``````

Returns `true` if last value is greater than any previous value.

### #`new_minimum`

``````new_minimum() bool
``````

Returns `true` if last value is smaller than any previous value.

### #`threshold_time`

``````threshold_time(double t) double
``````

Forecasts the number of minutes until the sample value reaches the specified threshold `t` based on extrapolation of the difference between the last and first value.

### #`threshold_linear_time`

``````threshold_linear_time(double threshold) double
``````

Forecasts the number of minutes until the sample value reaches the specified `threshold` based on linear extrapolation.

### #`rate_per_second`

``````rate_per_second() double
``````

Calculates the difference between last and first value per second. Same as `diff()/(time_last()-time_first())`. Time measured in Unix seconds.

### #`rate_per_minute`

``````rate_per_minute() double
``````

Calculates the difference between last and first value per minute. Same as `rate_per_second()*60`.

### #`rate_per_hour`

``````rate_per_hour() double
``````

Calculates the hourly difference between last and first value input. Same as `rate_per_second()*3600`.

### #`slope`

``````slope() double
``````

Calculates linear regression slope.

### #`slope_per_second`

``````slope_per_second() double
``````

Calculates linear regression slope.

### #`slope_per_minute`

``````slope_per_minute() double
``````

Calculates `slope_per_second()/60`.

### #`slope_per_hour`

``````slope_per_hour() double
``````

Calculates `slope_per_second()/3600`.

### #`countIf`

``````countIf(string condition [, string interval | int n]) long
``````

Counts elements matching the specified `condition` within `interval` or within the last `n` samples.

Examples:

``````/* For values [0, 15, 5, 40] the function returns 2. */
countIf('value > 10')
``````
``````/* Count of values exceeding 5 within the last 10 samples. */
countIf('value > 5', 10)
``````

### #`avgIf`

``````avgIf(string condition [, string interval | int n]) double
``````

Calculates average of elements matching the specified `condition` within `interval` or within the last `n` samples.

### #`sumIf`

``````sumIf(string condition [, string interval | int n]) double
``````

Sums elements matching the specified `condition` within `interval` or within the last `n` samples.

## # Interval Selection

By default, statistical functions calculate results based on all samples stored in a window. The range of samples can be adjusted by passing an optional argument - specified as sample count `n` or `interval` - in which case the function calculates the result based on the most recent samples.

``````avg([string interval | int n]) double
``````
• `avg(5)`: Average value for the last 5 samples.
• `avg('1 HOUR')`: Average value for the last 1 hour.
• `max('2 minute')`: Maximum value for the last 2 minutes.
• `percentile(95, '1 hour')`: 95% percentile for the last hour.
• `countIf('value > 5', 10)`: Count of values exceeding 5 within the last 10 samples.

Example:

The condition evaluates to `true` if the 1-minute average is greater than the 1-hour average by more than `20` and a maximum is reached in the last 5 samples.

``````avg('1 minute') - avg() > 20 && max(5) = max()
``````