Skip to main content

Celonis Product Documentation

Chart
Introduction to Charts

With the chart widget, you can combine visuals like bars, lines, areas, and points to represent your data.

41190271.png
41190266.png
41190269.png
41190600.png
41190593.png
41190278.png
41190603.png
41190281.png
41190246.png
Chart Types

A list of minimalistic configuration examples.

Bar Chart
41190240.png

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
41190271.png

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
41190269.png

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.

41190600.png

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
41190593.png

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:

41190278.png

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:

41190282.png

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:

41190281.png

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:

41190603.png

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
41190246.png

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:

41190251.png

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


41190248.png

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

41191095.png

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

41190262.png

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

41190263.png

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.

41190261.png

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:

  1. 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)

  2. 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).

  3. 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.

41190596.png

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.

60361552.png

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.

41190595.png

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.

50726588.png

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 can be defined on each data point of the field accessor

50726606.png

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)

50726568.png

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

50726567.png

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

All position lines are blue and dashed by default. Nevertheless, this can be customized via yaml configuration.

Using custom domains and zeroBased with Position Lines 

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

41190240.png

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

41190248.png

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:

  1. 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.

  2. 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

41190248.png

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:

  • quantitative for number values

  • temporal for date values

  • nominal for string values (use for categorical values)

  • ordinal (is not used by default as it is not possible to automatically derive whether the data has a natural order)

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.

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

Examples:

  • for a quantitative y-position encoding with percentage values, you may specify a domain of [0, 1] to make sure that the y-axis always spans the values from 0 to 100%.

  • for a categorical x-position encoding with country names, you can specify the following domain to fix all values that should be shown on the axis: ["Germany", "Kenia", "Brazil", "India", "New Zealand", "Canada"]

kpiParams

Properties specific to X and Y encodings:

axis

AxisSpec

An axis specification object:

Property

Type

Description

position

"top" | "right" | "bottom" | "left"

Where to place the axis of this position encoding.

Default:

  • for x encodings: "bottom"

  • for y encodings: "left"

title

String

The title is to be shown on the axis.

Default: the default value of axis.title is the title of the encoding.

hide

true | false

Specify true to hide the axis.

Default: false.

ticks

Number

tickOverlap

grid

true | false

Specify false to hide the gridline.

Default: true.

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: bar or 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:

  • default for type quantitative, temporal, ordinal: SEQUENTIAL_BLUE

  • default for type nominal: CATEGORICAL

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:

  • <HUE>_10, <HUE>_20, <HUE>_30, <HUE>_40, <HUE>_50 where <HUE> can be one of the following: BLUE, RED, GREEN, PURPLE, PINK

  • WHITE, GRAY_10, GRAY_20, GRAY_30, BLACK

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:

Property

Type

Description

width

Number

Width of the marker in pixels.

height

Number

Height of the marker in pixels.

shape

"CIRCLE" | "RECT"

Default: "CIRCLE".

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