From ba7bcd645239cc53d4b4761e7909ca15a8cff2e8 Mon Sep 17 00:00:00 2001 From: Scott Anderson Date: Tue, 6 Aug 2019 14:11:46 -0600 Subject: [PATCH] added holtWinters function --- .../transformations/aggregates/doubleema.md | 2 +- .../aggregates/exponentialmovingaverage.md | 2 +- .../transformations/aggregates/holtwinters.md | 114 ++++++++++++++++++ .../aggregates/movingaverage.md | 2 +- .../aggregates/relativestrengthindex.md | 2 +- .../transformations/aggregates/tripleema.md | 2 +- 6 files changed, 119 insertions(+), 5 deletions(-) create mode 100644 content/v2.0/reference/flux/functions/built-in/transformations/aggregates/holtwinters.md diff --git a/content/v2.0/reference/flux/functions/built-in/transformations/aggregates/doubleema.md b/content/v2.0/reference/flux/functions/built-in/transformations/aggregates/doubleema.md index 2c11353cf..88a99ef58 100644 --- a/content/v2.0/reference/flux/functions/built-in/transformations/aggregates/doubleema.md +++ b/content/v2.0/reference/flux/functions/built-in/transformations/aggregates/doubleema.md @@ -27,7 +27,7 @@ _**Function type:** Aggregate_ doubleEMA(n: 5) ``` -##### Double exponential moving average rules: +##### Double exponential moving average rules - A double exponential moving average is defined as `doubleEMA = 2 * EMA_N - EMA of EMA_N`. - `EMA` is an exponential moving average. - `N = n` is the period used to calculate the EMA. diff --git a/content/v2.0/reference/flux/functions/built-in/transformations/aggregates/exponentialmovingaverage.md b/content/v2.0/reference/flux/functions/built-in/transformations/aggregates/exponentialmovingaverage.md index 4694eb75c..c543ab342 100644 --- a/content/v2.0/reference/flux/functions/built-in/transformations/aggregates/exponentialmovingaverage.md +++ b/content/v2.0/reference/flux/functions/built-in/transformations/aggregates/exponentialmovingaverage.md @@ -25,7 +25,7 @@ _**Function type:** Aggregate_ exponentialMovingAverage(n: 5) ``` -##### Exponential moving average rules: +##### Exponential moving average rules - The first value of an exponential moving average over `n` values is the algebraic mean of `n` values. - Subsequent values are calculated as `y(t) = x(t) * k + y(t-1) * (1 - k)`, where: diff --git a/content/v2.0/reference/flux/functions/built-in/transformations/aggregates/holtwinters.md b/content/v2.0/reference/flux/functions/built-in/transformations/aggregates/holtwinters.md new file mode 100644 index 000000000..46829e1da --- /dev/null +++ b/content/v2.0/reference/flux/functions/built-in/transformations/aggregates/holtwinters.md @@ -0,0 +1,114 @@ +--- +title: holtWinters() function +description: > + The `holtWinters()` function applies the Holt-Winters forecasting method to input tables. +aliases: + - /v2.0/reference/flux/functions/transformations/aggregates/holtwinters +menu: + v2_0_ref: + name: holtWinters + parent: built-in-aggregates +weight: 501 +related: + - https://docs.influxdata.com/influxdb/latest/query_language/functions/#holt-winters, InfluxQL HOLT_WINTERS() +--- + +The `holtWinters()` function applies the Holt-Winters forecasting method to input tables. + +_**Function type:** Aggregate_ +_**Output data type:** Float_ + +```js +holtWinters( + n: 10, + seasonality: 4, + interval: 30d, + withFit: false, + timeColumn: "_time", + column: "_value", +) +``` + +The Holt-Winters method predicts [`n`](#n) seasonally-adjusted values for the +specified [`column`](#column) at the specified [`interval`](#interval). +For example, if `interval` is `6m` and `n` is `3`, results include three predicted +values six minutes apart. + +#### Seasonality +[`seasonality`](#seasonality) delimits the length of a seasonal pattern according to `interval`. +If your `interval` is `2m` and `s` is `3`, then the seasonal pattern occurs every +six minutes or every three data points. +If there is no seasonality in the data, set `seasonality` to `0`. + +#### Space values evenly in time +`holtWinters()` expects values evenly spaced in time. +To ensure this, it applies the following rules: + +- `interval` is used to divide the into buckets based time. +- If a bucket includes many values, the first value is used. +- If a bucket includes no values, a missing value (`null`) is added for that bucket. + +By default, `holtWinters()` uses the first value in each time bucket. +Use [`window()`](/v2.0/reference/flux/functions/built-in/transformations/window/) +and [selectors](/v2.0/reference/flux/functions/built-in/transformations/selectors/) +or [aggregates](/v2.0/reference/flux/functions/built-in/transformations/aggregates/), +or use [`aggregateWindow()`](/v2.0/reference/flux/functions/built-in/transformations/aggregates/aggregatewindow) +to specify other values to use in the `holtWinters()` calculation. + +#### Fitted model +The `holtWinters()` function applies the [Nelder-Mead optimization](https://en.wikipedia.org/wiki/Nelder%E2%80%93Mead_method) +to include "fitted" data points in results when [`withFit`](#withfit) is set to `true`. + +#### Null timestamps +`holtWinters()` discards rows with `null` timestamps before running the Holt-Winters calculation. + +#### Null values +`holtWinters()` treats `null` values as missing data points and includes them in the Holt-Winters calculation. + + +## Parameters + +### n +The number of values to predict. + +_**Data type: Integer**_ + +### seasonality +The number of points in a season. +Defaults to `0`. + +_**Data type: Integer**_ + +### interval +The interval between two data points. + +_**Data type: Duration**_ + +### withFit +Return [fitted data](#fitted-model) in results. +Defaults to `false`. + +_**Data type: Boolean**_ + +### timeColumn +The time column to use. +Defaults to `"_time"`. + +_**Data type: String**_ + +### column +The column to operate on. +Defaults to `"_value"`. + +_**Data type: String**_ + +## Examples + +##### Use aggregateWindow to prepare data for holtWinters +```js +from(bucket: "example-bucket") + |> range(start: -7y) + |> filter(fn: (r) => r._field == "water_level") + |> aggregateWindow(every: 379m, fn: first). + |> holtWinters(n: 10, seasonality: 4, interval: 379m) +``` diff --git a/content/v2.0/reference/flux/functions/built-in/transformations/aggregates/movingaverage.md b/content/v2.0/reference/flux/functions/built-in/transformations/aggregates/movingaverage.md index de1bc07ab..3ee8221c2 100644 --- a/content/v2.0/reference/flux/functions/built-in/transformations/aggregates/movingaverage.md +++ b/content/v2.0/reference/flux/functions/built-in/transformations/aggregates/movingaverage.md @@ -24,7 +24,7 @@ _**Function type:** Aggregate_ movingAverage(n: 5) ``` -##### Moving average rules: +##### Moving average rules - The average over a period populated by `n` values is equal to their algebraic mean. - The average over a period populated by only `null` values is `null`. - Moving averages skip `null` values. diff --git a/content/v2.0/reference/flux/functions/built-in/transformations/aggregates/relativestrengthindex.md b/content/v2.0/reference/flux/functions/built-in/transformations/aggregates/relativestrengthindex.md index 8ffb36750..d8f08460b 100644 --- a/content/v2.0/reference/flux/functions/built-in/transformations/aggregates/relativestrengthindex.md +++ b/content/v2.0/reference/flux/functions/built-in/transformations/aggregates/relativestrengthindex.md @@ -27,7 +27,7 @@ relativeStrengthIndex( ) ``` -##### Relative strength index rules: +##### Relative strength index rules - The general equation for calculating a relative strength index (RSI) is `RSI = 100 - (100 / (1 + (AVG GAIN / AVG LOSS)))`. - For the first value of the RSI, `AVG GAIN` and `AVG LOSS` are averages of the `n` period. diff --git a/content/v2.0/reference/flux/functions/built-in/transformations/aggregates/tripleema.md b/content/v2.0/reference/flux/functions/built-in/transformations/aggregates/tripleema.md index 6618acab7..cb084a607 100644 --- a/content/v2.0/reference/flux/functions/built-in/transformations/aggregates/tripleema.md +++ b/content/v2.0/reference/flux/functions/built-in/transformations/aggregates/tripleema.md @@ -29,7 +29,7 @@ _**Function type:** Aggregate_ tripleEMA(n: 5) ``` -##### Triple exponential moving average rules: +##### Triple exponential moving average rules - A triple exponential moving average is defined as `tripleEMA = (3 * EMA_1) - (3 * EMA_2) + EMA_3`. - `EMA_1` is the exponential moving average of the original data. - `EMA_2` is the exponential moving average of `EMA_1`.