Skip to content

chart

Displays data sets in a chart or a group of charts.

The chart control is based on the plotly.js graphs library.

Plotly is a graphing library that provides a vast number of visual representations of datasets with all sorts of customization capabilities. Taipy exposes the Plotly components through the chart control and heavily depends on the underlying implementation.

The core principles of creating charts in Taipy are explained in the Basic concepts section.
Advanced concepts are described in the Advanced features section.

Chart types catalog

Because there are so many different ways of representing data, we have sorted the chart types supported by Taipy by application category:

Basic charts

Statistical charts

Scientific charts

Financial charts

Maps

Specialized charts

Description

The chart control has a large set of properties to deal with the many types of charts it supports and the different kinds of customization that can be defined.

Properties

Name Type Default Description
data(★) dynamic(Any) Required

The data object bound to this chart control.
See the section on the data property below for details.
type indexed(str) scatter

Chart type. See the Plotly chart type documentation for details.
mode indexed(str) lines+markers

Chart mode. See the Plotly chart mode documentation for details.
x indexed(str)

Column name for the x axis.
y indexed(str)

Column name for the y axis.
z indexed(str)

Column name for the z axis.
lon indexed(str)

Column name for the longitude value. See Plotly Map traces.
lat indexed(str)

Column name for the latitude value. See Plotly Map traces.
r indexed(str)

Column name for the r value. See Plotly Polar charts.
theta indexed(str)

Column name for the theta value. See Plotly Polar charts.
high indexed(str)

Column name for the high value. See Plotly Candlestick charts.
low indexed(str)

Column name for the low value. See Ploty Candlestick charts.
open indexed(str)

Column name for the open value. See Plotly Candlestick charts.
close indexed(str)

Column name for the close value. See Plotly Candlestick charts.
locations indexed(str)

Column name for the locations value. See Plotly Choropleth maps.
values indexed(str)

Column name for the values value. See Plotly Pie charts or Plotly Funnel Area charts.
labels indexed(str)

Column name for the labels value. See Plotly Pie charts.
text indexed(str)

Column name for the text associated to the point for the indicated trace. This is meaningful only when _mode_ has the text option.
base indexed(str)

Column name for the base value. Used in bar charts only. See the Plotly bar chart base documentation for details."
title str

The title of this chart control.
render dynamic(bool) True

If True, this chart is visible on the page.
on_range_change Callback

Callback function called when the visible part of the x axis changes. The function receives four parameters:

  • state (State): the state instance.
  • id (optional[str]): the identifier of the chart control.
  • action (optional[str]): the name of the action that provoked the change.
  • payload (dict[str, Any]): the full details on this callback's invocation, as emitted by Plotly.
columns str|List[str]|dict[str, dict[str, str]] _All columns_

List of column names

  • str: ;-separated list of column names
  • List[str]: list of names
  • dict: {"col_name": {format: "format", index: 1}} if index is specified, it represents the display order of the columns. If not, the list order defines the index
label indexed(str)

The label for the indicated trace. This is used when the mouse hovers over a trace.
name indexed(str)

The name of the indicated trace.
selected indexed(dynamic(list[int]|str))

List of the selected point indices.
color indexed(str)

The color of the indicated trace (or a column name for scattered).
selected_color indexed(str)

The color of the selected points for the indicated trace.
marker indexed(dict[str, Any])

The type of markers used for the indicated trace. See marker for details. Color, opacity, size and symbol can be column name.
line indexed(str|dict[str, Any])

The configuration of the line used for the indicated trace. See line for details. If the value is a string, it must be a dash type or pattern (see dash style of lines for details).
selected_marker indexed(dict[str, Any])

The type of markers used for selected points in the indicated trace. See selected marker for details.
layout dict[str, Any]

The plotly.js compatible layout object.
plot_config dict[str, Any]

The plotly.js compatible configuration options object.
options indexed(dict[str, Any])

The plotly.js compatible data object where dynamic data will be overridden..
orientation indexed(str)

The orientation of the indicated trace.
text_anchor indexed(str)

