add visualization behaviors and examples to vis type docs

content/v2.0/visualize-data/visualization-types/gauge.md

@@ -11,14 +11,25 @@ menu:
     parent: Visualization types
 ---
 
-The **Gauge** view displays the single value most recent value for a time series in a gauge view.
+The **Gauge** visualization displays the most recent value for a time series in a gauge.
 
 {{< img-hd src="/img/2-0-visualizations-gauge-example.png" alt="Gauge example" />}}
 
-To select this view, select the **Gauge** option from the visualization dropdown in the upper right.
+Select the **Gauge** option from the visualization dropdown in the upper right.
 
-#### Gauge Controls
+## Gauge behavior
+The gauge visualization displays a single numeric data point within a defined spectrum (_default is 0-100_).
+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 Gauge displaying inconsistent data.
+For consistent results, the Gauge query should return a single table.
+{{% /note %}}
+
+## Gauge Controls
 To view **Gauge** controls, click the settings icon ({{< icon "gear" >}}) next to
 the visualization dropdown in the upper right.
 
@@ -32,3 +43,25 @@ the visualization dropdown in the upper right.
 - **Add a Threshold**: Change the color of the gauge based on the current value.
   - **Value is**: Enter the value at which the gauge should appear in the selected color.
     Choose a color from the dropdown menu next to the value.
+
+## Gauge examples
+Gauge visualizations are useful for showing the current value of a metric and displaying
+where it falls within a spectrum.
+
+### Steam pressure gauge
+The following example queries sensor data that tracks the pressure of steam pipes
+in a facility and displays it as a gauge.
+
+###### Query pressure data from a specific sensor
+```js
+from(bucket: "example-bucket")
+  |> range(start: -1m)
+  |> filter(fn: (r) =>
+      r._measurement == "steam-sensors" and
+      r._field == "psi"
+      r.sensorID == "a211i"
+  )
+```
+
+###### Visualization options for pressure gauge
+{{< img-hd src="/img/2-0-visualizations-guage-pressure.jpg" alt="Pressure guage example" />}}

content/v2.0/visualize-data/visualization-types/graph-single-stat.md

@@ -10,6 +10,9 @@ menu:
   v2_0:
     name: Graph + Single Stat
     parent: Visualization types
+related:
+  - /v2.0/visualize-data/visualization-types/graph
+  - /v2.0/visualize-data/visualization-types/single-stat
 ---
 
 The **Graph + Single Stat** view displays the specified time series in a line graph
@@ -17,11 +20,24 @@ and overlays the single most recent value as a large numeric value.
 
 {{< img-hd src="/img/2-0-visualizations-line-graph-single-stat-example.png" alt="Line Graph + Single Stat example" />}}
 
-To select this view, select the **Graph + Single Stat** option from the visualization
-dropdown in the upper right.
+Select the **Graph + Single Stat** option from the visualization dropdown in the upper right.
 
