From ef92659856f4f4a8b4381f662981ec7bde3b81f3 Mon Sep 17 00:00:00 2001 From: Scott Anderson Date: Tue, 16 Jul 2019 15:31:10 -0600 Subject: [PATCH 01/17] added doubleExponentialMovingAverate() function, resolves #329 --- .../transformations/aggregates/doubleema.md | 67 +++++++++++++++++++ 1 file changed, 67 insertions(+) create mode 100644 content/v2.0/reference/flux/functions/built-in/transformations/aggregates/doubleema.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 new file mode 100644 index 000000000..12f7ecc6a --- /dev/null +++ b/content/v2.0/reference/flux/functions/built-in/transformations/aggregates/doubleema.md @@ -0,0 +1,67 @@ +--- +title: doubleEMA() function +description: > + The `doubleEMA()` or `doubleExponentialMovingAverage()` function calculates the + exponential moving average of values grouped into `n` number of points, + giving more weight to recent data at double the rate of `exponentialMovingAverage()`. +menu: + v2_0_ref: + name: doubleEMA + parent: built-in-aggregates +weight: 501 +related: + - /v2.0/reference/flux/functions/built-in/transformations/aggregates/movingaverage/ + - /v2.0/reference/flux/functions/built-in/transformations/aggregates/timedmovingaverage/ + - /v2.0/reference/flux/functions/built-in/transformations/aggregates/exponentialmovingaverage/ + - https://docs.influxdata.com/influxdb/v1.7/query_language/functions/#exponential-moving-average, InfluxQL EXPONENTIAL_MOVING_AVERAGE() +--- + +The `doubleEMA()` or `doubleExponentialMovingAverage()` function calculates the +exponential moving average (EMA) of values grouped into `n` number of points, +giving more weight to recent data at double the rate of +[`exponentialMovingAverage()`](/v2.0/reference/flux/functions/built-in/transformations/aggregates/exponentialmovingaverage/). + +_**Function type:** Aggregate_ + +```js +doubleExponentialMovingAverage( + n: 5, + columns: ["_value"] +) + +// OR + +doubleEMA( + n: 5, + columns: ["_value"] +) +``` + +##### 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. +- A true double exponential moving average requires at least `2 * n - 1` values. + If not enough values exist to calculate the double EMA, it returns a `NaN` value. +- `doubleEMA()` inherits all [exponential moving average rules](/v2.0/reference/flux/functions/built-in/transformations/aggregates/exponentialmovingaverage/#exponential-moving-average-rules). + +## Parameters + +### n +The number of points to average. + +_**Data type:** Integer_ + +### columns +Columns to operate on. _Defaults to `["_value"]`_. + +_**Data type:** Array of Strings_ + +## Examples + +#### Calculate a five point double exponential moving average +```js +from(bucket: "example-bucket"): + |> range(start: -12h) + |> doubleExponentialMovingAverage(n: 5) +``` From 481652c9d908084a514b69b3644aca44e860ee75 Mon Sep 17 00:00:00 2001 From: Scott Anderson Date: Tue, 16 Jul 2019 15:34:26 -0600 Subject: [PATCH 02/17] added related links to moving average functions --- .../built-in/transformations/aggregates/movingaverage.md | 2 ++ .../built-in/transformations/aggregates/timedmovingaverage.md | 2 ++ 2 files changed, 4 insertions(+) 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 60c08af83..1af19070a 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 @@ -9,6 +9,8 @@ menu: weight: 501 related: - /v2.0/reference/flux/functions/built-in/transformations/aggregates/timedmovingaverage/ + - /v2.0/reference/flux/functions/built-in/transformations/aggregates/exponentialmovingaverage/ + - /v2.0/reference/flux/functions/built-in/transformations/aggregates/doubleema/ - https://docs.influxdata.com/influxdb/latest/query_language/functions/#moving-average, InfluxQL MOVING_AVERAGE() --- diff --git a/content/v2.0/reference/flux/functions/built-in/transformations/aggregates/timedmovingaverage.md b/content/v2.0/reference/flux/functions/built-in/transformations/aggregates/timedmovingaverage.md index acaedcbe8..1809552ac 100644 --- a/content/v2.0/reference/flux/functions/built-in/transformations/aggregates/timedmovingaverage.md +++ b/content/v2.0/reference/flux/functions/built-in/transformations/aggregates/timedmovingaverage.md @@ -10,6 +10,8 @@ menu: weight: 501 related: - /v2.0/reference/flux/functions/built-in/transformations/aggregates/movingaverage/ + - /v2.0/reference/flux/functions/built-in/transformations/aggregates/exponentialmovingaverage/ + - /v2.0/reference/flux/functions/built-in/transformations/aggregates/doubleema/ - https://docs.influxdata.com/influxdb/latest/query_language/functions/#moving-average, InfluxQL MOVING_AVERAGE() --- From 1dc00f2ec8f7d5e577f4c80907788688603fcd56 Mon Sep 17 00:00:00 2001 From: Scott Anderson Date: Tue, 23 Jul 2019 15:42:48 -0600 Subject: [PATCH 03/17] added new date package functions --- .../flux/functions/date/microsecond.md | 31 +++++++++ .../flux/functions/date/millisecond.md | 31 +++++++++ .../flux/functions/date/nanosecond.md | 31 +++++++++ .../reference/flux/functions/date/quarter.md | 31 +++++++++ .../reference/flux/functions/date/truncate.md | 57 ++++++++++++++++ .../reference/flux/functions/date/week.md | 31 +++++++++ .../visualization-types/single-stat.md | 65 ------------------- 7 files changed, 212 insertions(+), 65 deletions(-) create mode 100644 content/v2.0/reference/flux/functions/date/microsecond.md create mode 100644 content/v2.0/reference/flux/functions/date/millisecond.md create mode 100644 content/v2.0/reference/flux/functions/date/nanosecond.md create mode 100644 content/v2.0/reference/flux/functions/date/quarter.md create mode 100644 content/v2.0/reference/flux/functions/date/truncate.md create mode 100644 content/v2.0/reference/flux/functions/date/week.md delete mode 100644 content/v2.0/visualize-data/visualization-types/single-stat.md diff --git a/content/v2.0/reference/flux/functions/date/microsecond.md b/content/v2.0/reference/flux/functions/date/microsecond.md new file mode 100644 index 000000000..6a1226250 --- /dev/null +++ b/content/v2.0/reference/flux/functions/date/microsecond.md @@ -0,0 +1,31 @@ +--- +title: date.microsecond() function +description: > + The `date.microsecond()` function returns the microsecond of a specified time. + Results range from `[0-999999]`. +menu: + v2_0_ref: + name: date.microsecond + parent: Date +weight: 301 +--- + +The `date.microsecond()` function returns the microsecond of a specified time. +Results range from `[0-999999]`. + +_**Function type:** Transformation_ + +```js +import "date" + +date.microsecond(t: 2019-07-17T12:05:21.012934584Z) + +// Returns 12934 +``` + +## Parameters + +### t +The time to operate on. + +_**Data type:** Time_ diff --git a/content/v2.0/reference/flux/functions/date/millisecond.md b/content/v2.0/reference/flux/functions/date/millisecond.md new file mode 100644 index 000000000..cc3645240 --- /dev/null +++ b/content/v2.0/reference/flux/functions/date/millisecond.md @@ -0,0 +1,31 @@ +--- +title: date.millisecond() function +description: > + The `date.millisecond()` function returns the millisecond of a specified time. + Results range from `[0-999999]`. +menu: + v2_0_ref: + name: date.millisecond + parent: Date +weight: 301 +--- + +The `date.millisecond()` function returns the millisecond of a specified time. +Results range from `[0-999]`. + +_**Function type:** Transformation_ + +```js +import "date" + +date.millisecond(t: 2019-07-17T12:05:21.012934584Z) + +// Returns 12 +``` + +## Parameters + +### t +The time to operate on. + +_**Data type:** Time_ diff --git a/content/v2.0/reference/flux/functions/date/nanosecond.md b/content/v2.0/reference/flux/functions/date/nanosecond.md new file mode 100644 index 000000000..21f42bdd7 --- /dev/null +++ b/content/v2.0/reference/flux/functions/date/nanosecond.md @@ -0,0 +1,31 @@ +--- +title: date.nanosecond() function +description: > + The `date.nanosecond()` function returns the nanosecond of a specified time. + Results range from `[0-999999999]`. +menu: + v2_0_ref: + name: date.nanosecond + parent: Date +weight: 301 +--- + +The `date.nanosecond()` function returns the nanosecond of a specified time. +Results range from `[0-999999999]`. + +_**Function type:** Transformation_ + +```js +import "date" + +date.nanosecond(t: 2019-07-17T12:05:21.012934584Z) + +// Returns 12934584 +``` + +## Parameters + +### t +The time to operate on. + +_**Data type:** Time_ diff --git a/content/v2.0/reference/flux/functions/date/quarter.md b/content/v2.0/reference/flux/functions/date/quarter.md new file mode 100644 index 000000000..87576ce4c --- /dev/null +++ b/content/v2.0/reference/flux/functions/date/quarter.md @@ -0,0 +1,31 @@ +--- +title: date.quarter() function +description: > + The `date.quarter()` function returns the quarter of the year for a specified time. + Results range from `[1-4]`. +menu: + v2_0_ref: + name: date.quarter + parent: Date +weight: 301 +--- + +The `date.quarter()` function returns the quarter of the year for a specified time. +Results range from `[1-4]`. + +_**Function type:** Transformation_ + +```js +import "date" + +date.quarter(t: 2019-07-17T12:05:21.012Z) + +// Returns 3 +``` + +## Parameters + +### t +The time to operate on. + +_**Data type:** Time_ diff --git a/content/v2.0/reference/flux/functions/date/truncate.md b/content/v2.0/reference/flux/functions/date/truncate.md new file mode 100644 index 000000000..c9f7db136 --- /dev/null +++ b/content/v2.0/reference/flux/functions/date/truncate.md @@ -0,0 +1,57 @@ +--- +title: date.truncate() function +description: > + The `date.truncate()` function truncates a time to a specified unit. +menu: + v2_0_ref: + name: date.truncate + parent: Date +weight: 301 +--- + +The `date.truncate()` function truncates a time to a specified unit. + +_**Function type:** Transformation_ + +```js +import "date" + +date.truncate( + t: 2019-07-17T12:05:21.012Z + unit: 1s +) + +// Returns 2019-07-17T12:05:21.000000000Z +``` + +## Parameters + +### t +The time to operate on. + +_**Data type:** Time_ + +### unit +The unit time to truncate to. + +_**Data type:** Duration_ + +{{% note %}} +Only use `1` and the unit of time to specify the `unit`. +For example: `1s`, `1m`, `1h`. +{{% /note %}} + +## Examples +```js +import "date" + +date.truncate(t: "2019-06-03T13:59:01.000000000Z", unit: 1s) +// Returns 2019-06-03T13:59:01.000000000Z + +date.truncate(t: "2019-06-03T13:59:01.000000000Z", unit: 1m) +// Returns 2019-06-03T13:59:00.000000000Z + +date.truncate(t: "2019-06-03T13:59:01.000000000Z", unit: 1h) +// Returns 2019-06-03T13:00:00.000000000Z + +``` diff --git a/content/v2.0/reference/flux/functions/date/week.md b/content/v2.0/reference/flux/functions/date/week.md new file mode 100644 index 000000000..8e1bede7b --- /dev/null +++ b/content/v2.0/reference/flux/functions/date/week.md @@ -0,0 +1,31 @@ +--- +title: date.week() function +description: > + The `date.week()` function returns the ISO week of the year for a specified time. + Results range from `[1-53]`. +menu: + v2_0_ref: + name: date.week + parent: Date +weight: 301 +--- + +The `date.week()` function returns the ISO week of the year for a specified time. +Results range from `[1-53]`. + +_**Function type:** Transformation_ + +```js +import "date" + +date.week(t: 2019-07-17T12:05:21.012Z) + +// Returns 29 +``` + +## Parameters + +### t +The time to operate on. + +_**Data type:** Time_ diff --git a/content/v2.0/visualize-data/visualization-types/single-stat.md b/content/v2.0/visualize-data/visualization-types/single-stat.md deleted file mode 100644 index 10c49e303..000000000 --- a/content/v2.0/visualize-data/visualization-types/single-stat.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: Single Stat visualization -list_title: Single stat -list_image: /img/2-0-visualizations-single-stat-example.png -description: > - The Single Stat view displays the most recent value of the specified time series as a numerical value. -weight: 205 -menu: - v2_0: - name: Single Stat - parent: Visualization types ---- - -The **Single Stat** view displays the most recent value of the specified time series as a numerical value. - -{{< img-hd src="/img/2-0-visualizations-single-stat-example.png" alt="Single stat example" />}} - -Select the **Single Stat** option from the visualization dropdown in the upper right. - -## Single Stat behavior -The Single Stat visualization displays a single numeric data point. -It uses the latest point in the first table (or series) returned by the query. - -{{% note %}} -#### Queries should return one table -Flux does not guarantee the order in which tables are returned. -If a query returns multiple tables (or series), the table order can change between query executions -and result in the Single Stat visualization displaying inconsistent data. -For consistent results, the Single Stat query should return a single table. -{{% /note %}} - -## Single Stat Controls -To view **Single Stat** controls, click the settings icon ({{< icon "gear" >}}) -next to the visualization dropdown in the upper right. - -- **Prefix**: Prefix to be added to the single stat. -- **Suffix**: Suffix to be added to the single stat. -- **Decimal Places**: The number of decimal places to display for the single stat. - - **Auto** or **Custom**: Enable or disable auto-setting. - -###### Colorized Thresholds -- **Base Color**: Select a base or background color from the selection list. -- **Add a Threshold**: Change the color of the single stat based on the current value. - - **Value is**: Enter the value at which the single stat should appear in the selected color. - Choose a color from the dropdown menu next to the value. -- **Colorization**: Choose **Text** for the single stat to change color based on the configured thresholds. - Choose **Background** for the background of the graph to change color based on the configured thresholds. - -## Single Stat examples - -### Show human-readable current value -The following example shows the current memory usage displayed has a human-readable percentage: - -###### Query memory usage percentage -```js -from(bucket: "example-bucket") - |> range(start: v.timeRangeStart, stop: v.timeRangeStop) - |> filter(fn: (r) => - r._measurement == "mem" and - r._field == "used_percent" - ) -``` - -###### Memory usage as a single stat -{{< img-hd src="/img/2-0-visualizations-single-stat-memor.png" alt="Graph + Single Stat Memory Usage Example" />}} From 22bcd1c9510e88b70a6ff024e0b905b997fcc3ec Mon Sep 17 00:00:00 2001 From: Scott Anderson Date: Tue, 23 Jul 2019 15:48:51 -0600 Subject: [PATCH 04/17] re-added single stat graph doc that was unintentially removed --- .../visualization-types/single-stat.md | 65 +++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 content/v2.0/visualize-data/visualization-types/single-stat.md diff --git a/content/v2.0/visualize-data/visualization-types/single-stat.md b/content/v2.0/visualize-data/visualization-types/single-stat.md new file mode 100644 index 000000000..10c49e303 --- /dev/null +++ b/content/v2.0/visualize-data/visualization-types/single-stat.md @@ -0,0 +1,65 @@ +--- +title: Single Stat visualization +list_title: Single stat +list_image: /img/2-0-visualizations-single-stat-example.png +description: > + The Single Stat view displays the most recent value of the specified time series as a numerical value. +weight: 205 +menu: + v2_0: + name: Single Stat + parent: Visualization types +--- + +The **Single Stat** view displays the most recent value of the specified time series as a numerical value. + +{{< img-hd src="/img/2-0-visualizations-single-stat-example.png" alt="Single stat example" />}} + +Select the **Single Stat** option from the visualization dropdown in the upper right. + +## Single Stat behavior +The Single Stat visualization displays a single numeric data point. +It uses the latest point in the first table (or series) returned by the query. + +{{% note %}} +#### Queries should return one table +Flux does not guarantee the order in which tables are returned. +If a query returns multiple tables (or series), the table order can change between query executions +and result in the Single Stat visualization displaying inconsistent data. +For consistent results, the Single Stat query should return a single table. +{{% /note %}} + +## Single Stat Controls +To view **Single Stat** controls, click the settings icon ({{< icon "gear" >}}) +next to the visualization dropdown in the upper right. + +- **Prefix**: Prefix to be added to the single stat. +- **Suffix**: Suffix to be added to the single stat. +- **Decimal Places**: The number of decimal places to display for the single stat. + - **Auto** or **Custom**: Enable or disable auto-setting. + +###### Colorized Thresholds +- **Base Color**: Select a base or background color from the selection list. +- **Add a Threshold**: Change the color of the single stat based on the current value. + - **Value is**: Enter the value at which the single stat should appear in the selected color. + Choose a color from the dropdown menu next to the value. +- **Colorization**: Choose **Text** for the single stat to change color based on the configured thresholds. + Choose **Background** for the background of the graph to change color based on the configured thresholds. + +## Single Stat examples + +### Show human-readable current value +The following example shows the current memory usage displayed has a human-readable percentage: + +###### Query memory usage percentage +```js +from(bucket: "example-bucket") + |> range(start: v.timeRangeStart, stop: v.timeRangeStop) + |> filter(fn: (r) => + r._measurement == "mem" and + r._field == "used_percent" + ) +``` + +###### Memory usage as a single stat +{{< img-hd src="/img/2-0-visualizations-single-stat-memor.png" alt="Graph + Single Stat Memory Usage Example" />}} From ce94a620572c6ec3446761fec2172a3c4c558d83 Mon Sep 17 00:00:00 2001 From: Scott Anderson Date: Tue, 23 Jul 2019 16:32:07 -0600 Subject: [PATCH 05/17] added relativeStrengthIndex function doc, resolves #339 --- .../aggregates/movingaverage.md | 10 -- .../aggregates/relativestrengthindex.md | 105 ++++++++++++++++++ 2 files changed, 105 insertions(+), 10 deletions(-) create mode 100644 content/v2.0/reference/flux/functions/built-in/transformations/aggregates/relativestrengthindex.md 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 ee4687b40..d95951548 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 @@ -52,16 +52,6 @@ from(bucket: "example-bucket"): |> movingAverage(n: 5) ``` -#### Calculate a ten point moving average -```js -movingAverage = (every, period, column="_value", tables=<-) => - tables - |> window(every: every, period: period) - |> mean(column: column) - |> duplicate(column: "_stop", as: "_time") - |> window(every: inf) -``` - #### Table transformation with a two point moving average ###### Input table: 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 new file mode 100644 index 000000000..36d0c7b0a --- /dev/null +++ b/content/v2.0/reference/flux/functions/built-in/transformations/aggregates/relativestrengthindex.md @@ -0,0 +1,105 @@ +--- +title: relativeStrengthIndex() function +description: > + The `relativeStrengthIndex()` function is a momentum indicator that compares the + magnitude of recent increases and decreases of values over a period of time period + to measure the speed and change of data movements. +menu: + v2_0_ref: + name: relativeStrengthIndex + parent: built-in-aggregates +weight: 501 +related: + - /v2.0/reference/flux/functions/built-in/transformations/aggregates/movingaverage/ + - /v2.0/reference/flux/functions/built-in/transformations/aggregates/timedmovingaverage/ + - /v2.0/reference/flux/functions/built-in/transformations/aggregates/exponentialmovingaverage/ + - https://docs.influxdata.com/influxdb/v1.7/query_language/functions/#relative-strength-index, InfluxQL RELATIVE_STRENGTH_INDEX() +--- + +The `relativeStrengthIndex()` function is a momentum indicator that compares the +magnitude of recent increases and decreases of values over a period of time period +to measure thepeed and change of data movements. + +_**Function type:** Aggregate_ + +```js +relativeStrengthIndex( + n: 5, + columns: ["_value"] +) +``` + +##### 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 simple `n`-period averages. +- For subsequent calculations: + - `AVG GAIN` = `((PREVIOUS AVG GAIN) * (n - 1)) / n` + - `AVG LOSS` = `((PREVIOUS AVG LOSS) * (n - 1)) / n` +- `relativeStrengthIndex()` ignores `null` values. + +## Parameters + +### n +The sample size of the algorithm. + +_**Data type:** Integer_ + +### columns +Columns to operate on. _Defaults to `["_value"]`_. + +_**Data type:** Array of Strings_ + +## Examples + +#### Calculate a five point relative strength index +```js +from(bucket: "example-bucket"): + |> range(start: -12h) + |> relativeStrengthIndex(n: 5) +``` + +#### Table transformation with a ten point RSI + +###### Input table: +| _time | A | B | tag | +|:-----:|:----:|:----:|:---:| +| 0001 | 1 | 1 | tv | +| 0002 | 2 | 2 | tv | +| 0003 | 3 | 3 | tv | +| 0004 | 4 | 4 | tv | +| 0005 | 5 | 5 | tv | +| 0006 | 6 | 6 | tv | +| 0007 | 7 | 7 | tv | +| 0008 | 8 | 8 | tv | +| 0009 | 9 | 9 | tv | +| 0010 | 10 | 10 | tv | +| 0011 | 11 | 11 | tv | +| 0012 | 12 | 12 | tv | +| 0013 | 13 | 13 | tv | +| 0014 | 14 | 14 | tv | +| 0015 | 15 | 15 | tv | +| 0016 | 16 | 16 | tv | +| 0017 | 17 | null | tv | +| 0018 | 18 | 17 | tv | + +###### Query: +```js +// ... + |> relativeStrengthIndex( + n: 10, + columns: ["A", "B"] + ) +``` + +###### Output table: +| _time | A | B | tag | +|:-----:|:----:|:----:|:---:| +| 0011 | 100 | 100 | tv | +| 0012 | 100 | 100 | tv | +| 0013 | 100 | 100 | tv | +| 0014 | 100 | 100 | tv | +| 0015 | 100 | 100 | tv | +| 0016 | 90 | 90 | tv | +| 0017 | 81 | 90 | tv | +| 0018 | 72.9 | 81 | tv | From 9f2cd6bb510ea8b57db961d33a2ce9a8c803b1dd Mon Sep 17 00:00:00 2001 From: Scott Anderson Date: Wed, 24 Jul 2019 15:06:16 -0600 Subject: [PATCH 06/17] updated RSI function doc to address PR feedback --- .../aggregates/relativestrengthindex.md | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) 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 36d0c7b0a..8ffb36750 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 @@ -1,9 +1,8 @@ --- title: relativeStrengthIndex() function description: > - The `relativeStrengthIndex()` function is a momentum indicator that compares the - magnitude of recent increases and decreases of values over a period of time period - to measure the speed and change of data movements. + The `relativeStrengthIndex()` function measures the relative speed and change of + values in an input table. menu: v2_0_ref: name: relativeStrengthIndex @@ -16,9 +15,8 @@ related: - https://docs.influxdata.com/influxdb/v1.7/query_language/functions/#relative-strength-index, InfluxQL RELATIVE_STRENGTH_INDEX() --- -The `relativeStrengthIndex()` function is a momentum indicator that compares the -magnitude of recent increases and decreases of values over a period of time period -to measure thepeed and change of data movements. +The `relativeStrengthIndex()` function measures the relative speed and change of +values in an input table. _**Function type:** Aggregate_ @@ -32,7 +30,7 @@ relativeStrengthIndex( ##### 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 simple `n`-period averages. +- For the first value of the RSI, `AVG GAIN` and `AVG LOSS` are averages of the `n` period. - For subsequent calculations: - `AVG GAIN` = `((PREVIOUS AVG GAIN) * (n - 1)) / n` - `AVG LOSS` = `((PREVIOUS AVG LOSS) * (n - 1)) / n` @@ -41,7 +39,7 @@ relativeStrengthIndex( ## Parameters ### n -The sample size of the algorithm. +The number of values to use to calculate the RSI. _**Data type:** Integer_ From 93d4b284f798e1c61052bb35f82fa2c0c9cab538 Mon Sep 17 00:00:00 2001 From: Scott Anderson Date: Wed, 24 Jul 2019 15:56:13 -0600 Subject: [PATCH 07/17] added the flux runtime package, resolves #352 --- .../flux/functions/runtime/_index.md | 22 +++++++++++++++++++ .../flux/functions/runtime/version.md | 20 +++++++++++++++++ 2 files changed, 42 insertions(+) create mode 100644 content/v2.0/reference/flux/functions/runtime/_index.md create mode 100644 content/v2.0/reference/flux/functions/runtime/version.md diff --git a/content/v2.0/reference/flux/functions/runtime/_index.md b/content/v2.0/reference/flux/functions/runtime/_index.md new file mode 100644 index 000000000..b940e379a --- /dev/null +++ b/content/v2.0/reference/flux/functions/runtime/_index.md @@ -0,0 +1,22 @@ +--- +title: Flux runtime package +list_title: Runtime package +description: > + The Flux runtime package includes functions that provide information about the + current Flux runtime. Import the `runtime` package. +menu: + v2_0_ref: + name: Runtime + parent: Flux packages and functions +weight: 202 +v2.0/tags: [runtime, functions, package] +--- + +The Flux runtime package includes functions that provide information about the +current Flux runtime. Import the `runtime` package: + +```js +import "runtime" +``` + +{{< children type="functions" show="pages" >}} diff --git a/content/v2.0/reference/flux/functions/runtime/version.md b/content/v2.0/reference/flux/functions/runtime/version.md new file mode 100644 index 000000000..84333887b --- /dev/null +++ b/content/v2.0/reference/flux/functions/runtime/version.md @@ -0,0 +1,20 @@ +--- +title: runtime.version() function +description: The `runtime.version()` function returns the current Flux version. +menu: + v2_0_ref: + name: runtime.version + parent: Runtime +weight: 401 +--- + +The `runtime.version()` function returns the current Flux version. + +_**Function type:** Miscellaneous_ +_**Output data type:** String_ + +```js +import "runtime" + +runtime.version() +``` From 87ba42544a20be1043b9be162bd698af9fa5f54e Mon Sep 17 00:00:00 2001 From: Scott Anderson Date: Fri, 26 Jul 2019 11:16:06 -0600 Subject: [PATCH 08/17] fixed bad frontmatter --- .../built-in/transformations/aggregates/movingaverage.md | 6 +----- .../transformations/aggregates/timedmovingaverage.md | 3 --- 2 files changed, 1 insertion(+), 8 deletions(-) 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 6691c7b02..742bce355 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 @@ -9,12 +9,8 @@ menu: weight: 501 related: - /v2.0/reference/flux/functions/built-in/transformations/aggregates/timedmovingaverage/ -<<<<<<< HEAD - - /v2.0/reference/flux/functions/built-in/transformations/aggregates/exponentialmovingaverage/ - - /v2.0/reference/flux/functions/built-in/transformations/aggregates/doubleema/ -======= - /v2.0/reference/flux/functions/built-in/transformations/aggregates/exponentialmovingaverage/ ->>>>>>> flux-0.38 + - /v2.0/reference/flux/functions/built-in/transformations/aggregates/doubleema/ - https://docs.influxdata.com/influxdb/latest/query_language/functions/#moving-average, InfluxQL MOVING_AVERAGE() --- diff --git a/content/v2.0/reference/flux/functions/built-in/transformations/aggregates/timedmovingaverage.md b/content/v2.0/reference/flux/functions/built-in/transformations/aggregates/timedmovingaverage.md index 2dec95128..1809552ac 100644 --- a/content/v2.0/reference/flux/functions/built-in/transformations/aggregates/timedmovingaverage.md +++ b/content/v2.0/reference/flux/functions/built-in/transformations/aggregates/timedmovingaverage.md @@ -11,10 +11,7 @@ weight: 501 related: - /v2.0/reference/flux/functions/built-in/transformations/aggregates/movingaverage/ - /v2.0/reference/flux/functions/built-in/transformations/aggregates/exponentialmovingaverage/ -<<<<<<< HEAD - /v2.0/reference/flux/functions/built-in/transformations/aggregates/doubleema/ -======= ->>>>>>> flux-0.38 - https://docs.influxdata.com/influxdb/latest/query_language/functions/#moving-average, InfluxQL MOVING_AVERAGE() --- From 004a623107da9dfe698396f2466f9c91943e3891 Mon Sep 17 00:00:00 2001 From: Scott Anderson Date: Fri, 26 Jul 2019 15:04:01 -0600 Subject: [PATCH 09/17] added tripleEMA(), udpated params on existing moving avg docs --- .../transformations/aggregates/doubleema.md | 46 ++++++------- .../aggregates/exponentialmovingaverage.md | 43 +++++------- .../aggregates/movingaverage.md | 37 ++++------ .../aggregates/timedmovingaverage.md | 1 + .../transformations/aggregates/tripleema.md | 68 +++++++++++++++++++ 5 files changed, 121 insertions(+), 74 deletions(-) create mode 100644 content/v2.0/reference/flux/functions/built-in/transformations/aggregates/tripleema.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 12f7ecc6a..2c11353cf 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 @@ -1,9 +1,9 @@ --- title: doubleEMA() function description: > - The `doubleEMA()` or `doubleExponentialMovingAverage()` function calculates the - exponential moving average of values grouped into `n` number of points, - giving more weight to recent data at double the rate of `exponentialMovingAverage()`. + The `doubleEMA()` function calculates the exponential moving average of values + grouped into `n` number of points, giving more weight to recent data at double + the rate of `exponentialMovingAverage()`. menu: v2_0_ref: name: doubleEMA @@ -11,30 +11,20 @@ menu: weight: 501 related: - /v2.0/reference/flux/functions/built-in/transformations/aggregates/movingaverage/ + - /v2.0/reference/flux/functions/built-in/transformations/aggregates/tripleema/ - /v2.0/reference/flux/functions/built-in/transformations/aggregates/timedmovingaverage/ - /v2.0/reference/flux/functions/built-in/transformations/aggregates/exponentialmovingaverage/ - - https://docs.influxdata.com/influxdb/v1.7/query_language/functions/#exponential-moving-average, InfluxQL EXPONENTIAL_MOVING_AVERAGE() + - https://docs.influxdata.com/influxdb/v1.7/query_language/functions/#double-exponential-moving-average, InfluxQL DOUBLE_EXPONENTIAL_MOVING_AVERAGE() --- -The `doubleEMA()` or `doubleExponentialMovingAverage()` function calculates the -exponential moving average (EMA) of values grouped into `n` number of points, -giving more weight to recent data at double the rate of -[`exponentialMovingAverage()`](/v2.0/reference/flux/functions/built-in/transformations/aggregates/exponentialmovingaverage/). +The `doubleEMA()` function calculates the exponential moving average of values in +the `_value` column grouped into `n` number of points, giving more weight to recent +data at double the rate of [`exponentialMovingAverage()`](/v2.0/reference/flux/functions/built-in/transformations/aggregates/exponentialmovingaverage/). _**Function type:** Aggregate_ ```js -doubleExponentialMovingAverage( - n: 5, - columns: ["_value"] -) - -// OR - -doubleEMA( - n: 5, - columns: ["_value"] -) +doubleEMA(n: 5) ``` ##### Double exponential moving average rules: @@ -52,16 +42,22 @@ The number of points to average. _**Data type:** Integer_ -### columns -Columns to operate on. _Defaults to `["_value"]`_. - -_**Data type:** Array of Strings_ - ## Examples #### Calculate a five point double exponential moving average ```js from(bucket: "example-bucket"): |> range(start: -12h) - |> doubleExponentialMovingAverage(n: 5) + |> doubleEMA(n: 5) +``` + +## Function definition +```js +doubleEMA = (n, tables=<-) => + tables + |> exponentialMovingAverage(n:n) + |> duplicate(column:"_value", as:"ema") + |> exponentialMovingAverage(n:n) + |> map(fn: (r) => ({r with _value: 2.0 * r.ema - r._value})) + |> drop(columns: ["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 da132b4ab..4694eb75c 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 @@ -1,8 +1,8 @@ --- title: exponentialMovingAverage() function description: > - The `exponentialMovingAverage()` function calculates the exponential moving average - of values grouped into `n` number of points, giving more weight to recent data. + The `exponentialMovingAverage()` function calculates the exponential moving average of values + in the `_value` column grouped into `n` number of points, giving more weight to recent data. menu: v2_0_ref: name: exponentialMovingAverage @@ -11,19 +11,18 @@ weight: 501 related: - /v2.0/reference/flux/functions/built-in/transformations/aggregates/movingaverage/ - /v2.0/reference/flux/functions/built-in/transformations/aggregates/timedmovingaverage/ + - /v2.0/reference/flux/functions/built-in/transformations/aggregates/doubleema/ + - /v2.0/reference/flux/functions/built-in/transformations/aggregates/tripleema/ - https://docs.influxdata.com/influxdb/v1.7/query_language/functions/#exponential-moving-average, InfluxQL EXPONENTIAL_MOVING_AVERAGE() --- -The `exponentialMovingAverage()` function calculates the exponential moving average -of values grouped into `n` number of points, giving more weight to recent data. +The `exponentialMovingAverage()` function calculates the exponential moving average of values +in the `_value` column grouped into `n` number of points, giving more weight to recent data. _**Function type:** Aggregate_ ```js -exponentialMovingAverage( - n: 5, - columns: ["_value"] -) +exponentialMovingAverage(n: 5) ``` ##### Exponential moving average rules: @@ -43,11 +42,6 @@ The number of points to average. _**Data type:** Integer_ -### columns -Columns to operate on. _Defaults to `["_value"]`_. - -_**Data type:** Array of Strings_ - ## Examples #### Calculate a five point exponential moving average @@ -60,23 +54,20 @@ from(bucket: "example-bucket"): #### Table transformation with a two point exponential moving average ###### Input table: -| _time | A | B | C | tag | -|:-----:|:----:|:----:|:----:|:---:| -| 0001 | 2 | null | 2 | tv | -| 0002 | null | 10 | 4 | tv | -| 0003 | 8 | 20 | 5 | tv | +| _time | tag | _value | +|:-----:|:---:|:------:| +| 0001 | tv | null | +| 0002 | tv | 10 | +| 0003 | tv | 20 | ###### Query: ```js // ... - |> exponentialMovingAverage( - n: 2, - columns: ["A", "B", "C"] - ) + |> exponentialMovingAverage(n: 2) ``` ###### Output table: -| _time | A | B | C | tag | -|:-----:|:----:|:----:|:----:|:---:| -| 0002 | 2 | 10 | 3 | tv | -| 0003 | 6 | 16.67| 4.33 | tv | +| _time | tag | _value | +|:-----:|:---:|:------:| +| 0002 | tv | 10 | +| 0003 | tv | 16.67 | 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 742bce355..5e8186c7e 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 @@ -11,18 +11,17 @@ related: - /v2.0/reference/flux/functions/built-in/transformations/aggregates/timedmovingaverage/ - /v2.0/reference/flux/functions/built-in/transformations/aggregates/exponentialmovingaverage/ - /v2.0/reference/flux/functions/built-in/transformations/aggregates/doubleema/ + - /v2.0/reference/flux/functions/built-in/transformations/aggregates/tripleema/ - https://docs.influxdata.com/influxdb/latest/query_language/functions/#moving-average, InfluxQL MOVING_AVERAGE() --- -The `movingAverage()` function calculates the mean of values grouped into `n` number of points. +The `movingAverage()` function calculates the mean of values in the `_values` column +grouped into `n` number of points. _**Function type:** Aggregate_ ```js -movingAverage( - n: 5, - columns: ["_value"] -) +movingAverage(n: 5) ``` ##### Moving average rules: @@ -39,11 +38,6 @@ The number of points to average. _**Data type:** Integer_ -### columns -Columns to operate on. _Defaults to `["_value"]`_. - -_**Data type:** Array of Strings_ - ## Examples #### Calculate a five point moving average @@ -66,23 +60,20 @@ movingAverage = (every, period, column="_value", tables=<-) => #### Table transformation with a two point moving average ###### Input table: -| _time | A | B | C | D | tag | -|:-----:|:----:|:----:|:----:|:----:|:---:| -| 0001 | null | 1 | 2 | null | tv | -| 0002 | 6 | 2 | null | null | tv | -| 0003 | 4 | null | 4 | 4 | tv | +| _time | tag | _value | +|:-----:|:---:|:------:| +| 0001 | tv | null | +| 0002 | tv | 6 | +| 0003 | tv | 4 | ###### Query: ```js // ... - |> movingAverage( - n: 2, - columns: ["A", "B", "C", "D"] - ) + |> movingAverage(n: 2 ) ``` ###### Output table: -| _time | A | B | C | D | tag | -|:-----:|:----:|:----:|:----:|:----:|:---:| -| 0002 | 6 | 1.5 | 2 | null | tv | -| 0003 | 5 | 2 | 4 | 4 | tv | +| _time | tag | _value | +|:-----:|:---:|:------:| +| 0002 | tv | 6 | +| 0003 | tv | 5 | diff --git a/content/v2.0/reference/flux/functions/built-in/transformations/aggregates/timedmovingaverage.md b/content/v2.0/reference/flux/functions/built-in/transformations/aggregates/timedmovingaverage.md index 1809552ac..d9b435213 100644 --- a/content/v2.0/reference/flux/functions/built-in/transformations/aggregates/timedmovingaverage.md +++ b/content/v2.0/reference/flux/functions/built-in/transformations/aggregates/timedmovingaverage.md @@ -12,6 +12,7 @@ related: - /v2.0/reference/flux/functions/built-in/transformations/aggregates/movingaverage/ - /v2.0/reference/flux/functions/built-in/transformations/aggregates/exponentialmovingaverage/ - /v2.0/reference/flux/functions/built-in/transformations/aggregates/doubleema/ + - /v2.0/reference/flux/functions/built-in/transformations/aggregates/tripleema/ - https://docs.influxdata.com/influxdb/latest/query_language/functions/#moving-average, InfluxQL MOVING_AVERAGE() --- 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 new file mode 100644 index 000000000..6618acab7 --- /dev/null +++ b/content/v2.0/reference/flux/functions/built-in/transformations/aggregates/tripleema.md @@ -0,0 +1,68 @@ +--- +title: tripleEMA() function +description: > + The `tripleEMA()` function calculates the exponential moving average of values + grouped into `n` number of points, giving more weight to recent data with less lag + than `exponentialMovingAverage()` and `doubleEMA()`. +menu: + v2_0_ref: + name: tripleEMA + parent: built-in-aggregates +weight: 501 +related: + - /v2.0/reference/flux/functions/built-in/transformations/aggregates/movingaverage/ + - /v2.0/reference/flux/functions/built-in/transformations/aggregates/doubleema/ + - /v2.0/reference/flux/functions/built-in/transformations/aggregates/timedmovingaverage/ + - /v2.0/reference/flux/functions/built-in/transformations/aggregates/exponentialmovingaverage/ + - https://docs.influxdata.com/influxdb/v1.7/query_language/functions/#triple-exponential-moving-average, InfluxQL TRIPLE_EXPONENTIAL_MOVING_AVERAGE() +--- + +The `tripleEMA()` function calculates the exponential moving average of values in +the `_value` column grouped into `n` number of points, giving more weight to recent +data with less lag than +[`exponentialMovingAverage()`](/v2.0/reference/flux/functions/built-in/transformations/aggregates/exponentialmovingaverage/) +and [`doubleEMA()`](/v2.0/reference/flux/functions/built-in/transformations/aggregates/doubleema/). + +_**Function type:** Aggregate_ + +```js +tripleEMA(n: 5) +``` + +##### 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`. + - `EMA_3` is the exponential moving average of `EMA_2`. +- A true triple exponential moving average requires at least requires at least `3 * n - 2` values. + If not enough values exist to calculate the triple EMA, it returns a `NaN` value. +- `tripleEMA()` inherits all [exponential moving average rules](/v2.0/reference/flux/functions/built-in/transformations/aggregates/exponentialmovingaverage/#exponential-moving-average-rules). + +## Parameters + +### n +The number of points to average. + +_**Data type:** Integer_ + +## Examples + +#### Calculate a five point triple exponential moving average +```js +from(bucket: "example-bucket"): + |> range(start: -12h) + |> tripleEMA(n: 5) +``` + +## Function definition +```js +tripleEMA = (n, tables=<-) => + tables + |> exponentialMovingAverage(n:n) + |> duplicate(column:"_value", as:"ema1") + |> exponentialMovingAverage(n:n) + |> duplicate(column:"_value", as:"ema2") + |> exponentialMovingAverage(n:n) + |> map(fn: (r) => ({r with _value: 3.0 * r.ema1 - 3.0 * r.ema2 + r._value})) + |> drop(columns: ["ema1", "ema2"]) +``` From a9e553ed44f9a03be55d6a5a5f377f79bd09c0b1 Mon Sep 17 00:00:00 2001 From: Scott Anderson Date: Fri, 26 Jul 2019 15:52:58 -0600 Subject: [PATCH 10/17] added keepFirst param to difference function --- .../transformations/aggregates/difference.md | 27 ++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/content/v2.0/reference/flux/functions/built-in/transformations/aggregates/difference.md b/content/v2.0/reference/flux/functions/built-in/transformations/aggregates/difference.md index f864f6626..d7d45b091 100644 --- a/content/v2.0/reference/flux/functions/built-in/transformations/aggregates/difference.md +++ b/content/v2.0/reference/flux/functions/built-in/transformations/aggregates/difference.md @@ -17,7 +17,11 @@ _**Function type:** Aggregate_ _**Output data type:** Float_ ```js -difference(nonNegative: false, column: "_value") +difference( + nonNegative: false, + column: "_value", + keepFirst: false +) ``` ## Parameters @@ -34,6 +38,13 @@ Defaults to `"_value"`. _**Data type:** String_ +### keepFirst +Indicates if the first row should be kept. +If `true`, the difference will be `null`. +Defaults to `false`. + +_**Data type:** Boolean_ + ## Subtraction rules for numeric types - The difference between two non-null values is their algebraic difference; or `null`, if the result is negative and `nonNegative: true`; @@ -90,6 +101,20 @@ from(bucket: "example-bucket") | 0004 | 6 | tv | | 0005 | null | tv | + +#### With keepFirst set to true +```js +|> difference(nonNegative: false, keepfirst: true): +``` +###### Output table +| _time | _value | tag | +|:-----:|:------:|:---:| +| 0001 | null | tv | +| 0002 | null | tv | +| 0003 | -2 | tv | +| 0004 | 6 | tv | +| 0005 | null | tv | +
##### Related InfluxQL functions and statements: From b381781d19cba2024db4f0c8f7d80259668ccf0c Mon Sep 17 00:00:00 2001 From: Scott Anderson Date: Mon, 29 Jul 2019 10:49:49 -0600 Subject: [PATCH 11/17] updated difference function doc to address PR feedback --- .../functions/built-in/transformations/aggregates/difference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/v2.0/reference/flux/functions/built-in/transformations/aggregates/difference.md b/content/v2.0/reference/flux/functions/built-in/transformations/aggregates/difference.md index d7d45b091..3e52efdba 100644 --- a/content/v2.0/reference/flux/functions/built-in/transformations/aggregates/difference.md +++ b/content/v2.0/reference/flux/functions/built-in/transformations/aggregates/difference.md @@ -39,7 +39,7 @@ Defaults to `"_value"`. _**Data type:** String_ ### keepFirst -Indicates if the first row should be kept. +Indicates the first row should be kept. If `true`, the difference will be `null`. Defaults to `false`. From a2c9de850a849d73e16d1b09fb57542b49734d2e Mon Sep 17 00:00:00 2001 From: Scott Anderson Date: Mon, 5 Aug 2019 13:21:51 -0600 Subject: [PATCH 12/17] added date.year function --- .../reference/flux/functions/date/year.md | 29 +++++++++++++++++++ 1 file changed, 29 insertions(+) create mode 100644 content/v2.0/reference/flux/functions/date/year.md diff --git a/content/v2.0/reference/flux/functions/date/year.md b/content/v2.0/reference/flux/functions/date/year.md new file mode 100644 index 000000000..b2e2a80b4 --- /dev/null +++ b/content/v2.0/reference/flux/functions/date/year.md @@ -0,0 +1,29 @@ +--- +title: date.year() function +description: > + The `date.year()` function returns the year of a specified time. +menu: + v2_0_ref: + name: date.year + parent: Date +weight: 301 +--- + +The `date.year()` function returns the year of a specified time. + +_**Function type:** Transformation_ + +```js +import "date" + +date.year(t: 2019-07-17T12:05:21.012Z) + +// Returns 2019 +``` + +## Parameters + +### t +The time to operate on. + +_**Data type:** Time_ From ba7bcd645239cc53d4b4761e7909ca15a8cff2e8 Mon Sep 17 00:00:00 2001 From: Scott Anderson Date: Tue, 6 Aug 2019 14:11:46 -0600 Subject: [PATCH 13/17] 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`. From 6b1342916e4686e80a377ec32ef03d798f769076 Mon Sep 17 00:00:00 2001 From: Scott Anderson Date: Tue, 6 Aug 2019 14:52:36 -0600 Subject: [PATCH 14/17] marked date.year as draft --- content/v2.0/reference/flux/functions/date/year.md | 1 + 1 file changed, 1 insertion(+) diff --git a/content/v2.0/reference/flux/functions/date/year.md b/content/v2.0/reference/flux/functions/date/year.md index b2e2a80b4..d420ed839 100644 --- a/content/v2.0/reference/flux/functions/date/year.md +++ b/content/v2.0/reference/flux/functions/date/year.md @@ -7,6 +7,7 @@ menu: name: date.year parent: Date weight: 301 +draft: true --- The `date.year()` function returns the year of a specified time. From 8c9fd6a5245aad1ed24bc09a1d93019f771ed40a Mon Sep 17 00:00:00 2001 From: Scott Anderson Date: Tue, 6 Aug 2019 15:48:35 -0600 Subject: [PATCH 15/17] added flux 0.38.0 release notes --- content/v2.0/reference/release-notes/flux.md | 26 +++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/content/v2.0/reference/release-notes/flux.md b/content/v2.0/reference/release-notes/flux.md index ffb1490e1..f3c011dbc 100644 --- a/content/v2.0/reference/release-notes/flux.md +++ b/content/v2.0/reference/release-notes/flux.md @@ -11,13 +11,37 @@ aliases: --- {{% note %}} -_The latest release of InfluxDB v2.0 alpha includes **Flux v0.37.2**. +_The latest release of InfluxDB v2.0 alpha includes **Flux v0.38.0**. Though newer versions of Flux may be available, they will not be included with InfluxDB until the next InfluxDB v2.0 release._ {{% /note %}} --- +## v0.38.0 [2019-08-06] + +### Features +- Update selectors to operate on time columns. +- Add `relativeStrengthIndex()` transformation. +- Add double and triple exponential average transformations (`doubleEMA()` and `tripleEMA()`). +- Add `holtWinters()` transformation. +- Add `keepFirst` parameter to `difference()`. +- DatePart equivalent functions. +- Add runtime package. +- Add and subtract duration literal arithmetic. +- Allow `keep()` to run regardless of nonexistent columns. + If all columns given are nonexistent, `keep()` returns an empty table. +- Scanner returns positioning. + +### Bug fixes +- Function resolver now keeps track of local assignments that may be evaluated at runtime. +- Fixed InfluxDB test errors. +- Add range to tests to pass in InfluxDB. +- Allow converting a duration to a duration. +- Catch integer overflow and underflow for literals. + +--- + ## v0.37.2 [2019-07-24] - _General cleanup of internal code._ From a04c0f344fb4ef1bc8e93717ad93d7d4fc53dc41 Mon Sep 17 00:00:00 2001 From: Scott Anderson Date: Tue, 6 Aug 2019 16:20:24 -0600 Subject: [PATCH 16/17] added selector info to aggregateWindow, resolves #371 --- .../transformations/aggregates/aggregatewindow.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/content/v2.0/reference/flux/functions/built-in/transformations/aggregates/aggregatewindow.md b/content/v2.0/reference/flux/functions/built-in/transformations/aggregates/aggregatewindow.md index c82f5ee3b..5127800f3 100644 --- a/content/v2.0/reference/flux/functions/built-in/transformations/aggregates/aggregatewindow.md +++ b/content/v2.0/reference/flux/functions/built-in/transformations/aggregates/aggregatewindow.md @@ -10,7 +10,8 @@ menu: weight: 501 --- -The `aggregateWindow()` function applies an aggregate function to fixed windows of time. +The `aggregateWindow()` function applies an aggregate or selector function +(any function with a `column` parameter) to fixed windows of time. _**Function type:** Aggregate_ @@ -25,7 +26,7 @@ aggregateWindow( ) ``` -As data is windowed into separate tables and aggregated, the `_time` column is dropped from each group key. +As data is windowed into separate tables and processed, the `_time` column is dropped from each group key. This function copies the timestamp from a remaining column into the `_time` column. View the [function definition](#function-definition). @@ -42,7 +43,7 @@ The [aggregate function](/v2.0/reference/flux/functions/built-in/transformations _**Data type:** Function_ {{% note %}} -Only aggregate functions with a `column` parameter (singular) work with `aggregateWindow()`. +Only aggregate and selector functions with a `column` parameter (singular) work with `aggregateWindow()`. {{% /note %}} ### column @@ -84,10 +85,10 @@ from(bucket: "example-bucket") fn: mean ) ``` -###### Specifying parameters of the aggregate function -To use `aggregateWindow()` aggregate functions that don't provide defaults for required parameters, -for the `fn` parameter, define an anonymous function with `columns` and `tables` parameters -that pipe-forwards tables into the aggregate function with all required parameters defined: +###### Specify parameters of the aggregate function +To use functions that don't provide defaults for required parameters with `aggregateWindow()`, +define an anonymous function with `column` and `tables` parameters that pipe-forward +tables into the aggregate or selector function with all required parameters defined: ```js from(bucket: "example-bucket") From 6a85f883b46daefb54c897429bfab7d439132cae Mon Sep 17 00:00:00 2001 From: Scott Anderson Date: Tue, 6 Aug 2019 16:36:46 -0600 Subject: [PATCH 17/17] upated holtWinters doc to address PR feedback --- .../transformations/aggregates/holtwinters.md | 24 +++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) 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 index 46829e1da..7301ce089 100644 --- 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 @@ -36,24 +36,25 @@ 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`. +If your `interval` is `2m` and `seasonality` is `4`, then the seasonal pattern occurs every +eight minutes or every four data points. +If data doesn't have a seasonal pattern, set `seasonality` to `0`. #### Space values evenly in time `holtWinters()` expects values evenly spaced in time. -To ensure this, it applies the following rules: +To ensure `holtWinters()` values are spaced evenly in time, the following rules apply: -- `interval` is used to divide the into buckets based time. +- Data is grouped into time-based "buckets" determined by the `interval`. - 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. +By default, `holtWinters()` uses the first value in each time bucket to run the Holt-Winters calculation. +To specify other values to use in the calculation, use: + +- [`window()`](/v2.0/reference/flux/functions/built-in/transformations/window/) + with [selectors](/v2.0/reference/flux/functions/built-in/transformations/selectors/) + or [aggregates](/v2.0/reference/flux/functions/built-in/transformations/aggregates/) +- [`aggregateWindow()`](/v2.0/reference/flux/functions/built-in/transformations/aggregates/aggregatewindow) #### Fitted model The `holtWinters()` function applies the [Nelder-Mead optimization](https://en.wikipedia.org/wiki/Nelder%E2%80%93Mead_method) @@ -65,7 +66,6 @@ to include "fitted" data points in results when [`withFit`](#withfit) is set to #### Null values `holtWinters()` treats `null` values as missing data points and includes them in the Holt-Winters calculation. - ## Parameters ### n