# Statistical Forecast Functions

## Overview

## Reference

`forecast`

`forecast_stdev`

`forecast_score_stdev`

`forecast_score_deviation`

`forecast_deviation`

`thresholdTime`

`forecast()`

```
forecast([string name]) object
```

Returns forecast object for the entity, metric, and tags in the current window. The object contains neighboring forecast periods based on `time`

field calculated by subtracting 50% of the forecast period from the window center (`windowTime`

).

If the `name`

is specified, the forecast object is retrieved for the named forecast settings.

The object contains the following fields:

`previous`

- Previous period value.`next`

- Next period value.`min`

- Minimum of the previous and the next period values.`max`

- Maximum of the previous and the next period values.`linear`

- Linearly interpolated value between previous and next periods based on`time`

field.`windowTime`

- Window center time calculated as average of first and last timestamps in the current window.`time`

- Forecast time calculated as`windowTime - 0.50*forecast_series_period`

.`previousTime`

- Previous period start time.`nextTime`

- Next period start time.

Parameter | Time | Date |
---|---|---|

`command.time` | `1550082342000` | `2019-02-13 18:25:56` |

`previousTime` | `1550080800000` | `2019-02-13 18:00:00` |

`nextTime` | `1550081700000` | `2019-02-13 18:15:00` |

`windowTime` | `1550081922000` | `2019-02-13 18:18:42` |

`time` | `1550081472000` | `2019-02-13 18:11:12` |

The `violates()`

function in the forecast object returns `true`

if the input value deviates by more than the specified delta from the `min`

and `max`

range. The delta must be a non-negative number.

```
violates(double a, double delta) {
return a < min - delta || a > max + delta;
}
```

Example:

```
violates(avg(), 10)
```

`forecast_stdev`

```
forecast_stdev() double
```

Returns forecast standard deviation.

`forecast_score_stdev`

Returns the standard deviation of actual aggregated values from the best fitting forecast values within the scoring interval.

Scoring is a procedure that identifies parameters that produce the best fitting forecast with the smallest standard deviation from observed aggregated values.

```
forecast_score_stdev(string name) double
```

`forecast_score_deviation`

```
forecast_score_deviation(string name, double a) double
```

Returns the difference between a number `a`

(such as the last value, or moving average `avg()`

) and the `forecast().interpolated`

value, divided by the forecast score standard deviation.

The function returns `NaN`

if either forecast or forecast score standard deviation cannot be retrieved, or if the standard deviation is zero.

The formula is:

```
(a - forecast(name).interpolated/forecast_score_stdev(name)
```

`forecast_deviation`

```
forecast_deviation(number a) double
```

Returns difference between a number `a`

and the `forecast().interpolated`

value, divided by the forecast standard deviation.

```
(a - forecast().interpolated)/forecast_stdev()
```

`thresholdTime`

```
thresholdTime(number min, number max [, string interval]) long
```

Returns Unix time in milliseconds when the stored forecast value is outside of the `(min, max)`

range for the first time during time interval `interval`

.

`interval`

is specified as count and unit, for example `1 WEEK`

. If `interval`

is not specified, the function checks all forecast values in the future.

Thresholds `min`

and `max`

are ignored by the function if either is set to `null`

. If both `min`

and `max`

are specified, the following rules apply:

- If threshold
`max`

is equal or greater than`min`

, the function returns time when the forecast value is**outside**of the specified range. - If threshold
`min`

exceeds`max`

, the function returns time when the forecast value is**within**the specified range.

The function returns `null`

if no stored forecast is found in the database.

### Example

```
/* Returns time, within the next 6 hours, when the forecast exceeds 90.
Returns `null`, if all forecast values are below 90 or the violation occurs after the `6 HOUR` window. */
thresholdTime(null, 90, '6 HOUR')
```

### Example Table

Current time is `2018-Jul-07 15:00`

, or `1530975600000`

in Unix time (milliseconds).

Forecast Values:

Value | Date | Time | Note |
---|---|---|---|

`70` | `2018-Jul-08 15:00` | `1530975600000` | 1 day from `now` |

`80` | `2018-Jul-09 15:00` | `1531148400000` | 2 days from `now` |

`90` | `2018-Jul-10 15:00` | `1531234800000` | 3 days from `now` |

`100` | `2018-Jul-16 15:00` | `1531753200000` | 9 days from `now` |

```
/* Returns 1531753200000 (2018-Jul-16 15:00)
First time when the forecast 100 exceeds 'max' threshold 95 */
thresholdTime(null, 95)
```

```
/* Returns null. No forecast value exceeds 120. */
thresholdTime(null, 120)
```

```
/* Returns null. No forecast value exceeds 95 within the next 7 days, by 2018-Jul-14 15:00. */
thresholdTime(null, 95, '7 DAY')
```

```
/* Returns 1531234800000 (2018-Jul-10 15:00).
First time when the forecast 90 exceeds 'max' threshold 80.
Forecast 80 on 2018-Jul-09 15:00 is ignored as not exceeding the threshold. */
thresholdTime(null, 80, '7 DAY')
```

```
/* Returns 1530975600000 (2018-Jul-08 15:00).
First time when the forecast 70 is below 'min' threshold 80. */
thresholdTime(80, null, '7 DAY')
```

```
/* Returns 1531753200000 (2018-Jul-16 15:00)
Outside range check: case when 'max' threshold is greater than 'min' threshold.
First time when the forecast 100 is either below 70 OR above 90. */
thresholdTime(70, 90)
```

```
/* Returns 1531148400000 (2018-Jul-09 15:00)
Within range check: case when 'min' threshold is greater than 'max' threshold.
First time when the forecast 80 is BOTH above 'max' threshold 70 AND below 'min' threshold 90. */
thresholdTime(90, 70)
```

```
/* Returns 1531148400000 (2018-Jul-09 15:00)
Case when 'min' threshold equals 'max' threshold.
First time when the forecast 80 is either below 70 (false) OR above 70 (true). */
thresholdTime(70, 70)
```