-#### Graph + Single Stat Controls
+## Graph + Single Stat behavior
+The Graph visualization color codes each table (or series) in the queried data set.
+When multiple series are present, it automatically assigns colors based on the selected [Line Colors option](#options).
 
+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 Single Stat results, the query should return a single table.
+{{% /note %}}
+
+## Graph + Single Stat Controls
 To view **Graph + Single Stat** controls, click the settings icon ({{< icon "gear" >}})
 next to the visualization dropdown in the upper right.
 
@@ -56,3 +72,22 @@ next to the visualization dropdown in the upper right.
     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.
+
+## Graph + Single Stat examples
+The primary use case for the Graph + Single Stat visualization is to show the current or latest
+value as well as historical values.
+
+### Show current value and historical values
+The following example shows the current percentage of memory used as well as memory usage over time:
+
+###### 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 visualization
+{{< img-hd src="/img/2-0-visualizations-graph-single-stat-mem.jpg" alt="Graph + Single Stat Memory Usage Example" />}}

content/v2.0/visualize-data/visualization-types/graph.md

@@ -11,15 +11,20 @@ menu:
     parent: Visualization types
 ---
 
-There are several types of graphs you can create.
-
-To select this view, select the **Graph** option from the visualization dropdown
-in the upper right.
+The Graph visualization provides several types of graphs, each configured through
+the [Graph options](#graph-options).
 
 {{< img-hd src="/img/2-0-visualizations-line-graph-example.png" alt="Line Graph example" />}}
 
-#### Graph controls
+Select the **Graph** option from the visualization dropdown in the upper right.
 
+## Graph behavior
+The Graph visualization color codes each table (or series) in the queried data set.
+When multiple series are present, it automatically assigns colors based on the selected [Line Colors option](#options).
+
+When using a line graph, all points within a single table are connected. When multiple series are present, it automatically assigns colors based on the selected [Line Colors option](#options).
+
+## Graph controls
 To view **Graph** controls, click the settings icon ({{< icon "gear" >}}) next
 to the visualization dropdown in the upper right.
 
@@ -47,22 +52,19 @@ to the visualization dropdown in the upper right.
       - **Min**: Minimum y-axis value.
       - **Max**: Maximum y-axis value.
 
-##### Graph with linear interpolation
+## Graph Examples
 
+##### Graph with linear interpolation
 {{< img-hd src="/img/2-0-visualizations-line-graph-example.png" alt="Line Graph example" />}}
 
 ##### Graph with smooth interpolation
-
 {{< img-hd src="/img/2-0-visualizations-line-graph-smooth-example.png" alt="Step-Plot Graph example" />}}
 
 ##### Graph with step interpolation
-
 {{< img-hd src="/img/2-0-visualizations-line-graph-step-example.png" alt="Step-Plot Graph example" />}}
 
 <!-- ##### Stacked Graph example
-
 {{< img-hd src="/img/2-0-visualizations-stacked-graph-example.png" alt="Stacked Graph example" />}} -->
 
 <!-- ##### Bar Graph example
-
 {{< img-hd src="/img/2-0-visualizations-bar-graph-example.png" alt="Bar Graph example" />}} -->

content/v2.0/visualize-data/visualization-types/heatmap.md

@@ -10,6 +10,8 @@ menu:
   v2_0:
     name: Heatmap
     parent: Visualization types
+related:
+  - /v2.0/visualize-data/visualization-types/scatter
 ---
 
 A **Heatmap** displays the distribution of data on an x and y axes where color
@@ -17,10 +19,16 @@ represents different concentrations of data points.
 
 {{< img-hd src="/img/2-0-visualizations-heatmap-example.png" alt="Heatmap example" />}}
 
-To select this view, select the **Heatmap** option from the visualization dropdown in the upper right.
+Select the **Heatmap** option from the visualization dropdown in the upper right.
 
-#### Heatmap Controls
+## Heatmap behavior
+Heatmaps divide data points into "bins" – segments of the visualization with upper
+and lower bounds for both [X and Y axes](#data).
+The [Bin Size option](#options) determines the bounds for each bin.
+The total number of points that fall within a bin determine the its value and color.
+Warmer or brighter colors represent higher bin values or density of points within the bin.
 
+## Heatmap Controls
 To view **Heatmap** controls, click the settings icon ({{< icon "gear" >}})
 next to the visualization dropdown in the upper right.
 
@@ -51,3 +59,57 @@ next to the visualization dropdown in the upper right.
   - **Custom**: Manually specify the value range of the y-axis.
       - **Min**: Minimum y-axis value.
       - **Max**: Maximum y-axis value.
+
+## Heatmap examples
+
+### Cross-measurement correlation
+The following example explores possible correlation between CPU and Memory usage.
+It uses data collected with the Telegraf [Mem](/v2.0/reference/telegraf-plugins/#mem)
+and [CPU](/v2.0/reference/telegraf-plugins/#cpu) input plugins.
+
+###### Join CPU and memory usage
+The following query joins CPU and memory usage on `_time`.
+Each row in the output table contains `_value_cpu` and `_value_mem` columns.
+
+```js
+cpu = from(bucket: "example-bucket")
+  |> range(start: v.timeRangeStart, stop: v.timeRangeStop)
+  |> filter(fn: (r) =>
+      r._measurement == "cpu" and
+      r._field == "usage_system" and
+      r.cpu == "cpu-total"
+  )
+
+mem = from(bucket: "example-bucket")
+  |> range(start: v.timeRangeStart, stop: v.timeRangeStop)
+  |> filter(fn: (r) =>
+      r._measurement == "mem" and
+      r._field == "used_percent"
+  )
+
+join(tables: {cpu: cpu, mem: mem}, on: ["_time"], method: "inner")
+```
+
+###### Use a heatmap to visualize correlation
+In the Heatmap visualization controls, `_value_cpu` is selected as the [X Column](#data)
+and `_value_mem` is selected as the [Y Column](#data).
+The domain for each axis is also customized to account for the scale difference
+between column values.
+
+{{< img-hd src="/img/2-0-visualizations-heatmap-correlation.jpg" alt="Heatmap correlation example" />}}
+
+
+## Important notes
+
+### Differences between a heatmap and a scatter plot
+Heatmaps and [Scatter plots](/v2.0/visualize-data/visualization-types/scatter/)
+both visualize the distribution of data points on X and Y axes.
+However, in certain cases, heatmaps provide better visibility into point density.
+
+For example, the dashboard cells below visualize the same query results:
+
+{{< img-hd src="/img/2-0-visualizations-heatmap-vs-scatter.jpg" alt="Heatmap vs Scatter plot" />}}
+
+The heatmap indicates isolated high point density, which isn't visible in the scatter plot.
+In the scatter plot visualization, points that share the same X and Y coordinates
+appear as a single point.

content/v2.0/visualize-data/visualization-types/histogram.md

@@ -3,7 +3,7 @@ title: Histogram visualization
 list_title: Histogram
 list_image: /img/2-0-visualizations-histogram-example.png
 description: >
-  A histogram is a way to view the distribution of data. Unlike column charts, histograms have no time axis.
+  A histogram is a way to view the distribution of data.
   The y-axis is dedicated to count, and the x-axis is divided into bins.
 weight: 204
 menu:
@@ -12,20 +12,32 @@ menu:
     parent: Visualization types
 ---
 
-A histogram is a way to view the distribution of data. Unlike column charts, histograms have no time axis.
-The y-axis is dedicated to count, and the x-axis is divided into bins.
+A histogram is a way to view the distribution of data.
+The y-axis is dedicated to count, and the X-axis is divided into bins.
 
 {{< img-hd src="/img/2-0-visualizations-histogram-example.png" alt="Histogram example" />}}
 
-To select this view, select the **Histogram** option from the visualization dropdown in the upper right.
+Select the **Histogram** option from the visualization dropdown in the upper right.
 
-#### Histogram Controls
+## Histogram behavior
+The Histogram visualization is a bar graph that displays the number of data points
+that fall within "bins" – segments of the X axis with upper and lower bounds.
+Bin thresholds are determined by dividing the width of the X axis by the number
+of bins set using the [Bins option](#options).
+Data within bins can be further grouped or segmented by selecting columns in the
+[Group By option](#options).
 
+{{% note %}}
+The Histogram visualization automatically bins, segments, and counts data.
+To work properly, query results **should not** be structured as histogram data.
+{{% /note %}}
+
+## Histogram Controls
 To view **Histogram** controls, click the settings icon ({{< icon "gear" >}}) next
 to the visualization dropdown in the upper right.
 
 ###### Data
-- **Column**: The column to select data from.
+- **X Column**: The column to select data from.
 - **Group By**: The column to group by.
 
 ###### Options
@@ -43,3 +55,26 @@ to the visualization dropdown in the upper right.
   - **Custom**: Manually specify the value range of the x-axis.
       - **Min**: Minimum x-axis value.
       - **Max**: Maximum x-axis value.
+
+## Histogram examples
+
+### View error counts by severity over time
+The following example uses the Histogram visualization to show the number of errors
+"binned" by time and segmented by severity.
+_It utilizes data from the [Telegraf Syslog plugin](/v2.0/reference/telegraf-plugins/#syslog)._
+
+##### Query for errors by severity code
+```js
+from(bucket: "example-bucket")
+  |> range(start: v.timeRangeStart, stop: v.timeRangeStop)
+  |> filter(fn: (r) =>
+      r._measurement == "syslog" and
+      r._field == "severity_code"
+  )
+```
+
+##### Histogram settings
+In the Histogram visualization options, select `_time` as the [X Column](#data)
+and `severity` as the [Group By](#data) option:
+
+{{< img-hd src="/img/2-0-visualizations-histogram-errors.jpg" alt="Errors histogram" />}}

content/v2.0/visualize-data/visualization-types/scatter.md

@@ -9,21 +9,30 @@ menu:
   v2_0:
     name: Scatter
     parent: Visualization types
+related:
+  - /v2.0/visualize-data/visualization-types/heatmap
 ---
 
 The **Scatter** view uses a scatter plot to display time series data.
 
 {{< img-hd src="/img/2-0-visualizations-scatter-example.png" alt="Scatter plot example" />}}
 
-To select this view, select the **Scatter** option from the visualization dropdown in the upper right.
+Select the **Scatter** option from the visualization dropdown in the upper right.
 
-#### Scatter controls
+## Scatter behavior
+The scatter visualization maps each data point to X and Y coordinates.
+X and Y axes are specified with the [X Column](#data) and [Y Column](#data) visualization options.
+Each unique series is differentiated using fill colors and symbols.
+Use the [Symbol Column](#data) and [Fill Column](#data) options to select columns
+used to differentiate points in the visualization.
+
+## Scatter controls
 To view **Scatter** controls, click the settings icon ({{< icon "gear" >}}) next
 to the visualization dropdown in the upper right.
 
 ###### Data
-- **Symbol column**: Define a column containing values that should be differentiated with symbols.
-- **Fill column**: Define a column containing values that should be differentiated with fill color.
+- **Symbol Column**: Define a column containing values that should be differentiated with symbols.
+- **Fill Column**: Define a column containing values that should be differentiated with fill color.
 - **X Column**: Select a column to display on the x-axis.
 - **Y Column**: Select a column to display on the y-axis.
 
@@ -42,3 +51,59 @@ to the visualization dropdown in the upper right.
   - **Custom**: Manually specify the value range of the y-axis.
       - **Min**: Minimum y-axis value.
       - **Max**: Maximum y-axis value.
+
+## Scatter examples
+
+### Cross-measurement correlation
+The following example explores possible correlation between CPU and Memory usage.
+It uses data collected with the Telegraf [Mem](/v2.0/reference/telegraf-plugins/#mem)
+and [CPU](/v2.0/reference/telegraf-plugins/#cpu) input plugins.
+
+###### Query CPU and memory usage
+The following query creates a union of CPU and memory usage.
+It scales the CPU usage metric to better align with baseline memory usage.
+
+```js
+cpu = from(bucket: "example-bucket")
+  |> range(start: v.timeRangeStart, stop: v.timeRangeStop)
+  |> filter(fn: (r) =>
+      r._measurement == "cpu" and
+      r._field == "usage_system" and
+      r.cpu == "cpu-total"
+  )
+  // Scale CPU usage
+  |> map(fn: (r) => ({
+      _value: r._value + 60.0,
+      _time: r._time
+      })
+  )
+
+mem = from(bucket: "example-bucket")
+  |> range(start: v.timeRangeStart, stop: v.timeRangeStop)
+  |> filter(fn: (r) =>
+      r._measurement == "mem" and
+      r._field == "used_percent"
+  )
+
+union(tables: [cpu, mem])
+```
+
+###### Use a scatter plot to visualize correlation
+In the Scatter visualization controls, points are differentiated based on their group keys.
+
+{{< img-hd src="/img/2-0-visualizations-scatter-correlation.jpg" alt="Heatmap correlation example" />}}
+
+## Important notes
+
+### Differences between a scatter plot and a heatmap
+Scatter plots and [Heatmaps](/v2.0/visualize-data/visualization-types/heatmap/)
+both visualize the distribution of data points on X and Y axes.
+However, in certain cases, scatterplots can "hide" points if they share the same X and Y coordinates.
+
+For example, the dashboard cells below visualize the same query results:
+
+{{< img-hd src="/img/2-0-visualizations-heatmap-vs-scatter.jpg" alt="Heatmap vs Scatter plot" />}}
+
+The heatmap indicates isolated high point density, which isn't visible in the scatter plot.
+In the scatter plot visualization, points that share the same X and Y coordinates
+appear as a single point.

content/v2.0/visualize-data/visualization-types/single-stat.md

@@ -15,10 +15,21 @@ The **Single Stat** view displays the most recent value of the specified time se
 
 {{< img-hd src="/img/2-0-visualizations-single-stat-example.png" alt="Single stat example" />}}
 
-To select this view, select the **Single Stat** option from the visualization dropdown in the upper right.
+Select the **Single Stat** option from the visualization dropdown in the upper right.
 
-#### Single Stat Controls
+## 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.
 
@@ -34,3 +45,21 @@ next to the visualization dropdown in the upper right.
     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.jpg" alt="Graph + Single Stat Memory Usage Example" />}}

content/v2.0/visualize-data/visualization-types/table.md

@@ -1,6 +1,6 @@
 ---
 title: Table visualization
-list_title: Single stat
+list_title: Table
 list_image: /img/2-0-visualizations-table-example.png
 description: >
   The Table option displays the results of queries in a tabular view, which is
@@ -17,10 +17,16 @@ sometimes easier to analyze than graph views of data.
 
 {{< img-hd src="/img/2-0-visualizations-table-example.png" alt="Table example" />}}
 
-To select this view, select the **Table** option from the visualization dropdown in the upper right.
+Select the **Table** option from the visualization dropdown in the upper right.
 
-#### Table Controls
+## Table behavior
+The table visualization renders queried data in structured, easy-to-read tables.
+Columns and rows match those in the query output.
+If query results contain multiple tables, only one table is shown at a time.
+Select other output tables in the far left column of the table visualization.
+Tables are identified by their [group key](/v2.0/query-data/get-started/#group-keys).
 
+## Table Controls
 To view **Table** controls, click the settings icon ({{< icon "gear" >}}) next to
 the visualization dropdown in the upper right.
 
@@ -51,3 +57,27 @@ the visualization dropdown in the upper right.
 - **Add a Threshold**: Change the color of the table based on the current value.
   - **Value is**: Enter the value at which the table should appear in the selected color.
     Choose a color from the dropdown menu next to the value.
+
+## Table examples
+Tables are helpful when displaying many human-readable metrics in a dashboard
+such as cluster statistics or log messages.
+
+### Human-readable cluster metrics
+The following example queries the latest reported memory usage from a cluster of servers.
+
+###### Query the latest memory usage from each host
+```js
+from(bucket: "example-bucket")
+  |> range(start: v.timeRangeStart, stop: v.timeRangeStop)
+  |> filter(fn: (r) =>
+      r._measurement == "mem" and
+      r._field == "used_percent"
+  )
+  |> group(columns: ["host"])
+  |> last()
+  |> group()
+  |> keep(columns: ["_value", "host"])
+```
+
+###### Cluster metrics in a table
+{{< img-hd src="/img/2-0-visualizations-table-human-readable.jpg" alt="Human readable metrics in a table" />}}