Docs: xy chart visualization refactor (#103558)
* Added config options heading and bumped other heading levels
* Restructured xy options section
* Fixed links
* Formatted xy chart options using tabs
* Finalized structure of xy chart options section
* Corrected and restructured tooltip options
* Made to do note
* Added to do note
* Replaced screenshots
* Replaced axis options with shared file
* moved transform section
* Moved non-config sections and fixed heading level
* Removed incorrect options from xy chart and commented out image in shared axis file
* Wording edits
* Updated axis options
* Fixed wording
* Added Value mappings and thresholds and other minor edits
* Fixed table
(cherry picked from commit 27e9422f24)
XY charts provide a way to visualize arbitrary x and y values in a graph so that you can easily show the relationship between two variables. XY charts are typically used to create scatter plots. You can also use them to create bubble charts where field values determine the size of each bubble:
The following options let you control how data is displayed in an xy chart:
<!-- prettier-ignore-start -->
| Option | Description |
| ------ | ----------- |
| [Series mapping](#series-mapping) | Set how series data is mapped in the chart. Choose from: **Auto** and **Manual**. Depending on your series mapping selection, the **Frame**, **X-field**, and **Y-field** options differ. For information on setting these specific fields, refer to the [Series mapping section](#series-mapping). |
| Size field | Set which field's values control the size of the points in the chart. This value is relative to the min and max of all the values in the data frame. When you select this option, you can then set the **Min point size** and **Max point size** options. Required in **Manual** mode. |
| Color field | Set which field's values control the color of the points in the chart. To use the color value options under the **Standard** options, you must set this field. Typically, this field is used when you only have one series displayed in the chart. Required in **Manual** mode. |
| [Show](#show) | Set how values are represented in the visualization. Choose from: **Points**, **Lines**, or **Both**. |
| Point size | Set the size of all points in the chart, from one to one hundred pixels in diameter. The default size is five pixels. You can set an [override](ref:configure-field-overrides) to set the pixel size by series (y-field). |
| Min/Max point size | Use these options to control the minimum or maximum point size when you've set the **Size field** option. You can [override](ref:configure-field-overrides) these options for specific series. |
| Point shape | Set the shape of the points in the chart. Choose from:<ul><li>**Circle** - The default setting</li><li>**Square** </li></ul> |
| Point stroke width | The width of the point stroke in pixels. The default is one pixel. |
| Fill opacity | The opacity of the point fill. The default is 50. |
| [Line style](#line-style) | Set the style of the lines that connect points. Choose from: **Solid**, **Dash**, or **Dots**. |
| Line width | The width of the lines that connect points, in pixels. |
### Series mapping
<!-- prettier-ignore-end -->
Set how series data is mapped in the chart.
#### Series mapping
- [Auto](#auto-series-mapping-options) - Automatically generates series from all available data frames (or datasets). You can filter to select only one frame.
- [Manual](#manual-series-mapping-options) - Explicitly define the series by selecting from available data frames.
Set how series data is mapped in the chart. Choose from:
Depending on your series mapping selection, the **Frame**, **X-field**, and **Y-field** options differ. The [Auto](#auto-series-mapping-options) and [Manual](#manual-series-mapping-options) series mapping sections describe these different options.
- **Auto** - Automatically generates series from all available data frames (or datasets). You can filter to select only one frame.
- **Manual** - Explicitly define the series by selecting from available data frames.
#### Auto series mapping options
Depending on your series mapping selection, the **Frame**, **X-field**, and **Y-field** options differ.
These options are described in the tabs that follow:
{{<tabs>}}
{{<tab-contentname="Auto series mapping options">}}
When you select **Auto** as your series mapping mode, the following options are preconfigured, but you can also define them yourself:
- [Frame](#frame)
- [X-field](#x-field)
- [Y-field](#y-field)
- [Size field](#size-field)
- [Color field](#color-field)
<!-- prettier-ignore-start -->
| Option | Description |
| ------ | ----------- |
| Frame | By default, an xy chart displays all data frames. You can filter to select only one frame. |
| [X field](#x-field) | Select which field or fields x represents. By default, this is the first number field in each data frame. For an example of this in **Auto** mode, refer to the [X field section](#x-field). |
| [Y field](#y-field) | After the x-field is set, by default, all the remaining number fields in the data frame are designated as the y-fields. You can use this option to explicitly choose which fields to use for y. For more information on how to use this in **Auto** mode, refer to the [Y field section](#y-field). |
<!-- prettier-ignore-end -->
{{</tab-content>}}
{{<tab-contentname="Manual series mapping options">}}
When you select **Manual** as your series mode, you can add, edit, and delete series.
To manage a series, click the **Series** field; to rename the series, click the series name.
##### Frame
In **Manual** mode, these fields are required:
By default, an xy chart displays all data frames. You can filter to select only one frame.
<!-- prettier-ignore-start -->
##### X-field
| Option | Description |
| ------ | ----------- |
| Frame | Select your data frame or dataset. You can add as many frames as you want. |
| X field | Select which field x represents. |
| Y field | Select which field y represents. |
Select which field or fields x represents. By default, this is the first number field in each data frame. For example, you enter the following CSV content:
<!-- prettier-ignore-end -->
{{</tab-content>}}
{{</tabs>}}
#### X field
In **Auto** series mapping mode, select which field or fields x represents. By default, this is the first number field in each data frame. For example, you enter the following CSV content:
| a | b | c |
| --- | --- | --- |
@ -108,210 +155,85 @@ Select which field or fields x represents. By default, this is the first number
In the resulting chart, the x-field is generated from the values in column "a" unless you define it differently.
##### Y-field
#### Y field
After the x-field is set, by default, all the remaining number fields in the data frame are designated as the y-fields. You can use this option to explicitly choose which fields to use for y.
In **Auto** series mapping mode, after the x-field is set, by default, all the remaining number fields in the data frame are designated as the y-fields.
You can use this option to explicitly choose which fields to use for y.
The series of the chart are generated from the y-fields. To make changes to a series in an xy chart, make [overrides](ref:configure-field-overrides) to the y-field.
The series of the chart are generated from the y-fields.
To make changes to a series in an xy chart, make [overrides](ref:configure-field-overrides) to the y-field.
{{<admonitiontype=note>}}
Any field you use in the [Size field](#size-field) or [Color field](#color-field) doesn't generate a series.
Any field you use in the **Size field** or **Color field** doesn't generate a series.
{{</admonition>}}
You can also use [overrides](ref:configure-field-overrides) to exclude y-fields individually. To do so, add an override with the following properties for each y-field you want removed:
You can also use [overrides](ref:configure-field-overrides) to exclude y-fields individually.
To do so, add an override with the following properties for each y-field you want removed:
- Override type: **Fields with name**
- Override property: **Series > Hide in area**
- Area: **Viz**
##### Size field
Set which field's values control the size of the points in the chart. This value is relative to the min and max of all the values in the data frame.
When you select this option, you can then set the [Min point size](#minmax-point-size) and [Max point size](#minmax-point-size) options.
##### Color field
Set which field's values control the color of the points in the chart. To use the color value options under the Standard options, you must set this field.
Typically, this field is used when you only have one series displayed in the chart.
#### Manual series mapping options
When you select **Manual** as your series mode, you can add, edit, and delete series. To manage a series, click the **Series** field; to rename the series, click the series name.
#### Show
In **Manual** mode, you must set the following options:
Set how values are represented in the visualization. Choose from:
- **Frame** - Select your data frame or dataset. You can add as many frames as you want.
- **X-field** - Select which field x represents.
- **Y-field** - Select which field y represents.
- **Size field** - Select which field controls the size of the points in the chart.
- **Color field** - Select which field controls the color of the points in the chart.
### Show
Set how values are represented in the visualization.
- **Points** - Display values as points. When you select this option, the [Point size](#point-size) option is also displayed.
- **Lines** - Add a line between values. When you select this option, the [Line style](#line-style) and [Line width](#line-width) options are also displayed.
- **Points** - Display values as points. When you select this option, the **Point size** option is also displayed.
- **Lines** - Add a line between values. When you select this option, the [Line style](#line-style) and **Line width** options are also displayed.
- **Both** - Display both points and lines.
### Point size
Set the size of all points in the chart, from one to one hundred pixels in diameter. The default size is five pixels. You can set an [override](ref:configure-field-overrides) to set the pixel size by series (y-field).
### Min/Max point size
Use these options to control the minimum or maximum point size when you've set the **Size field** option. You can [override](ref:configure-field-overrides) these options for specific series.
### Point shape
Set the shape of the points in the chart.
- **Circle** - Display points as circles. This is the default setting.
- **Square** - Display points as squares.
### Point stroke width
Set the width of the point stroke in pixels. The default is one pixel.
### Fill opacity
Set the opacity of the point fill. The default is 50.
### Line style
#### Line style
Set the style of the lines that connect points. To change the color, use the standard [Color scheme](ref:color-scheme) field option.
- **Solid:** Display a solid line. This is the default setting.
- **Dash:** Display a dashed line. When you choose this option, a drop-down list is displayed where you can select the length and gap setting for the line dashes. By default, the length and gap are set to `10, 10`.
- **Dots:** Display dotted lines. When you choose this option, a drop-down list is displayed where you can select dot spacing. By default, the dot spacing is set to `0, 10` (the first number represents dot length, which is always zero).
- **Solid** - Display a solid line. This is the default setting.
- **Dash** - Display a dashed line. When you choose this option, a drop-down list is displayed where you can select the length and gap setting for the line dashes. By default, the length and gap are set to `10, 10`.
- **Dots** - Display dotted lines. When you choose this option, a drop-down list is displayed where you can select dot spacing. By default, the dot spacing is set to `0, 10` (the first number represents dot length, which is always zero).
Set the width of the lines that connect points, in pixels.
## Tooltip options
### Tooltip options
Tooltip options control the information overlay that appears when you hover over data points in the visualization.
### Tooltip mode
When you hover your cursor over the visualization, Grafana can display tooltips. Choose how tooltips behave.
- **Single -** The hover tooltip shows only a single series, the one that you are hovering over on the visualization.
- **Hidden -** Do not display the tooltip when you interact with the visualization.
Use an override to hide individual series from the tooltip.
<!-- prettier-ignore-start -->
### Max width
| Option | Description |
| ------------ | ----------- |
| Tooltip mode | When you hover your cursor over the visualization, Grafana can display tooltips. Choose how they behave:<ul><li>**Single** - The hover tooltip shows only a single series, the one that you are hovering over on the visualization.</li><li>**Hidden** - Do not display the tooltip when you interact with the visualization.</li></ul> |
| Max width | Set the maximum width of the tooltip box. |
Set the maximum width of the tooltip box.
<!-- prettier-ignore-end -->
### Max height
Set the maximum height of the tooltip box. The default is 600 pixels.
Options under the axis category change how the x- and y-axes are rendered. Some options don't take effect until you click outside of the field option box you are editing. You can also or press `Enter`.
### Placement (y-axis)
Select the placement of the y-axis.
- **Auto:** Automatically assigns the y-axis to the series. When there are two or more series with different units, Grafana assigns the left axis to the first unit and the right axis to the units that follow.
- **Left:** Display all y-axes on the left side.
- **Right:** Display all y-axes on the right side.
- **Hidden:** Hide all axes.
To selectively hide axes, [Add a field override](ref:add-a-field-override) that targets specific fields.
### Label
Set a y-axis text label. If you have more than one y-axis, then you can assign different labels using an override.
### Width
Set a fixed width of the axis. By default, Grafana dynamically calculates the width of an axis.
By setting the width of the axis, data with different axes types can share the same display proportions. This setting makes it easier for you to compare more than one graph’s worth of data because the axes are not shifted or stretched within visual proximity to each other.
### Show grid lines
Set the axis grid line visibility.
- **Auto:** Automatically show grid lines based on the density of the data.
- **On:** Always show grid lines.
- **Off:** Never show grid lines.
### Color
Set the color of the axis.
- **Text:** Set the color based on theme text color.
- **Series:** Set the color based on the series color.
- **Logarithmic:** Use a logarithmic scale. When you select this option, a list appears for you to choose a binary (base 2) or common (base 10) logarithmic scale.
- **Symlog:** Use a symmetrical logarithmic scale. When you select this option, a list appears for you to choose a binary (base 2) or common (base 10) logarithmic scale. The linear threshold option allows you to set the threshold at which the scale changes from linear to logarithmic.
### Centered zero
Set the y-axis to be centered on zero.
### Soft min and soft max
Set a **Soft min** or **soft max** option for better control of all axes limits. By default, Grafana sets the range automatically based on the dataset.
**Soft min** and **soft max** settings can prevent small variations in the data from being magnified when it's mostly flat. In contrast, hard min and max values help prevent obscuring useful detail in the data by clipping intermittent spikes past a specific point.
To define hard limits of the axes, set standard min/max options. For more information, refer to [Configure standard options](ref:configure-standard-options).
**Standard options** in the panel editor pane let you change how field data is displayed in your visualizations. When you set a standard option, the change is applied to all fields or series. For more granular control over the display of fields, refer to [Configure field overrides](ref:configure-field-overrides).
You can customize the following standard options:
- **Field min/max** - Enable **Field min/max** to have Grafana calculate the min or max of each field individually, based on the minimum or maximum value of the field.
- **Color scheme** - Set single or multiple colors for your entire visualization.
To learn more, refer to [Configure standard options](ref:configure-standard-options).
- **Color scheme** - Set single or multiple colors for your entire visualization. To learn more about color schemes, refer to [Configure standard options](ref:configure-standard-options).
There are three axis options shared files, axis-options-1.md and axis-options-2.md to cover the most common combinations of options.
Using shared files ensures that content remains consistent across visualizations that share the same options and users don't have to figure out which options apply to a specific visualization when reading that content.
This file is used in the following visualizations: candlestick
This file is used in the following visualizations: candlestick, xy chart
---
Options under the **Axis** section control how the x- and y-axes are rendered. Some options don't take effect until you click outside of the field option box you're editing. You can also press `Enter`.
| [Placement](#placement) | Select the placement of the y-axis. |
| Label | Set a y-axis text label. If you have more than one y-axis, then you can assign different labels using an override. |
| Width | Set a fixed width for the axis. By default, Grafana dynamically calculates the width of an axis. |
| Show grid lines | Set the axis grid line visibility. Choose from: **Auto**, **On**, and **Off**. |
| Color | Set the color of the axis. Choose from:<ul><li>**Text** - Uses panel text color.</li><li>**Series** - Uses the colors of the series.</li></ul> |
| Show border | Set the axis border visibility. |
| [Scale](#scale) | Set the y-axis values scale. Choose from: **Linear**, **Logarithmic**, and **Symlog**. |
| Centered zero | Set the y-axis so it's centered on zero. |
| [Soft min](#soft-min-and-soft-max) | Set a soft min to better control the y-axis limits. |
| [Soft max](#soft-min-and-soft-max) | Set a soft max to better control the y-axis limits. |
| [Placement](#placement) | Select the placement of the y-axis. Choose from: **Auto**, **Left**, **Right**, and **Hidden**. |
| Label | Set a y-axis text label. If you have more than one y-axis, then you can assign different labels using an override. |
| Width | Set a fixed width for the axis. By default, Grafana dynamically calculates the width of an axis. |
| Show grid lines | Set the axis grid line visibility. Choose from: **Auto**, **On**, and **Off**. |
| Color | Set the color of the axis. Choose from:<ul><li>**Text** - Uses panel text color.</li><li>**Series** - Uses the colors of the series.</li></ul> |
| Show border | Set the axis border visibility. |
| [Scale](#scale) | Set the y-axis values scale. Choose from: **Linear**, **Logarithmic**, and **Symlog**. |
| Centered zero | Set the y-axis so it's centered on zero. Applies to the **Linear** or **Symlog** scale options. |
| [Soft min](#soft-min-and-soft-max) | Set a soft min to better control the y-axis limits. |
| [Soft max](#soft-min-and-soft-max) | Set a soft max to better control the y-axis limits. |
<!-- prettier-ignore-end -->
@ -39,8 +39,10 @@ Select the placement of the y-axis. Choose from the following:
Set the y-axis values scale. Choose from:
- **Linear** - Divides the scale into equal parts.
- **Logarithmic** - Use a logarithmic scale. When you select this option, a list appears for you to choose a binary (base 2) or common (base 10) logarithmic scale.
- **Symlog** - Use a symmetrical logarithmic scale. When you select this option, a list appears for you to choose a binary (base 2) or common (base 10) logarithmic scale. The linear threshold option allows you to set the threshold at which the scale changes from linear to logarithmic.
- **Logarithmic** - Use a logarithmic scale. If you select this option, in the **Log base** list, choose a binary (base 2) or common (base 10) logarithmic scale.
- **Symlog** - Use a symmetrical logarithmic scale. If you select this option, choose also:
- **Log base** - Select a binary (base 2) or common (base 10) logarithmic scale.
- **Linear threshold** - Set the threshold at which the scale changes from linear to logarithmic.
#### Soft min and soft max
@ -50,4 +52,6 @@ Set a **Soft min** or **soft max** option for better control of y-axis limits. B
To define hard limits of the y-axis, set standard min/max options. For more information, refer to [Configure standard options](ref:configure-standard-options).
Isabel Matwawana
3 months ago
committed by