Categorical

Categorical

Categorical(
    data: Union[DataType, DataFrame],
    *,
    category_axis: Union[
        str, WidgetField, CategoryAxis
    ] = "category",
    value_axis: Optional[
        Union[ValueAxisSeries, ValueAxis]
    ] = None,
    secondary_value_axis: Optional[
        Union[ValueAxisSeries, ValueAxis]
    ] = None,
    widget_id: Optional[str] = None,
    legend_position: LegendPosition = LegendPosition.BOTTOM,
    title: Optional[WidgetTitleType] = None,
    enable_toolbar: bool = True,
    direction: ChartDirection = ChartDirection.VERTICAL,
    tooltips: Optional[List[TooltipItem]] = None
)

Spec for Categorical widget.

Construct spec for a Categorical widget.

Parameters:

Name	Type	Description	Default
data	Union[DataType, DataFrame]	data source for the widget.	required
widget_id	Optional[str]	unique widget id in a dashboard.	None
category_axis	Union[str, WidgetField, CategoryAxis]	spec for category axis.	'category'
value_axis	Optional[Union[ValueAxisSeries, ValueAxis]]	spec for main value axis.	None
secondary_value_axis	Optional[Union[ValueAxisSeries, ValueAxis]]	Spec for secondary value axis.	None
legend_position	LegendPosition	legend of Categorical widget.	BOTTOM
title	Optional[WidgetTitleType]	title of widget can be either a string (fixed value) or determined by a value from another widget using a WidgetField.	None
enable_toolbar	bool	Enable/Disable toolbar flag.	True
direction	ChartDirection	option to set the direction for series in the Chart.	VERTICAL
tooltips	Optional[List[TooltipItem]]	list of tooltip items.	None

Examples:

Create a minimal Categorical Widget

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

data = pd.DataFrame(
    [
        {"category": "Apple", "value": 100, "value_2": 1999},
        {"category": "Microsoft", "value": 200, "value_2": 2999},
    ]
)

categorical_widget = categorical.Categorical(data=data)

Dashboard(content=categorical_widget)

Create a Categorical Widget with value Axis and secondary value Axis

import pandas as pd
from engineai.sdk.dashboard import dashboard
from engineai.sdk.dashboard.widgets import categorical

data = pd.DataFrame(
    [
        {
            "company": "Apple",
            "shares_short": 700,
            "volume": 1200,
            "market_cap": 1500,
        },
        {
            "company": "Microsoft",
            "shares_short": 900,
            "volume": 1600,
            "market_cap": 2000,
        },
    ]
)

categorical_widget = categorical.Categorical(
    data=data,
    category_axis=categorical.CategoryAxis(
        data_column="company",
    ),
    value_axis=categorical.ValueAxis(
        [
            categorical.PointSeries(
                data_column="volume",
            ),
            categorical.ColumnSeries(
                data_column="shares_short",
            ),
        ]
    ),
    secondary_value_axis=categorical.ValueAxis(
        categorical.BubbleSeries(
            name="Market Cap vs Volume",
            data_column="volume",
            bubble_size_data_column="market_cap",
            bubble_name="Market Cap",
        )
    ),
)

dashboard.Dashboard(content=categorical_widget)

Components

CategoryAxis

CategoryAxis(
    *,
    data_column: Union[str, GenericLink],
    label_column: Optional[Union[str, GenericLink]] = None,
    title: Union[str, GenericLink] = "",
    enable_crosshair: bool = False,
    line: Optional[AxisLine] = None,
    band: Optional[AxisBand] = None
)

Specs for category axis of a Categorical chart.

Construct category axis for a Categorical chart.

Parameters:

Name	Type	Description	Default
title	Union[str, GenericLink]	axis title.	''
data_column	Union[str, GenericLink]	name of column in pandas dataframe(s) used for Category axis values.	required
enable_crosshair	bool	whether to enable crosshair that follows either the mouse pointer or the hovered point.	False
label_column	Optional[Union[str, GenericLink]]	name of column in pandas dataframe(s) used for the label of each category. Same values are used for each series.	None
line	Optional[AxisLine]	specs for chart axis line.	None
band	Optional[AxisBand]	specs for chart axis band.	None

ValueAxis

ValueAxis(
    *,
    series: ValueAxisSeries,
    formatting: Optional[AxisNumberFormatting] = None,
    title: Optional[Union[str, GenericLink]] = None,
    enable_crosshair: bool = False,
    scale: Optional[AxisScale] = None,
    line: Optional[AxisLine] = None,
    band: Optional[AxisBand] = None
)

Specs for Value Axis of a Categorical chart.

Construct Value Axis for a Categorical chart.

Parameters:

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

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.

ChartDirection

Options for directions of categorical chart.

Attributes:

Name	Type	Description
VERTICAL		Chart with a vertical direction.
HORIZONTAL		Chart with a horizontal direction.

Series

AreaSeries

AreaSeries(
    *,
    data_column: Union[str, GenericLink],
    name: Optional[Union[str, GenericLink]] = None,
    styling: Optional[
        Union[Palette, AreaSeriesStyling]
    ] = None,
    stacked: bool = False,
    show_in_legend: bool = True,
    required: bool = True,
    visible: bool = True,
    tooltips: Optional[List[TooltipItem]] = None
)

Spec for a Area Series of a Categorical widget.

Construct Area Series.

Parameters:

Name	Type	Description	Default
data_column	Union[str, GenericLink]	name of column in pandas dataframe(s) used for the values of this series for the Y Axis.	required
name	Optional[Union[str, GenericLink]]	series name (shown in legend and tooltip).	None
styling	Optional[Union[Palette, AreaSeriesStyling]]	styling spec.	None
stacked	bool	whether area is stacked or not.	False
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
tooltips	Optional[List[TooltipItem]]	Tooltip items to show in the tooltip.	None

AreaRangeSeries

AreaRangeSeries(
    *,
    low_data_column: Union[str, GenericLink],
    high_data_column: Union[str, GenericLink],
    name: Union[str, GenericLink],
    styling: Optional[
        Union[Palette, AreaRangeSeriesStyling]
    ] = None,
    show_in_legend: bool = True,
    required: bool = True,
    visible: bool = True,
    tooltips: Optional[List[TooltipItem]] = None
)

Spec for a Area Range Series of a Categorical widget.

Construct Area Range Series.

Parameters:

Name	Type	Description	Default
low_data_column	Union[str, GenericLink]	name of column in pandas dataframe(s) used for the low values of this series.	required
high_data_column	Union[str, GenericLink]	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.	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
tooltips	Optional[List[TooltipItem]]	Tooltip items to show in the tooltip.	None

BubbleSeries

BubbleSeries(
    *,
    bubble_size_data_column: Union[str, GenericLink],
    data_column: Union[str, GenericLink],
    name: Optional[Union[str, GenericLink]] = None,
    bubble_name: Optional[Union[str, GenericLink]] = None,
    bubble_size_formatting: Optional[
        NumberFormatting
    ] = None,
    styling: Optional[
        Union[Palette, BubbleSeriesStyling]
    ] = None,
    show_in_legend: bool = True,
    required: bool = True,
    visible: bool = True,
    tooltips: Optional[List[TooltipItem]] = None
)

Spec for a Bubble Series of a Categorical widget.

Construct a Bubble Series.

Parameters:

Name	Type	Description	Default
bubble_size_data_column	Union[str, GenericLink]	name of column in pandas dataframe(s) used for the values of this series associated with the size of the bubble.	required
data_column	Union[str, GenericLink]	name of column in pandas dataframe(s) used for the values of this series for the Y Axis.	required
name	Optional[Union[str, GenericLink]]	series name (shown in legend and tooltip).	None
bubble_name	Optional[Union[str, GenericLink]]	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.	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
tooltips	Optional[List[TooltipItem]]	Tooltip items to show in the tooltip.	None

ErrorBarSeries

ErrorBarSeries(
    *,
    low_data_column: Union[str, GenericLink],
    high_data_column: Union[str, GenericLink],
    name: Optional[Union[str, GenericLink]] = None,
    styling: Optional[
        Union[Palette, ErrorBarSeriesStyling]
    ] = None,
    stack: Optional[Union[str, GenericLink]] = None,
    show_in_legend: bool = True,
    required: bool = True,
    visible: bool = True,
    tooltips: Optional[List[TooltipItem]] = None
)

Spec forError Bar Series of a Categorical widget.

Construct Column Series.

Parameters:

Name	Type	Description	Default
low_data_column	Union[str, GenericLink]	name of column in pandas dataframe(s) used for the low value of this series.	required
high_data_column	Union[str, GenericLink]	name of column in pandas dataframe(s) used for the high value of this series.	required
name	Optional[Union[str, GenericLink]]	series name (shown in legend and tooltip).	None
styling	Optional[Union[Palette, ErrorBarSeriesStyling]]	styling spec.	None
stack	Optional[Union[str, GenericLink]]	id of stack for column.	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
tooltips	Optional[List[TooltipItem]]	Tooltip items to show in the tooltip.	None

ColumnSeries

ColumnSeries(
    *,
    data_column: Union[str, GenericLink],
    name: Optional[Union[str, GenericLink]] = None,
    styling: Optional[
        Union[Palette, ColumnSeriesStyling]
    ] = None,
    stack: Optional[Union[str, GenericLink]] = None,
    show_in_legend: bool = True,
    required: bool = True,
    visible: bool = True,
    tooltips: Optional[List[TooltipItem]] = None
)

Spec for a Column Series of a Categorical widget.

Construct Column Series.

Parameters:

Name	Type	Description	Default
data_column	Union[str, GenericLink]	name of column in pandas dataframe(s) used for the values of this series for the Y Axis.	required
name	Optional[Union[str, GenericLink]]	series name (shown in legend and tooltip).	None
styling	Optional[Union[Palette, ColumnSeriesStyling]]	styling spec.	None
stack	Optional[Union[str, GenericLink]]	id of stack for column.	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
tooltips	Optional[List[TooltipItem]]	Tooltip items to show in the tooltip.	None

LineSeries

LineSeries(
    *,
    data_column: Union[str, GenericLink],
    name: Optional[Union[str, GenericLink]] = None,
    styling: Optional[
        Union[Palette, LineSeriesStyling]
    ] = None,
    show_in_legend: bool = True,
    required: bool = True,
    visible: bool = True,
    tooltips: Optional[List[TooltipItem]] = None
)

Spec for a Line Series of a Categorical widget.

Construct Line Series.

Parameters:

Name	Type	Description	Default
data_column	Union[str, GenericLink]	name of column in pandas dataframe(s) used for the values of this series for the Y Axis.	required
name	Optional[Union[str, GenericLink]]	series name (shown in legend and tooltip).	None
styling	Optional[Union[Palette, LineSeriesStyling]]	styling 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
tooltips	Optional[List[TooltipItem]]	Tooltip items to show in the tooltip.	None

PointSeries

PointSeries(
    *,
    data_column: Union[str, GenericLink],
    name: Optional[Union[str, GenericLink]] = None,
    styling: Optional[
        Union[Palette, PointSeriesStyling]
    ] = None,
    show_in_legend: bool = True,
    required: bool = True,
    visible: bool = True,
    tooltips: Optional[List[TooltipItem]] = None
)

Spec for a Point Series of a Categorical widget.

Construct Point Series.

Parameters:

Name	Type	Description	Default
data_column	Union[str, GenericLink]	name of column in pandas dataframe(s) used for the values of this series for the Y Axis.	required
name	Optional[Union[str, GenericLink]]	series name (shown in legend and tooltip).	None
styling	Optional[Union[Palette, PointSeriesStyling]]	styling 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
tooltips	Optional[List[TooltipItem]]	Tooltip items to show in the tooltip.	None

ScatterSeries

ScatterSeries(
    *,
    data_column: Union[str, GenericLink],
    name: Optional[Union[str, GenericLink]] = None,
    styling: Optional[
        Union[Palette, ScatterSeriesStyling]
    ] = None,
    show_in_legend: bool = True,
    required: bool = True,
    visible: bool = True,
    tooltips: Optional[List[TooltipItem]] = None
)

Spec for a Scatter Series of a Categorical widget.

Construct Scatter Series.

Parameters:

Name	Type	Description	Default
data_column	Union[str, GenericLink]	name of column in pandas dataframe(s) used for the values of this series for the Y Axis.	required
name	Optional[Union[str, GenericLink]]	series name (shown in legend and tooltip).	None
styling	Optional[Union[Palette, ScatterSeriesStyling]]	styling 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
tooltips	Optional[List[TooltipItem]]	Tooltip items to show in the tooltip.	None

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

Value 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