Position of the text relative to the point. Valid values are: top, bottom, left, and right.
xaxis indexed(str)

The x axis identifier for the indicated trace.
yaxis indexed(str)

The y axis identifier for the indicated trace.
width str|int|float 100%

The width, in CSS units, of this element.
height str|int|float

The height, in CSS units, of this element.
template dict

The Plotly layout template.
template[dark] dict

The Plotly layout template applied over the base template when theme is dark.
template[light] dict

The Plotly layout template applied over the base template when theme is not dark.
decimator indexed(taipy.gui.data.Decimator)

A decimator instance for the indicated trace that will reduce the size of the data being sent back and forth.
If defined as indexed, it will impact only the indicated trace; if not, it will apply only the the first trace.
on_change Callback

The name of a function that is triggered when the value is updated.
The parameters of that function are all optional:

  • state (State): the state instance.
  • var_name (str): the variable name.
  • value (Any): the new value.
propagate bool App config

Allows the control's main value to be automatically propagated.
The default value is defined at the application configuration level. If True, any change to the control's value is immediately reflected in the bound application variable.

(★)data is the default property for this visual element.

The data property

All the data sets represented in the chart control must be assigned to its data property.

The supported types for the data property are:

  • A list of values:
    Most chart types use two axes (x/y or theta/r). When receiving a data that is just a series of values, Taipy sets the first axis values to the value index ([0, 1, ...]) and the values of the second axis to the values of the collection.
  • A Pandas DataFrame:
    Taipy charts can be defined by setting the appropriate axis property value to the DataFrame column name.
  • A dictionary:
    The value is converted into a Pandas DataFrame where each key/value pair is converted to a column named key and the associated value. Note that this will work only when all the values of the dictionary keys are series that have the same length.
  • A list of lists of values:
    If all the lists have the same length, Taipy creates a Pandas DataFrame with it.
    If sizes differ, then a DataFrame is created for each list, with a single column called "<index>/0" where index is the index of the current list in the data array. Then an array is built using all those DataFrames and used as described below.
  • A Numpy series:
    Taipy internally builds a Pandas DataFrame with the provided data.
  • A list of Pandas DataFrames:
    This can be used when your chart must represent data sets of different sizes. In this case, you must set the axis property (x, y, r, etc.) value to a string with the format: "<index>/<column>" where index is the index of the DataFrame you want to refer to (starting at index 0) and column would be the column name of the referenced DataFrame.
  • A list of dictionaries
    The data is converted to a list of Pandas DataFrames.

Indexed properties

Chart controls can hold several traces that may display different data sets.
To indicate properties for a given trace, you will use the indexed properties (the ones whose type is indexed(type)). When setting the value of an indexed property, you can specify which trace this property should apply to: you will use the property_name[index] syntax, where the indices start at index 1, to specify which trace is targeted for this property.

Indexed properties can have a default value (using the property_name syntax with no index) which is overridden by any specified indexed property:
Here is an example where i_property is an indexed property:

# This value applies to all the traces of the chart control
general_value = <some_value>
# This value applies to only the second trace of the chart control
specific_value = <some_other_value>

page = "<|...|chart|...|i_property={general_value}|i_property[2]={specific_value}|...|>"

In the definition for page, you can see that the value general_value is set to the property without the index operator ([]) syntax. That means it applies to all the traces of the chart control.
specific_value, on the other hand, applies only to the second trace.

An indexed property can also be assigned an array, without the index operator syntax. Then each value of the array is set to the property at the appropriate index, in sequence:

values = [
    value1,
    value2,
    value3
]

page = "<|...|chart|...|i_property={values}|...|>"

is equivalent to

page = "<|...|chart|...|i_property[1]={value1}|i_property[2]={value2}|i_property[3]={value3}|...|>"

or slightly shorter (and if there are no more than three traces):

page = "<|...|chart|...|i_property={value1}|i_property[2]={value2}|i_property[3]={value3}|...|>"

Usage

Here is a list of several sub-sections that you can check to get more details on a specific domain covered by the chart control: