Timeseries

Timeseries

Timeseries(
    data: Union[DataType, DataFrame],
    *,
    charts: Optional[
        List[Union[str, TimeseriesSeries, Chart]]
    ] = None,
    date_column: Optional[TemplatedStringItem] = None,
    widget_id: Optional[str] = None,
    period_selector: Optional[PeriodSelector] = None,
    title: Optional[WidgetTitleType] = None,
    legend: Optional[LegendPosition] = None,
    navigator: Optional[
        Union[Navigator, TimeseriesSeries]
    ] = None,
    enable_toolbar: bool = True
)

Visualize charts, customize data, date, toolbar.

Visualize multiple charts with date selector, navigator, legend. Customize data source, date column, toolbar. Enable or disable toolbar for enhanced user control.

Constructor for Timeseries widget.

Parameters:

Name	Type	Description	Default
data	Union[DataType, DataFrame]	data to be used by widget. Accepts DataSource method as well as raw data.	required
charts	Optional[List[Union[str, TimeseriesSeries, Chart]]]	list of charts to be added to the widget. Each element in the list is a new chart, with a maximum of 5 Charts.	None
date_column	Optional[TemplatedStringItem]	column that must be used as x axis date. This column must be of type datetime.	None
widget_id	Optional[str]	unique widget id in a dashboard.	None
period_selector	Optional[PeriodSelector]	selector for particular periods in a chart.	None
title	Optional[WidgetTitleType]	title of widget can be either a string (fixed value) or determined by a value from another widget using a WidgetLink.	None
legend	Optional[LegendPosition]	legend of timeseries widget.	None
navigator	Optional[Union[Navigator, TimeseriesSeries]]	navigator added to the bottom of all charts to facilitate navigation.	None
enable_toolbar	bool	Enable/Disable toolbar flag.	True

Examples:

Basic Timeseries Widget

import pandas as pd
from engineai.sdk.dashboard.dashboard import Dashboard
from engineai.sdk.dashboard.widgets import timeseries

data = pd.DataFrame(
    {
        "value": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
    },
    index=pd.date_range("2020-01-01", "2020-01-10"),
)
Dashboard(
    app_slug="engineai-docs-steps",
    workspace_slug="engineai-docs-steps",
    content=timeseries.Timeseries(data=data),
)

Filter Timeseries charts

import pandas as pd
from engineai.sdk.dashboard.dashboard import Dashboard
from engineai.sdk.dashboard.widgets import timeseries

# Create a dataframe
df = pd.DataFrame(
    {
        "date": pd.date_range("2020-01-01", "2020-01-10"),
        "column_name_1": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
        "column_name_2": [10, 9, 8, 7, 6, 5, 4, 3, 2, 1],
        "column_name_3": [5, 4, 3, 2, 1, 2, 3, 4, 5, 6],
    }
)

ts = timeseries.Timeseries(df, charts=["column_name_1"])

Dashboard(
    app_slug="engineai-docs-steps",
    workspace_slug="engineai-docs-steps",
    content=ts,
)

Change Chart Series type

import pandas as pd
from engineai.sdk.dashboard.dashboard import Dashboard
from engineai.sdk.dashboard.widgets import timeseries

# Create a dataframe
df = pd.DataFrame(
    {
        "date": pd.date_range("2020-01-01", "2020-01-10"),
        "column_name_1": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
        "column_name_2": [10, 9, 8, 7, 6, 5, 4, 3, 2, 1],
        "column_name_3": [5, 4, 3, 2, 1, 2, 3, 4, 5, 6],
    }
)

ts = timeseries.Timeseries(
    df, charts=[timeseries.ColumnSeries(data_column="column_name_1")]
)

Dashboard(
    app_slug="engineai-docs-steps",
    workspace_slug="engineai-docs-steps",
    content=ts,
)

Add Multiple Series to a Chart

import pandas as pd
from engineai.sdk.dashboard.dashboard import Dashboard
from engineai.sdk.dashboard.widgets import timeseries

# Create a dataframe
df = pd.DataFrame(
    {
        "date": pd.date_range("2020-01-01", "2020-01-10"),
        "column_name_1": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
        "column_name_2": [10, 9, 8, 7, 6, 5, 4, 3, 2, 1],
        "column_name_3": [5, 4, 3, 2, 1, 2, 3, 4, 5, 6],
    }
)

ts = timeseries.Timeseries(
    df,
    charts=[
        timeseries.Chart(
            left_y_axis=timeseries.YAxis(
                series=[
                    "column_name_1",
                    "column_name_2",
                ]
            )
        ),
    ],
)

Dashboard(
    app_slug="engineai-docs-steps",
    workspace_slug="engineai-docs-steps",
    content=ts,
)

Components

Chart

Chart(
    *,
    left_y_axis: Optional[
        Union[YAxisSpec, TimeseriesSeries]
    ] = None,
    height_percentage: Optional[Union[int, float]] = None,
    height: Union[int, float] = 3,
    x_axis: Optional[XAxis] = None,
    right_y_axis: Optional[
        Union[YAxisSpec, TimeseriesSeries]
    ] = None,
    title: Optional[Union[str, WidgetField]] = None,
    area_series_stacked: bool = False,
    tooltips: Optional[TooltipItems] = None
)

Customize charts in Timeseries widget.

Construct charts within a timeseries widget, offering a variety of customizable options for effective data visualization. Specify parameters such as the x-axis specification, left and right y-axis configurations, chart title, height, area series stacking, and tooltips.

Constructor for Chart.

Parameters:

Name	Type	Description	Default
x_axis	Optional[XAxis]	spec for x axis or the specific date column that must be used for the x axis.	None
left_y_axis	Optional[Union[YAxisSpec, TimeseriesSeries]]	spec for left y axis. If TimeseriesSeries added directly, a YAxis will be used as the default axis spec.	None
right_y_axis	Optional[Union[YAxisSpec, TimeseriesSeries]]	spec for right y axis (optional). If TimeseriesSeries added directly, a YAxis will be used as the default axis spec.	None
title	Optional[Union[str, WidgetField]]	title of chart can be either a string (fixed value) or determined by a value from another widget using a WidgetField.	None
height_percentage	Optional[Union[int, float]]	percentage of height occupied by chart. The height_percentage of all charts in a timeseries widgets has to sum to 1.	None
height	Union[int, float]	height value for the chart in units of 100px. Values range from 2 to 10 units.	3
area_series_stacked	bool	enable stacking for all area series in this chart.	False
tooltips	Optional[TooltipItems]	tooltip items to be displayed at Chart level.	None

Navigator

Navigator(
    *series: TimeseriesSeries,
    title: Optional[WidgetTitleType] = None
)

Navigation of Timeseries data.

Construct a navigator for a timeseries widget for efficient navigation and exploration of time-series data. Specify one or more series to be included in the navigator for easy visualization of trends and patterns across different metrics.

Constructor for Navigator.

Parameters:

Name	Type	Description	Default
title	Optional[WidgetTitleType]	title to be added to navigator	None
series	TimeseriesSeries	series to be added to navigator	()

Examples:

Create a minimal timeseries widget with a navigator

import pandas as pd
from engineai.sdk.dashboard.dashboard import Dashboard
from engineai.sdk.dashboard.widgets import timeseries

data = pd.DataFrame(
    {
        "value": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
    },
    index=pd.date_range("2020-01-01", "2020-01-10"),
)

ts = timeseries.Timeseries(
    data=data,
    navigator=timeseries.Navigator(timeseries.ColumnSeries(data_column="value")),
)
Dashboard(
    app_slug="engineai-docs-steps",
    workspace_slug="engineai-docs-steps",
    content=ts,
)

XAxis

XAxis(
    *,
    enable_crosshair: bool = False,
    line: Optional[AxisLine] = None,
    band: Optional[AxisBand] = None
)

Specify x-axis appearance & behavior in Timeseries chart.

Construct specifications for the x-axis of a Timeseries chart with a range of options to customize its appearance and behavior.

Construct TimeseriesBaseAxis.

Parameters:

Name	Type	Description	Default
enable_crosshair	bool	whether to enable crosshair that follows either the mouse pointer or the hovered point.	False
line	Optional[AxisLine]	line spec for y axis.	None
band	Optional[AxisBand]	band spec for y axis.	None

YAxis

YAxis(
    *,
    series: Optional[
        List[Union[str, TimeseriesSeries]]
    ] = None,
    formatting: Optional[AxisNumberFormatting] = None,
    title: Union[str, WidgetField] = "",
    enable_crosshair: bool = False,
    scale: Optional[AxisScale] = None,
    line: Optional[AxisLine] = None,
    band: Optional[AxisBand] = None
)

Specify y-axis appearance & behavior in Timeseries chart.

Construct specifications for the y-axis of a Timeseries chart with a range of options to customize its appearance and behavior.

Constructor for YAxis.

Parameters:

Name	Type	Description	Default
series	Optional[List[Union[str, TimeseriesSeries]]]	series to be added to the y axis.	None
formatting	Optional[AxisNumberFormatting]	formatting spec for axis labels.	None
title	Union[str, WidgetField]	axis title.	''
enable_crosshair	bool	whether to enable crosshair that follows either the mouse pointer or the hovered point.	False
scale	Optional[AxisScale]	y axis scale, one of AxisScaleSymmetric, AxisScaleDynamic, AxisScalePositive, AxisScaleNegative.	None
line	Optional[AxisLine]	line spec for y axis.	None
band	Optional[AxisBand]	band spec for y axis.	None

add_series

add_series(*series: TimeseriesSeries) -> YAxis

Add series to y axis.

Returns:

Name	Type	Description
YAxis	YAxis	reference to this axis to facilitate inline manipulation.

MirrorYAxis

MirrorYAxis(
    *,
    top_series: Optional[
        List[Union[str, TimeseriesSeries]]
    ] = None,
    bottom_series: Optional[
        List[Union[str, TimeseriesSeries]]
    ] = None,
    formatting: Optional[AxisNumberFormatting] = None,
    title: Union[str, WidgetField] = "",
    enable_crosshair: bool = False,
    scale: Optional[AxisScale] = None,
    line: Optional[AxisLine] = None,
    band: Optional[AxisBand] = None
)

Customize appearance & behavior of mirror y-axis in Timeseries chart.

Construct specifications for the mirror y-axis of a Timeseries chart with a range of options to customize its appearance and behavior.

Constructor for MirrorYAxis.

Parameters:

Name	Type	Description	Default
top_series	Optional[List[Union[str, TimeseriesSeries]]]	series to be added to the top y axis.	None
bottom_series	Optional[List[Union[str, TimeseriesSeries]]]	series to be added to the bottom y axis.	None
formatting	Optional[AxisNumberFormatting]	formatting spec for axis labels.	None
title	Union[str, WidgetField]	axis title.	''
enable_crosshair	bool	whether to enable crosshair that follows either the mouse pointer or the hovered point.	False
scale	Optional[AxisScale]	y axis scale, one of AxisScaleSymmetric, AxisScaleDynamic, AxisScalePositive, AxisScaleNegative.	None
line	Optional[AxisLine]	line spec for y axis.	None
band	Optional[AxisBand]	band spec for y axis.	None

add_bottom_series

add_bottom_series(*series: TimeseriesSeries) -> MirrorYAxis

Add series to top y axis.

Returns:

Name	Type	Description
MirrorYAxis	MirrorYAxis	reference to this axis to facilitate inline manipulation.

Raises:

Type	Description
TimeseriesAxisEmptyDefinitionError	when no series data are added
ChartSeriesNameAlreadyExistsError	when series have duplicated names

add_top_series

add_top_series(*series: TimeseriesSeries) -> MirrorYAxis

Add series to top y axis.

Returns:

Name	Type	Description
MirrorYAxis	MirrorYAxis	reference to this axis to facilitate inline manipulation.

Raises:

Type	Description
TimeseriesAxisEmptyDefinitionError	when no series data are added
ChartSeriesNameAlreadyExistsError	when series have duplicated names

Axis Scales

AxisScaleDynamic

AxisScaleDynamic(*, tick_amount: int = 3)

Dynamically set y-axis extremes for optimal spacing.

Construct specifications for a dynamic scale for the y-axis of a chart. By default, it dynamically calculates axis extremes to minimize dead space in the chart.

Constructor for AxisScaleDynamic.

Parameters:

Name	Type	Description	Default
tick_amount	int	number of ticks beyond min and max.	3

AxisScaleNegative

AxisScaleNegative(
    *,
    min_value: Optional[int] = None,
    intermediate_tick_amount: int = 3
)

Y-axis scale for charts with negative values.

Construct specifications for a scale for the y-axis with only negative values. It assumes the maximum value of the chart to be fixed at 0. Specify a fixed minimum value for the axis with the min_value parameter, which defaults to None, allowing for dynamic calculation of the minimum value.

Constructor for AxisScaleNegative.

Parameters:

Name	Type	Description	Default
min_value	Optional[int]	fixed minimum value for axis. Defaults to None (min value calculated dynamically)	None
intermediate_tick_amount	int	number of extra ticks between extremes.	3

AxisScalePositive

AxisScalePositive(
    *,
    max_value: Optional[int] = None,
    intermediate_tick_amount: int = 3
)

Y-axis scale for charts with positive values.

Construct specifications for a scale for the y-axis with only positive values. It assumes the minimum value of the chart to be fixed at 0. Specify a fixed maximum value for the axis with the max_value parameter, which defaults to None, allowing for dynamic calculation of the maximum value.

Constructor for AxisScalePositive.

Parameters:

Name	Type	Description	Default
max_value	Optional[int]	fixed maximum value for axis. Defaults to None (max value calculated dynamically)	None
intermediate_tick_amount	int	number of extra ticks between extremes.	3

AxisScaleSymmetric

AxisScaleSymmetric(
    *,
    min_value: Optional[int] = None,
    max_value: Optional[int] = None,
    intermediate_tick_amount: int = 1,
    strict: Optional[bool] = None
)

Y-axis scale for charts with positive and negative values.

Construct specifications for a scale for the y-axis with both positive and negative values. It determines extremes based on the maximum absolute value of the data, with 0 added as the middle tick.

Constructor for AxisScaleSymmetric.

Parameters:

Name	Type	Description	Default
min_value	Optional[int]	fixed minimum value for axis. Defaults to None (calculated dynamically).	None
max_value	Optional[int]	fixed maximum value for axis. Defaults to None (calculated dynamically).	None
intermediate_tick_amount	int	number of ticks between min-mid and between mid and max. Defaults to 1 (axis with five ticks)	1
strict	bool	Strict the Symmetry between the min and max value. Defaults to True.	None

Periods

PeriodSelector

PeriodSelector(
    *periods: PeriodType,
    default_selection: Optional[int] = None,
    visible: bool = True
)

Select predefined periods for Timeseries visualization.

Construct specifications for a period selector component of a timeseries widget, select predefined periods for data visualization.

Constructor for PeriodSelector.

Parameters:

Name	Type	Description	Default
periods	PeriodType	specs for periods added into timeseries widget period selector component.	()
default_selection	Optional[int]	choose which period selector to be the default.	None
visible	bool	flag that makes the period selector visible. If False, all periods added and default selection will be ignored.	True

Raises:

Type	Description
TimeseriesPeriodSelectorEmptyDefinitionError	when periods is empty.
TimeseriesPeriodSelectorNoAvailableDefaultOptionError	when the desired default selection element does not exist

Examples:

Create a minimal timeseries widget with a selector

import pandas as pd
from engineai.sdk.dashboard.dashboard import Dashboard
from engineai.sdk.dashboard.widgets import timeseries

data = pd.DataFrame(
    {
        "value": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
    },
    index=pd.date_range("2020-01-01", "2020-01-10"),
)
ts = timeseries.Timeseries(
    data=data,
    period_selector=timeseries.PeriodSelector(
        timeseries.Period.W1,
        timeseries.Period.M1,
        timeseries.Period.ALL,
        default_selection=1,
    ),
)
Dashboard(
    app_slug="engineai-docs-steps",
    workspace_slug="engineai-docs-steps",
    content=ts,
)

Period

Standard time intervals for period selector in Timeseries.

Defines standard periods for a period selector component to choose predefined time intervals for data visualization. Each period represents a lookback relative to the last date of the chart.

Attributes:

Name	Type	Description
D1		1 day.
W1		1 week.
W2		2 weeks.
M1		1 month.
M3		3 months.
M6		6 months.
YTD		Year to date.
Y1		1 year.
Y2		2 years.
Y3		3 years.
Y4		4 years.
Y5		5 years.
ALL		All data.

CustomPeriod

CustomPeriod(
    *,
    label: Optional[str] = None,
    start_date: Union[str, datetime],
    end_date: Union[str, datetime]
)

Define custom time intervals for period selector in Timeseries.

Construct specifications for a custom period for a period selector component to define time intervals.

Constructor for CustomPeriod.

Parameters:

Name	Type	Description	Default
label	Optional[str]	label to show in period selector.	None
start_date	Union[str, datetime]	start date of custom period in a format supported by pandas.to_datetime.	required
end_date	Union[str, datetime]	end date of custom period in a format supported by pandas.to_datetime.	required

Raises:

Type	Description
TimeseriesPeriodSelectorDatesDefinitionError	if end_date <= start_date

Series

AreaSeries

AreaSeries(
    *,
    data_column: Union[str, WidgetField],
    name: Optional[Union[str, GenericLink]] = None,
    styling: Optional[
        Union[Palette, AreaSeriesStyling]
    ] = None,
    entity: Optional[Entities] = None,
    show_in_legend: bool = True,
    required: bool = True,
    visible: bool = True,
    right_axis: bool = False,
    tooltips: Optional[TooltipItems] = None
)

Visualize data as filled areas in Timeseries widget.

Construct specifications for an area series within a Timeseries widget to visualize data as filled areas on the chart.

Constructor for AreaSeries.

Parameters:

Name	Type	Description	Default
data_column	Union[str, WidgetField]	name of column in pandas dataframe(s) used for the values of this series.	required
name	Optional[Union[str, GenericLink]]	series name shown in legend and tooltip.	None
styling	Optional[Union[Palette, AreaSeriesStyling]]	styling spec, by default uses the values from the sequential palette.	None
entity	Optional[Entities]	entity spec.	None
show_in_legend	bool	whether to show series in legend or not.	True
required	bool	Flag to make the Series mandatory. If required == True and no Data the widget will show an error. If required==False and no Data, the widget hides the Series.	True
visible	bool	Flag to make the Series visible when chart is loaded.	True
right_axis	bool	Flag to make the Series visible on the right axis.	False
tooltips	Optional[TooltipItems]	tooltip items to be displayed at Series level.	None

AreaRangeSeries

AreaRangeSeries(
    *,
    low_data_column: Union[str, WidgetField],
    high_data_column: Union[str, WidgetField],
    name: Union[str, GenericLink],
    styling: Optional[
        Union[Palette, AreaRangeSeriesStyling]
    ] = None,
    entity: Optional[Entities] = None,
    show_in_legend: bool = True,
    required: bool = True,
    visible: bool = True,
    right_axis: bool = False,
    tooltips: Optional[TooltipItems] = None
)

Visualize data as filled areas between low and high values.

Construct specifications for an area range series within a Timeseries widget to visualize data as filled areas between low and high values on the chart.

Constructor for AreaRangeSeries.

Parameters:

Name	Type	Description	Default
low_data_column	Union[str, WidgetField]	name of column in pandas dataframe(s) used for the low values of this series.	required
high_data_column	Union[str, WidgetField]	name of column in pandas dataframe(s) used for the high values of this series.	required
name	Union[str, GenericLink]	series name (shown in legend and tooltip).	required
styling	Optional[Union[Palette, AreaRangeSeriesStyling]]	styling spec, by default uses the values from the sequential palette.	None
entity	Optional[Entities]	entity spec.	None
show_in_legend	bool	whether to show series in legend or not.	True
required	bool	Flag to make the Series mandatory. If required == True and no Data the widget will show an error. If required==False and no Data, the widget hides the Series.	True
visible	bool	Flag to make the Series visible when chart is loaded.	True
right_axis	bool	Flag to make the Series visible on the right axis.	False
tooltips	Optional[TooltipItems]	tooltip items to be displayed at Series level.	None

BubbleSeries

BubbleSeries(
    *,
    data_column: Union[str, WidgetField],
    bubble_size_data_column: Union[str, WidgetField],
    name: Optional[Union[str, GenericLink]] = None,
    bubble_name: Optional[Union[str, WidgetField]] = None,
    bubble_size_formatting: Optional[
        NumberFormatting
    ] = None,
    styling: Optional[
        Union[Palette, BubbleSeriesStyling]
    ] = None,
    entity: Optional[Entities] = None,
    show_in_legend: bool = True,
    required: bool = True,
    visible: bool = True,
    right_axis: bool = False,
    tooltips: Optional[TooltipItems] = None
)

Visualize data with bubbles in Timeseries widget.

Construct specifications for a bubble series within a Timeseries widget. Visually represent data with bubbles on the chart. The size of each bubble corresponds to a specific data value, providing an intuitive way to grasp the magnitude of each data point.

Constructor for BubbleSeries.

Parameters:

Name	Type	Description	Default
data_column	Union[str, WidgetField]	name of column in pandas dataframe(s) used for the values of this series associated with the y axis.	required
bubble_size_data_column	Union[str, WidgetField]	name of column in pandas dataframe(s) used for the values of this series associated with the size of the bubble.	required
name	Optional[Union[str, GenericLink]]	series name (shown in legend and tooltip).	None
bubble_name	Optional[Union[str, WidgetField]]	name for the bubble value (show in tooltip).	None
bubble_size_formatting	Optional[NumberFormatting]	formatting spec for size of the bubble (used in tooltip).	None
styling	Optional[Union[Palette, BubbleSeriesStyling]]	styling spec, by default uses the values from the sequential palette.	None
entity	Optional[Entities]	entity spec.	None
show_in_legend	bool	whether to show series in legend or not.	True
required	bool	Flag to make the Series mandatory. If required == True and no Data the widget will show an error. If required==False and no Data, the widget hides the Series.	True
visible	bool	Flag to make the Series visible when chart is loaded.	True
right_axis	bool	Flag to make the Series visible on the right axis.	False
tooltips	Optional[TooltipItems]	tooltip items to be displayed at Series level.	None

add_bubble_transform

add_bubble_transform(*transform: Transform) -> BubbleSeries

Add transform (i.e. apply transform to series data with high column data).

Returns:

Name	Type	Description
BubbleSeries	BubbleSeries	reference to this series to facilitate inline manipulation

ColumnSeries

ColumnSeries(
    *,
    data_column: Union[str, WidgetField],
    name: Optional[Union[str, GenericLink]] = None,
    styling: Optional[
        Union[Palette, ColumnSeriesStyling]
    ] = None,
    entity: Optional[Entities] = None,
    show_in_legend: bool = True,
    required: bool = True,
    visible: bool = True,
    right_axis: bool = False,
    tooltips: Optional[TooltipItems] = None
)

Visualize data as vertical columns in Timeseries widget.

Construct specifications for a column series within a Timeseries widget to visualize data as vertical columns on the chart. Each column represents a distinct data point, with the height of the column reflecting its corresponding value.

Constructor for ColumnSeries.

Parameters:

Name	Type	Description	Default
data_column	Union[str, WidgetField]	name of column in pandas dataframe(s) used for the values of this series.	required
name	Optional[Union[str, GenericLink]]	series name (shown in legend and tooltip).	None
styling	Optional[Union[Palette, ColumnSeriesStyling]]	styling spec, by default uses the values from the sequential palette.	None
entity	Optional[Entities]	entity spec.	None
show_in_legend	bool	whether to show series in legend or not.	True
required	bool	Flag to make the Series mandatory. If required == True and no Data the widget will show an error. If required==False and no Data, the widget hides the Series.	True
visible	bool	Flag to make the Series visible when chart is loaded.	True
right_axis	bool	Flag to make the Series visible on the right axis.	False
tooltips	Optional[TooltipItems]	tooltip items to be displayed at Series level.	None

ErrorBarSeries

ErrorBarSeries(
    *,
    low_data_column: Union[str, WidgetField],
    high_data_column: Union[str, WidgetField],
    name: Optional[Union[str, GenericLink]] = None,
    styling: Optional[
        Union[Palette, ErrorBarSeriesStyling]
    ] = None,
    entity: Optional[Entities] = None,
    show_in_legend: bool = True,
    required: bool = True,
    visible: bool = True,
    right_axis: bool = False,
    tooltips: Optional[TooltipItems] = None
)

Depict data variability with error bars in Timeseries.

Construct specifications for an error bar series within a Timeseries widget, providing a visual representation of the variability or uncertainty associated with data points. Each data point is depicted on the chart along with error bars, which indicate the range of possible values or the extent of deviation from a central value.

Constructor for ErrorBarSeries.

Parameters:

Name	Type	Description	Default
low_data_column	Union[str, WidgetField]	name of data column in pandas dataframe(s) used for the low values of this series.	required
high_data_column	Union[str, WidgetField]	name of data column in pandas dataframe(s) used for the high values of this series.	required
name	Optional[Union[str, GenericLink]]	series name (shown in legend and tooltip).	None
styling	Optional[Union[Palette, ErrorBarSeriesStyling]]	styling spec, by default uses the values from the sequential palette.	None
entity	Optional[Entities]	entity spec.	None
show_in_legend	bool	whether to show series in legend or not.	True
required	bool	Flag to make the Series mandatory. If required == True and no Data the widget will show an error. If required==False and no Data, the widget hides the Series.	True
visible	bool	Flag to make the Series visible when chart is loaded.	True
right_axis	bool	Flag to make the Series visible on the right axis.	False
tooltips	Optional[TooltipItems]	tooltip items to be displayed at Series level.	None

LineSeries

LineSeries(
    *,
    data_column: Union[str, WidgetField],
    name: Optional[Union[str, GenericLink]] = None,
    styling: Optional[
        Union[Palette, LineSeriesStyling]
    ] = None,
    entity: Optional[Entities] = None,
    show_in_legend: bool = True,
    required: bool = True,
    visible: bool = True,
    right_axis: bool = False,
    tooltips: Optional[TooltipItems] = None
)

Visualize data with continuous lines in Timeseries.

Construct specifications for a line series within a Timeseries widget to visualize data as a continuous line connecting data points on the chart. Each data point represents a specific value along the timeline, and the lines provide a clear depiction of the trends and patterns present in the data.

Constructor for LineSeries.

Parameters:

Name	Type	Description	Default
data_column	Union[str, WidgetField]	name of column in pandas dataframe(s) used for the values of this series.	required
name	Optional[Union[str, GenericLink]]	series name (shown in legend and tooltip).	None
styling	Optional[Union[Palette, LineSeriesStyling]]	styling spec, by default uses the values from the sequential palette.	None
entity	Optional[Entities]	entity spec.	None
show_in_legend	bool	whether to show series in legend or not.	True
required	bool	Flag to make the Series mandatory. If required == True and no Data the widget will show an error. If required==False and no Data, the widget hides the Series.	True
visible	bool	Flag to make the Series visible when chart is loaded.	True
right_axis	bool	Flag to make the Series visible on the right axis.	False
tooltips	Optional[TooltipItems]	tooltip items to be displayed at Series level.	None

PointSeries

PointSeries(
    *,
    data_column: Union[str, WidgetField],
    name: Optional[Union[str, GenericLink]] = None,
    styling: Optional[
        Union[Palette, PointSeriesStyling]
    ] = None,
    entity: Optional[Entities] = None,
    show_in_legend: bool = True,
    required: bool = True,
    visible: bool = True,
    right_axis: bool = False,
    tooltips: Optional[TooltipItems] = None
)

Visualize individual data points in Timeseries.

Construct specifications for a point series within a Timeseries widget, enabling users to visualize individual data points on the chart as distinct markers. Each marker represents a specific data value, providing a clear and concise depiction of the data distribution over time.

Constructor for PointSeries.

Parameters:

Name	Type	Description	Default
data_column	Union[str, WidgetField]	name of column in pandas dataframe(s) used for the values of this series.	required
name	Optional[Union[str, GenericLink]]	series name (shown in legend and tooltip).	None
styling	Optional[Union[Palette, PointSeriesStyling]]	styling spec, by default uses the values from the sequential palette.	None
entity	Optional[Entities]	entity spec.	None
show_in_legend	bool	whether to show series in legend or not.	True
required	bool	Flag to make the Series mandatory. If required == True and no Data the widget will show an error. If required==False and no Data, the widget hides the Series.	True
visible	bool	Flag to make the Series visible when chart is loaded.	True
right_axis	bool	Flag to make the Series visible on the right axis.	False
tooltips	Optional[TooltipItems]	tooltip items to be displayed at Series level.	None

ScatterSeries

ScatterSeries(
    *,
    data_column: Union[str, WidgetField],
    name: Optional[Union[str, GenericLink]] = None,
    styling: Optional[
        Union[Palette, ScatterSeriesStyling]
    ] = None,
    entity: Optional[Entities] = None,
    show_in_legend: bool = True,
    required: bool = True,
    visible: bool = True,
    right_axis: bool = False,
    tooltips: Optional[TooltipItems] = None
)

Visualize data as individual points in Timeseries.

Construct specifications for a scatter series within a Timeseries widget to visualize data as individual points on the chart without any connections between them. Each data point is represented by a distinct marker, providing a clear depiction of the data distribution over time.

Constructor for ScatterSeries.

Parameters:

Name	Type	Description	Default
data_column	Union[str, WidgetField]	name of column in pandas dataframe(s) used for the values of this series.	required
name	Optional[Union[str, GenericLink]]	series name (shown in legend and tooltip).	None
styling	Optional[Union[Palette, ScatterSeriesStyling]]	styling spec, by default uses the values from the sequential palette.	None
entity	Optional[Entities]	entity spec.	None
show_in_legend	bool	whether to show series in legend or not.	True
required	bool	Flag to make the Series mandatory. If required == True and no Data the widget will show an error. If required==False and no Data, the widget hides the Series.	True
visible	bool	Flag to make the Series visible when chart is loaded.	True
right_axis	bool	Flag to make the Series visible on the right axis.	False
tooltips	Optional[TooltipItems]	tooltip items to be displayed at Series level.	None

Series Styling

AreaSeriesStyling

AreaSeriesStyling(
    *,
    color_spec: ColorSpec,
    data_column: Optional[TemplatedStringItem] = None,
    marker_symbol: MarkerSymbol = MarkerSymbol.CIRCLE
)

Customize appearance of filled areas in Charts.

Specify styling options for an area series within a Chart widget to customize the appearance of filled areas on the chart.

Constructor for AreaSeriesStyling.

Parameters:

Name	Type	Description	Default
color_spec	ColorSpec	spec for coloring area.	required
data_column	Optional[TemplatedStringItem]	name of column in pandas dataframe(s) used for color spec if a gradient is used. Optional for single colors.	None
marker_symbol	MarkerSymbol	symbol for marker in tooltips and legends.	CIRCLE

Raises:

Type	Description
ChartStylingMissingDataColumnError	if color_spec is ColorDiscreteMap/ColorGradient and data_column has not been specified

AreaRangeSeriesStyling

AreaRangeSeriesStyling(
    *,
    color_spec: ColorSpec,
    data_column: Optional[TemplatedStringItem] = None,
    marker_symbol: MarkerSymbol = MarkerSymbol.CIRCLE
)

Customize appearance of filled areas between values.

Specify styling specifications for an area range series within a Timeseries widget to customize the appearance of filled areas between low and high values on the chart.

Constructor for AreaRangeSeriesStyling.

Parameters:

Name	Type	Description	Default
color_spec	ColorSpec	spec for coloring area range.	required
data_column	Optional[TemplatedStringItem]	name of column in pandas dataframe(s) used for color spec if a gradient is used. Optional for single colors.	None
marker_symbol	MarkerSymbol	symbol for marker in tooltips and legends.	CIRCLE

Raises:

Type	Description
ChartStylingMissingDataColumnError	if color_spec is ColorDiscreteMap/ColorGradient and data_column has not been specified

BubbleCircleSeriesStyling

BubbleCircleSeriesStyling(
    *,
    color_spec: ColorSpec,
    data_column: Optional[TemplatedStringItem] = None,
    label_column: Optional[TemplatedStringItem] = None,
    max_size_percentage: Optional[Union[int, float]] = 0.5,
    min_size_percentage: Optional[Union[int, float]] = 0.2
)

Customize appearance of bubble markers.

Specify styling options for a bubble circle series within a Chart widget to customize the appearance of bubble markers on the chart.

Constructor for BubbleCircleSeriesStyling.

Parameters:

Name	Type	Description	Default
color_spec	ColorSpec	spec for coloring bubble.	required
data_column	Optional[TemplatedStringItem]	name of column in pandas dataframe(s) used for color spec if a gradient is used. Optional for single colors.	None
label_column	Optional[TemplatedStringItem]	name of column in pandas dataframe(s) used for labeling the bubble.	None
max_size_percentage	Optional[Union[int, float]]	Percentage of the highest one of the plot width and height.	0.5
min_size_percentage	Optional[Union[int, float]]	Percentage of the smallest one of the plot width and height.	0.2

Raises:

Type	Description
ChartStylingMissingDataColumnError	if color_spec is ColorDiscreteMap/ColorGradient and data_column has not been specified

BubbleCountrySeriesStyling

BubbleCountrySeriesStyling(
    *,
    country_column: TemplatedStringItem,
    max_size_percentage: Optional[Union[int, float]] = 0.5,
    min_size_percentage: Optional[Union[int, float]] = 0.2
)

Customize appearance of country bubble markers.

Specify styling options for a bubble country series within a Chart widget to customize the appearance of bubble markers representing countries on the chart.

Constructor for BubbleCountrySeriesStyling.

Parameters:

Name	Type	Description	Default
country_column	TemplatedStringItem	name of column in pandas dataframe(s) with country codes.	required
max_size_percentage	Optional[Union[int, float]]	Percentage of the highest one of the plot width and height.	0.5
min_size_percentage	Optional[Union[int, float]]	Percentage of the smallest one of the plot width and height.	0.2

ColumnSeriesStyling

ColumnSeriesStyling(
    *,
    color_spec: ColorSpec,
    data_column: Optional[TemplatedStringItem] = None,
    marker_symbol: MarkerSymbol = MarkerSymbol.SQUARE
)

Customize appearance of vertical columns.

Specify styling options for a column series within a Chart widget to customize the appearance of vertical columns on the chart.

Constructor for ColumnSeriesStyling.

Parameters:

Name	Type	Description	Default
color_spec	ColorSpec	spec for coloring columns.	required
data_column	Optional[TemplatedStringItem]	name of column in pandas dataframe(s) used for color spec if a gradient is used. Optional for single colors.	None
marker_symbol	MarkerSymbol	symbol for marker in tooltips and legends.	SQUARE

Raises:

Type	Description
ChartStylingMissingDataColumnError	if a data_column is not defined when color_spec is a ColorDiscreteMap or ColorGradient

ErrorBarSeriesStyling

ErrorBarSeriesStyling(
    *,
    color_spec: ColorSpec,
    data_column: Optional[TemplatedStringItem] = None,
    marker_symbol: MarkerSymbol = MarkerSymbol.SQUARE
)

Customize appearance of error bars in Chart.

Specify styling options for an error bar series within a Chart widget to customize the appearance of error bars representing data variability or uncertainty on the chart.

Constructor for ErrorBarSeriesStyling.

Parameters:

Name	Type	Description	Default
color_spec	ColorSpec	spec for coloring columns.	required
data_column	Optional[TemplatedStringItem]	name of column in pandas dataframe(s) used for color spec if a gradient is used. Optional for single colors.	None
marker_symbol	MarkerSymbol	symbol for marker in tooltips and legends.	SQUARE

Raises:

Type	Description
ChartStylingMissingDataColumnError	if a data_column is not defined when color_spec is a ColorDiscreteMap or ColorGradient

LineSeriesStyling

LineSeriesStyling(
    *,
    color_spec: Optional[ColorSpec] = None,
    data_column: Optional[TemplatedStringItem] = None,
    dash_style: Union[
        DashStyle, TemplatedStringItem
    ] = DashStyle.SOLID,
    marker_symbol: MarkerSymbol = MarkerSymbol.CIRCLE,
    width: int = 2
)

Customize appearance of lines in Chart.

Specify styling options for a line series within a Chart widget to customize the appearance of the lines connecting data points on the chart.

Constructor for LineSeriesStyling.

Parameters:

Name	Type	Description	Default
color_spec	Optional[ColorSpec]	spec for coloring area.	None
data_column	Optional[TemplatedStringItem]	name of column in pandas dataframe(s) used for color spec if a gradient is used. Optional for single colors.	None
dash_style	Union[DashStyle, TemplatedStringItem]	dash style of line.	SOLID
marker_symbol	MarkerSymbol	symbol for marker in tooltips and legends.	CIRCLE
width	int	width of line.	2

Raises:

Type	Description
ChartStylingMissingDataColumnError	if a data_column is not defined when color_spec is a ColorDiscreteMap or ColorGradient

PointSeriesStyling

PointSeriesStyling(
    *,
    color_spec: ColorSpec,
    data_column: Optional[TemplatedStringItem] = None,
    marker_symbol: MarkerSymbol = MarkerSymbol.CIRCLE
)

Customize appearance of data points in Chart.

Specify styling options for a point series within a Chart widget to customize the appearance of individual data points on the chart.

Constructor for PointSeriesStyling.

Parameters:

Name	Type	Description	Default
color_spec	ColorSpec	spec for coloring columns.	required
data_column	Optional[TemplatedStringItem]	name of column in pandas dataframe(s) used for color spec if a gradient is used. Optional for single colors.	None
marker_symbol	MarkerSymbol	symbol for each point.	CIRCLE

Raises:

Type	Description
ChartStylingMissingDataColumnError	if a data_column is not defined when color_spec is a ColorDiscreteMap or ColorGradient

ScatterSeriesStyling

ScatterSeriesStyling(
    *,
    color_spec: ColorSpec,
    data_column: Optional[TemplatedStringItem] = None,
    marker_symbol: MarkerSymbol = MarkerSymbol.CIRCLE
)

Customize appearance of scatter markers.

Specify styling options for a scatter series within a Timeseries widget to customize the appearance of individual data points represented as scatter markers on the chart.

Constructor for ScatterSeriesStyling.

Parameters:

Name	Type	Description	Default
color_spec	ColorSpec	spec for coloring columns.	required
data_column	Optional[TemplatedStringItem]	name of column in pandas dataframe(s) used for color spec if a gradient is used. Optional for single colors.	None
marker_symbol	MarkerSymbol	symbol for each point.	CIRCLE

Raises:

Type	Description
ChartStylingMissingDataColumnError	if a data_column is not defined when color_spec is a ColorDiscreteMap or ColorGradient

Transform

Transform

Transform(
    *,
    transform: TransformChoices,
    scalar: Optional[Union[int, float]] = None
)

Modify data representation in Timeseries with various transformations.

Define specifications for transforming data within a Timeseries widget to modify or enhance the representation of data series. Select from a range of transformation choices to apply to the data, such as scaling, normalization, or logarithmic transformation, depending on analytical needs.

Constructor for Transform.

Parameters:

Name	Type	Description	Default
transform	TransformChoices	transform to apply to series data.	required
scalar	Optional[Union[int, float]]	Applies scalar value to data. Only applies when using the following transformations ADD, SUBTRACT, DIVIDE and MULTIPLY.	None

TransformChoices

Options for transforming data within Timeseries legend.

Below are the various options for transformations of timeseries data within a Timeseries widget's legend.

Attributes:

Name	Type	Description
CUMSUM		Transform series to the cumulative sum of its values.
CUMPROD		Transform series to the cumulative product of its values.
CUMRETURNPROD		Similar to CUMPROD but fixes the initial value as 0. Example used is to represent Return on Investment.
CUMRETURNSUM		Similar to CUMSUM but fixes the initial value as 0. Example used is to represent Return on Investment.
DRAWDOWN		Calculates drawdown based on the series values. Main use is to measure the decline of an investment from its peak value to its trough value.
INDEX		Transforms the values to an index where the first value is 100 and the rest of the values follow the relative changes of the original data.
ADD		Adds a scalar to all values in the series.
SUBTRACT		Subtracts a scalar to all values in the series.
DIVIDE		Divides a scalar to all values in the series.
MULTIPLY		Multiplies a scalar to all values in the series.

Tooltips

CategoryTooltipItem

CategoryTooltipItem(
    *,
    data_column: TemplatedStringItem,
    formatting: MapperFormatting,
    label: Optional[Union[str, DataField]] = None
)

Customize tooltips for categorical data in Chart widget.

Define specifications for a category tooltip item within a Chart widget to customize the appearance and content of tooltips displayed for categorical data.

Constructor for CategoryTooltipItem.

Parameters:

Name	Type	Description	Default
data_column	TemplatedStringItem	name of column in pandas dataframe(s) used for the value of the tooltip item.	required
formatting	MapperFormatting	tooltip formatting spec.	required
label	Optional[Union[str, DataField]]	label to be used for tooltip item, it can be either a string or a DataField object.	None

DatetimeTooltipItem

DatetimeTooltipItem(
    *,
    data_column: TemplatedStringItem,
    formatting: Optional[DateTimeFormatting] = None,
    label: Optional[Union[str, DataField]] = None
)

Customize tooltips for datetime data in Chart.

Define specifications for a datetime item within a tooltip for a Chart widget to customize the appearance and content of tooltips displayed for datetime data.

Constructor for DatetimeTooltipItem.

Parameters:

Name	Type	Description	Default
data_column	TemplatedStringItem	name of column in pandas dataframe(s) used for the value of the tooltip item.	required
formatting	DateTimeFormatting	tooltip formatting spec Defaults to DateTimeFormatting for Dates (i.e. not include HH:MM).	None
label	Optional[Union[str, DataField]]	label to be used for tooltip item, it can be either a string or a DataField object.	None

NumberTooltipItem

NumberTooltipItem(
    *,
    data_column: TemplatedStringItem,
    formatting: Optional[NumberFormatting] = None,
    label: Optional[Union[str, DataField]] = None
)

Customize tooltips for numerical data in Chart.

Define specifications for a number item within a tooltip for a Chart widget to customize the appearance and content of tooltips displayed for numerical data.

Constructor for NumberTooltipItem.

Parameters:

Name	Type	Description	Default
data_column	TemplatedStringItem	name of column in pandas dataframe(s) used for the value of the tooltip item.	required
formatting	Optional[NumberFormatting]	tooltip formatting spec. Defaults to None (Base NumberFormatting).	None
label	Optional[Union[str, DataField]]	label to be used for tooltip item, it can be either a string or a DataField object.	None

TextTooltipItem

TextTooltipItem(
    *,
    data_column: TemplatedStringItem,
    formatting: Optional[TextFormatting] = None,
    label: Optional[Union[str, DataField]] = None
)

Customize tooltips for textual data in Chart.

Define specifications for a text item within a tooltip for a Chart widget to customize the appearance and content of tooltips displayed for textual data.

Constructor for TextTooltipItem.

Parameters:

Name	Type	Description	Default
data_column	TemplatedStringItem	name of column in pandas dataframe(s) used for the value of the tooltip item.	required
formatting	Optional[TextFormatting]	tooltip formatting spec. Defaults to TextFormatting(max_characters=30).	None
label	Optional[Union[str, DataField]]	label to be used for tooltip item, it can be either a string or a DataField object.	None

Enums

DashStyle

Enum to specify dash style of lines.

Attributes:

Name	Type	Description
SOLID		Solid line.
DOT		Dotted line.
DASH		Dashed line.
SHORT_DASH		Short dashed line.
LONG_DASH		Long dashed line.
SHORT_DASH_DOT		Short dashed dotted line.
LONG_DASH_DOT		Long dashed dotted line.

MarkerSymbol

Enum to specify marker symbol.

Attributes:

Name	Type	Description
CROSS		Cross symbol.
TRIANGLE		Triangle symbol.
CIRCLE		Circle symbol.
DIAMOND		Diamond symbol.
SQUARE		Square symbol.
TRIANGLE_DOWN		Triangle down symbol.

LegendPosition

Chart legend position options.

Options for positions of charts legend.

Attributes:

Name	Type	Description
RIGHT	str	Legend is placed to the right of the chart.
BOTTOM	str	Legend is placed below the chart.
RIGHT_GROUPED	str	Legend is placed to the right of the chart and grouped with other legends.
BOTTOM_GROUPED	str	Legend is placed below the chart and grouped with other legends.
NEXT_TO_DATA	str	Legend is placed next to the data.

Axis lines and bands

AxisLine

AxisLine(
    data: Union[DataType, DataFrame],
    *,
    data_column: str,
    label: Optional[Union[str, AxisLabel]] = None,
    styling: Optional[
        Union[Palette, AxisLineStyling]
    ] = None,
    dash_style: DashStyle = DashStyle.DASH
)

Spec for Axis Line.

Construct a plot line for an axis.

Parameters:

Name	Type	Description	Default
data	Union[DataType, DataFrame]	data source for the Axis line.	required
data_column	str	name of column in pandas dataframe(s) used for the value of axis line	required
label	Optional[Union[str, AxisLabel]]	label annotation.	None
styling	Optional[Union[Palette, AxisLineStyling]]	specs for chart band styling.	None
dash_style	DashStyle	line dash style.	DASH

AxisBand

AxisBand(
    data: Union[DataType, DataFrame],
    *,
    from_column: str,
    to_column: str,
    label: Optional[Union[str, AxisLabel]] = None,
    styling: Optional[
        Union[Palette, AxisBandStyling]
    ] = None
)

Spec for Axis Band.

Construct a plot line for an axis.

Parameters:

Name	Type	Description	Default
data	Union[DataType, DataFrame]	data source for the Axis Band.	required
from_column	str	name of column in pandas dataframe(s) used for the start value for the band.	required
to_column	str	name of column in pandas dataframe(s) used for the end value for the band.	required
label	Optional[Union[str, AxisLabel]]	label annotation.	None
styling	Optional[Union[Palette, AxisBandStyling]]	specs for chart band styling.	None

AxisLabel

AxisLabel(
    *,
    text: Optional[Union[str, DataField]] = None,
    x_position: Union[int, DataField] = -5,
    y_position: Union[int, DataField] = 2,
    horizontal_align: HorizontalAlignment = HorizontalAlignment.CENTER,
    vertical_align: VerticalAlignment = VerticalAlignment.TOP,
    rotation: Optional[Union[float, int]] = -90
)

Spec for label of axis band or line.

Construct spec for label of axis band or line.

Parameters:

Name	Type	Description	Default
text	Optional[Union[str, DataField]]	name of column in pandas dataframe(s) used for the label text.	None
x_position	Union[int, DataField]	name of column in pandas dataframe(s) used for the x value for the label position.	-5
y_position	Union[int, DataField]	name of column in pandas dataframe(s) used for they value for the label position.	2
horizontal_align	HorizontalAlignment	horizontal alignment spec.	CENTER
vertical_align	VerticalAlignment	vertical alignment spec.	TOP
rotation	Optional[Union[float, int]]	Rotation of the text label in degrees.	-90