Chart
Introduction to Charts
With the chart widget, you can combine visuals like bars, lines, areas, and points to represent your data.
Chart Types
A list of minimalistic configuration examples.
Bar Chart
YAML configuration
id: cashflow2-new type: chart settings: name: Cash showLegend: true encodings: x: field: CASHFLOW_EVENTTIME_TS format: Q%q type: ordinal visuals: - mark: type: bar encodings: y: field: PAYROLL_TS
Line Chart
YAML configuration
id: DSO_Chart type: chart settings: name: Days Sales Outstanding showLegend: true encodings: x: field: ENTRY_QUARTER type: ordinal format: Q%q '%y visuals: - mark: type: line point: true encodings: y: field: KPI_DAYS_SALES_OUTSTANDING_TITLE
Area Chart
YAML configuration
id: revenue-chart type: chart settings: name: Cash showLegend: true sortBy: - field: CASHFLOW_EVENTTIME_TS encodings: x: field: CASHFLOW_EVENTTIME_TS format: Q%q type: ordinal visuals: - mark: type: area encodings: y: field: PAYROLL_TS - mark: type: area encodings: y: field: DEBT_TS axis: title: " "
Scatter Plot
The scatter plot can display two dimensions on x-axis, y-axis and a third dimension via the color encoding.
Using a size encoding it is also possible to make a bubble plot.
YAML configuration
id: riskScatterplot type: chart settings: encodings: x: field: LIKELIHOOD type: quantitative zeroBased: false y: field: IMPACT type: quantitative zeroBased: false color: field: RISKCOLOR scheme: DIVERGING_GREEN_TO_YELLOW_TO_RED thresholds: - 30 - 150 visuals: - mark: type: point point: shape: circle width: 10 - mark: type: text encodings: text: IMPACT
Lollipop Chart
YAML configuration
id: Lollipop type: chart settings: name: Lollipop encodings: x: field: EVENTTIME type: ordinal format: "%H:%m" y: field: COUNT_ACTIVITIES title: Value1 visuals: - mark: lollipop - mark: type: point point: width: 10 - mark: type: point point: width: 10 encodings: y: field: TOTAL_NUMBER_OF_INVOICES title: Value2
Stacked Charts
Stacked by dimensions:
YAML configuration
id: CHART_COSTS type: chart settings: name: Costs showLegend: true encodings: x: field: EXPENSES_EVENTTIME_TS type: ordinal format: Q%q color: field: EXPENSES_TYPE scheme: DIVERGING_BLUE_TO_PINK visuals: - mark: type: bar encodings: y: field: EXPENSES_USD_TS stackBy: EXPENSES_TYPE
Stacking multiple KPIs:
YAML configuration
id: ACV-Gap-chart type: chart settings: name: Revenue Gap showLegend: true encodings: x: field: CLOSEDATE_MONTH type: ordinal visuals: - mark: bar encodings: y: stack: - GEN_pipe_to_be_closed - WIN_RATE - QUOTA legend: true
Grouped Bar Chart
Grouping by dimension:
YAML configuration
id: groupedChart type: chart settings: name: Grouped by (dimension) Material Class x-axis per month showLegend: true encodings: x: field: MATERIAL_DATE_QUARTER type: ordinal axis: title: Material Class format: "%y/%m" color: field: MATERIAL_CLASS scheme: CATEGORICAL visuals: - mark: type: bar encodings: y: field: COUNT_TABLE__STACKINGSAMPLE_WITHOUT_TARGETS groupBy: MATERIAL_CLASS
Grouped KPIs:
YAML configuration
id: groupedStackedChart type: chart settings: name: Grouped - Stacked bar chart per Quarter (stacked KPIs) encodings: x: field: TIMEQUARTER type: ordinal format: Q%q visuals: - mark: bar encodings: y: stack: - - WON - COMMIT - - COMMIT_RISK - BEST_CASE - PIPELINE
Horizontal Charts
YAML configuration
id: horizontalGroupedChart type: chart settings: name: Grouped by (dimension) Material Class x-axis per month showLegend: true encodings: x: field: MATERIAL_DATE_QUARTER type: ordinal axis: title: Material Class format: "%y/%m" color: field: MATERIAL_CLASS scheme: CATEGORICAL visuals: - mark: type: bar orientation: horizontal encodings: y: field: COUNT_TABLE__STACKINGSAMPLE_WITHOUT_TARGETS groupBy: MATERIAL_CLASS
Configuring Charts
By making small changes in the YAML configuration, you can control the visual configuration of the charts.
Choose visuals
You can select one or more visuals to be shown on your chart:
YAML configuration
id: kpi_chart type: chart settings: encodings: x: field: ENTRY_QUARTER type: ordinal format: Q%q visuals: - mark: type: bar point: true legend: Invoice Volume '20 encodings: y: field: KPI_TOTAL_INVOICE_VALUE format: $.2s axis: title: Invoice Volume position: left
YAML configuration
id: kpi_chart type: chart settings: encodings: x: field: ENTRY_QUARTER type: ordinal format: Q%q visuals: - mark: type: bar point: true legend: Invoice Volume '20 encodings: y: field: KPI_TOTAL_INVOICE_VALUE format: $.2s axis: title: Invoice Volume position: left - mark: type: line point: true legend: ADD '20 encodings: y: field: KPI_DAYS_DELINQUENT_2020 units: " d" axis: title: " " position: right
YAML configuration
id: kpi_chart type: chart settings: encodings: x: field: ENTRY_QUARTER type: ordinal format: Q%q visuals: - mark: type: bar point: true legend: Invoice Volume '20 encodings: y: field: KPI_TOTAL_INVOICE_VALUE format: $.2s axis: title: Invoice Volume position: left - mark: type: line point: true legend: ADD '20 encodings: y: field: KPI_DAYS_DELINQUENT_2020 units: " d" axis: title: " " position: right - mark: type: line point: shape: rect width: 40 legend: ADD '19 encodings: y: field: KPI_DAYS_DELINQUENT_2019 units: " d" axis: title: Average Days Delinquent position: right
Sort or order the content
You can sort the content along the x-axis.
Sorted by Material Class
YAML configuration
id: sortedChart type: chart settings: sortBy: - field: MATERIAL_CLASS direction: ASC visuals: - mark: type: bar encodings: y: field: COUNT_TABLE__STACKINGSAMPLE - mark: type: line encodings: y: field: COUNT_TABLE__STACKINGSAMPLE_two encodings: x: field: MATERIAL_CLASS
Sorted by Count
YAML configuration
id: sortedChart type: chart settings: sortBy: - field: COUNT_TABLE__STACKINGSAMPLE direction: ASC visuals: - mark: type: bar encodings: y: field: COUNT_TABLE__STACKINGSAMPLE encodings: x: field: MATERIAL_CLASS
Add axis description and legends
The legend is added in the chart settings.
 |
YAML configuration
id: myChart settings: showLegend: true
The axis position (left, right) and the axis title are set in the encodings.
- mark: encodings: y: axis: title: "My axis title" position: right
Change the color
There are three ways how you can apply colors in a chart:
You can apply predefined color schemes in the chart settings. These colors will be applied to the different visuals (for a list of available color schemes see "What are the available Color Schemes that I can use?" in FAQ)
You can use a predefined color scheme to encode a certain data attribute with color in an encodings configuration (see "Properties specific to Color Encoding" in FAQ).
You can directly apply a specific color to the marks of one visual (see "What are the configuration properties of mark?" in FAQ)
YAML configuration
id: myChart settings: colors: SEQUENTIAL_BLUE
Define chart interactions
The chart interactions can be defined in the chart settings.
Tooltip
Tooltips are enabled by default. They can be disabled in the chart settings.
YAML configuration
id: myChart settings: interactions: tooltip: false
Use the detail encoding to add more fields to be shown in the Tooltip in addition to the data that is visually shown in the chart.
View YAML
id: ganttChart type: chart settings: name: Gantt Chart v1 interactions: selection: true tooltip: true sortBy: - field: GANTT_ACTIVITIES.START visuals: - mark: type: rect orientation: none encodings: x: field: GANTT_ACTIVITIES.START format: "%d.%m.%y" title: Time x2: GANTT_ACTIVITIES.END color: GANTT_ACTIVITIES.ACTIVITY y: GANTT_ACTIVITIES.ACTIVITY detail: - field: GANTT_ACTIVITIES.milestone - field: GANTT_ACTIVITIES.START title: Custom Start Title format: "%d.%m.%y"
Selections
Selections are enabled by default. They can be disabled in the chart settings.
Warning
Please note that not all fields are selectable (i.e., filterable). In particular, fields containing standard aggregations, FILTER_TO_NULL statements, or special cases such as FILTERED_ABC, KMEANS and LINEAR_REGRESSION with a model trained using TRAIN_FILTERED_KM / TRAIN_FILTERED_LM, and window aggregations cannot be filtered.
YAML configuration
id: myChart settings: interactions: selection: true
Target lines
If one of the chart's encodings is a kpi that has a target, a target line is shown by default on the point where the kpi target marks.
Assuming one of the kpis has a defined target (KPI targets can be set on KPI lists or KPI Bowlers) the following yaml will show a target line:
YAML configuration
settings: encodings: x: field: KPI y: field: KPI2
On the other side, if this target line needs to be hidden, it can be done by:
YAML configuration
settings: encodings: x: field: KPI kpiTargets: false y: field: KPI2
Target lines are dashed and grey by default. This can't be customized via yaml.
Position lines
Position lines
Position lines can be defined on each data point of the field accessor
Shorthanded to use the top level encoding:
YAML configuration
settings: encodings: x: field: KPI y: field: KPI2 visuals: - mark: rule
Visual encoding specific:
YAML configuration
settings: encodings: x: field: KPI y: field: KPI2 visuals: - mark: type: rule encodings: x: field: KPI3
Position lines can be defined on a KPI that resolves to one data value (datum)
Use datum to resolve a single value from a KPI. (as opposed to field which queries a KPI value for every data point)
YAML configuration
settings: encodings: x: field: KPI y: field: KPI2 visuals: - mark: type: rule encodings: x: datum: KPI3
Position lines can be defined with a constant value
Use value to manually define where the position line appears on the axis.
YAML configuration
settings: encodings: x: field: KPI y: field: KPI2 visuals: - mark: type: rule encodings: x: value: 30
When plotting vertical position lines, the position line will always be plotted against the axis of the main y-encoding which is by default on the left Y axis. To set the target based on the right y-axis, you can change the main y-encoding to show on the right axis.
YAML configuration
settings: encodings: x: field: KPI y: field: KPI2 axis: position: right visuals: - mark: type: rule encodings: x: value: 30
All position lines are blue and dashed by default. Nevertheless, this can be customized via yaml configuration.
It is suggested to always define custom domains and zeroBased properties in chart level encodings. Defining these properties in visual level encodings might cause unexpected behavior.
Defining domains and zeroBased properties in mark rule encodings will have no effect. See the example on the right.
YAML configuration
encodings: y: field: COUNT_TABLE__STACKINGSAMPLE domain: - 4 - 20 zeroBased: false x: field: MATERIAL_CLASS visuals: - mark: line - mark: type: rule labels: true style: dashed color: RED encodings: y: datum: KPI_X title: Average
FAQ (Frequently Asked Questions)
What are visuals, marks and encodings?
The main parts of every chart configuration are its visuals.
Visuals define visualization layers of the chart that contain mainly two parts: mark and encodings.
the visual mark defines the type of graphical object (such as bar, line, area, point) that is used to represent data items (eg. invoices)
and encodings allow to define how data attributes (eg. customer name, due date, value) of these data items are mapped to specific visual properties (such as color, x-position, y-position)
For example:
If you want to create simple charts that only contain one type of mark such as a bar chart, you specify one visual with mark: bar and encodings for x and y.
Simple Bar Chart
YAML configuration
id: cashflow2-new type: chart settings: name: Cash showLegend: true visuals: - mark: bar encodings: y: PAYROLL_TS x: field: CASHFLOW_EVENTTIME_TS format: Q%q type: ordinal
For a combination of multiple graphical objects in one chart such as bars and lines, or lines and points, you can layer multiple visuals with each of them defining a different mark.This way, you can create more complex charts such as a bar+line chart.
Bar + Line Chart
YAML configuration
id: kpi_chart type: chart settings: encodings: x: field: ENTRY_QUARTER type: ordinal format: Q%q visuals: - mark: bar legend: Invoice Volume '20 encodings: y: field: KPI_TOTAL_INVOICE_VALUE format: $.2s axis: title: Invoice Volume position: left - mark: type: line point: true legend: ADD '20 encodings: y: field: KPI_DAYS_DELINQUENT_2020 units: " d" axis: title: " " position: right
Where can I specify encodings?
Encodings can be specified in two places:
in visuals. Every visual needs at least encodings for x and y positions to know what data attributes should define the spatial layout of the visual.
as a direct property of settings. This can be helpful if you have multiple visuals in one chart which all use the same x-axis. In this case, you can save some writing effort by defining the common x encoding at this root level. The encodings specified at this root level will be used by all visuals that do not specify a respective encoding of their own.
For example, the following two yaml configurations produce this same chart:
Bar + Line Chart
Repeating the definition of x encoding for every visual in the visuals array:
YAML configuration
id: kpi_chart type: chart settings: visuals: - mark: bar legend: Invoice Volume '20 encodings: y: field: KPI_TOTAL_INVOICE_VALUE format: $.2s axis: title: Invoice Volume position: left x: field: ENTRY_QUARTER type: ordinal format: Q%q - mark: type: line point: true legend: ADD '20 encodings: y: field: KPI_DAYS_DELINQUENT_2020 units: " d" axis: title: " " position: right x: field: ENTRY_QUARTER type: ordinal format: Q%q
Defining the x encoding once at the root level so it can be used by every visual in the visuals array:
YAML configuration
id: kpi_chart type: chart settings: encodings: x: field: ENTRY_QUARTER type: ordinal format: Q%q visuals: - mark: bar legend: Invoice Volume '20 encodings: y: field: KPI_TOTAL_INVOICE_VALUE format: $.2s axis: title: Invoice Volume position: left - mark: type: line point: true legend: ADD '20 encodings: y: field: KPI_DAYS_DELINQUENT_2020 units: " d" axis: title: " " position: right
What are the configuration properties of encodings?
Encoding is an object that can contain sub-objects x, y, color, text. These sub-objects can then contain the following properties:
Property | Type | Description | |||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
field | <KnowledgeModel AttributeId> | Required.A string reference to an attribute in the connected knowledge model from which to pull the data. | |||||||||||||||||||||
type | "nominal" | "ordinal" | "quantitative" | "temporal" | The type of measurement for the encoded field. Default: the default value of type is based on the primitive data type of the encoded field:
As the type property describes the semantics of the data rather than the primitive data type, the defaults are only an educated guess. For example, although zip codes are numbers, their measurement type should be nominal as they represent categorical IDs rather than quantitative measures. In such cases, it is advisable to manually set the type property. | |||||||||||||||||||||
title | String | The title of the encoding is used in the tooltip, in the legend, and as the axis title. Default: the default value of title is the displayName of the encoded field/attribute from the Knowledge Model. | |||||||||||||||||||||
format | String | The format property takes a format specifier string as available in d3-format (for number formatting) and d3-time-format (for date formatting). | |||||||||||||||||||||
units | String | The units will be added postfix to every formatted data value. Default: the default value of units is the unit property of the encoded field/attribute from the Knowledge Model. | |||||||||||||||||||||
domain | Array | The domain property can be used to specify a custom domain for the encoding. Default: the default domain will automatically be calculated from the values in the encoded data field. NoteThis property can be overridden if used in visual level encoding by another visual so it's suggested to set this property in top(chart) level encoding Examples:
| |||||||||||||||||||||
kpiParams |
|
| |||||||||||||||||||||
Properties specific to X and Y encodings: | |||||||||||||||||||||||
axis | AxisSpec | An axis specification object:
| |||||||||||||||||||||
stackBy | <KnowledgeModel AttributeId> | A string reference to an attribute in the connected knowledge model that is used to split a bar or area into multiple stacked parts. Note: currently only supported in combination with mark: baror mark: area | |||||||||||||||||||||
groupBy | <KnowledgeModel AttributeId> | A string reference to an attribute in the connected knowledge model that is used to create grouped bars. Note: currently only supported in combination with mark: bar | |||||||||||||||||||||
stack | Array of <KnowledgeModel AttributeId> |
| |||||||||||||||||||||
zeroBased | true | false | Default: true. Note: This property can be overridden if used in visual level encoding by another visual so it's suggested to set this property in top(chart) level encoding | |||||||||||||||||||||
kpiTargets | true | false | Whether to show kpi target lines Default: true. | |||||||||||||||||||||
Properties specific to X and Y encodings within visuals | |||||||||||||||||||||||
datum | <KnowledgeModel KpiId> | A string reference to a kpi in the connected knowledge model that resolves to a constant value. Note: As opposed to field, the datum kpi is not queried with the other fields but queried independently. This is useful for position lines | |||||||||||||||||||||
value | String | Number | boolean | Date | Constant value to be used to map to a visual value. | |||||||||||||||||||||
Properties specific to Color Encoding: | |||||||||||||||||||||||
scheme | ColorScheme | A string reference to a color scheme. Color schemes usually start with one of the following prefixes: CATEGORICAL, SEQUENTIAL, or DIVERGING.For example: CATEGORICAL, SEQUENTIAL_BLUE, SEQUENTIAL_BLUE_REVERSE, DIVERGING_CYAN_TO_ORANGE.For a full list of available color schemes see "What are the available Color Schemes that I can use?" in the FAQ. Default: the default value ofschemeis based on the type property:
| |||||||||||||||||||||
thresholds | Number[] |
| |||||||||||||||||||||
kpiTargets | true | false | Toggle | |||||||||||||||||||||
What are the configuration properties of mark?
Property | Type | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
type | "line" | "bar" | "point" | "area" | "text" | "lollipop" | "rect" | "rule" | Required. The mark type defines the visual marks that will be shown for data items. Note: You can exchange "bar" for "line" to see how the same data would look like with another representation. | ||||||||||||
labels | true | false | Whether to show data labels. | ||||||||||||
color | ColorEnum | explicitly specify which color to use for the marks of this visual. By default the color will be assigned depending on the color scheme that you provided in the config. Possible color enum values are:
| ||||||||||||
orientation | "vertical" | "horizontal" | "none" | The orientation defines the tooltip behavior and whether bars should be vertically or horizontally oriented. Default: depends on the type of the visual, see the article about orientation of visuals. Note: if you specify orientation: horizontal, make sure to use the y encoding for the categorical values and the x encoding for the numerical values. | ||||||||||||
Properties specific to type: bar | ||||||||||||||
bandwidth | Number | Width of a bar in a bar chart in pixels. Default: the default value of bandwidth is calculated such that all bars just fit into the chart without overlap (and a bit of padding in between bars). Note: bars can never exceed the default bandwidth and thus will always fit into the chart without overlap. | ||||||||||||
Properties specific to type: rule | ||||||||||||||
style | "solid" | "dashed" | The line style to be applied to the specified rules | ||||||||||||
Properties specific to type: line | ||||||||||||||
point | true | false | PointSpec | Whether to show markers for every data point on the line. Specifying true will render markers on the line with default configuration. You can also specify a PointSpec object instead:
Default: false. | ||||||||||||
What is the shortcut syntax for default configuration of encodings and marks?
For encodings and mark configurations, you can use the following shortcut syntax if you don't need to do further customizations.
This may be useful to quickly test different chart configurations with default settings.
The following two code blocks are equivalent:
mark: point encodings: x: RECORDID.EVENTTIME_QUARTER y: RECORDID.PAYROLL_TS color: field: RECORDID.BUSINESS_UNIT scheme: DIVERGING_CYAN_TO_ORANGE
mark: type: point encodings: x: field: RECORDID.EVENTTIME_QUARTER y: field: RECORDID.PAYROLL_TS color: field: RECORDID.BUSINESS_UNIT scheme: DIVERGING_CYAN_TO_ORANGE: field: BUSINESS_UNIT
What are the available Color Schemes that I can use?
ColorSchemes can be applied in the chart settings `colors` property or in the color encoding `scheme` property.
You use one of the following color schemes:
Color schemes
# Categorical CATEGORICAL CATEGORICAL_ALT_1 CATEGORICAL_ALT_2 CATEGORICAL_ALT_3 # Diverging DIVERGING_CYAN_TO_ORANGE DIVERGING_BLUE_TO_PINK DIVERGING_PURPLE_TO_TEAL DIVERGING_GREEN_TO_RED DIVERGING_GREEN_TO_YELLOW_TO_RED DIVERGING_ORANGE_TO_CYAN DIVERGING_PINK_TO_BLUE DIVERGING_TEAL_TO_PURPLE DIVERGING_RED_TO_GREEN DIVERGING_RED_TO_YELLOW_TO_GREEN # Sequential SEQUENTIAL_GRAY SEQUENTIAL_CYAN SEQUENTIAL_TEAL SEQUENTIAL_BLUE SEQUENTIAL_PURPLE SEQUENTIAL_PINK SEQUENTIAL_RED SEQUENTIAL_ORANGE SEQUENTIAL_YELLOW SEQUENTIAL_GREEN SEQUENTIAL_GRAY_REVERSE SEQUENTIAL_CYAN_REVERSE SEQUENTIAL_TEAL_REVERSE SEQUENTIAL_BLUE_REVERSE SEQUENTIAL_PURPLE_REVERSE SEQUENTIAL_PINK_REVERSE SEQUENTIAL_RED_REVERSE SEQUENTIAL_ORANGE_REVERSE SEQUENTIAL_YELLOW_REVERSE SEQUENTIAL_GREEN_REVERSE