Categorical#

Categorical #

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

Spec for Categorical widget.

Construct spec for a Categorical widget.

Parameters:

Name	Type	Description	Default
`data`	`DataType \| DataFrame`	data source for the widget.	required
`widget_id`	`str \| None`	unique widget id in a dashboard.	`None`
`category_axis`	`str \| WidgetField \| CategoryAxis`	spec for category axis.	`'category'`
`value_axis`	`ValueAxisSeries \| ValueAxis \| None`	spec for main value axis.	`None`
`secondary_value_axis`	`ValueAxisSeries \| ValueAxis \| None`	Spec for secondary value axis.	`None`
`legend_position`	`LegendPosition`	legend of Categorical widget.	`BOTTOM`
`title`	`WidgetTitleType \| None`	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`	`list[TooltipItem] \| None`	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: str | GenericLink,
    label_column: str | GenericLink | None = None,
    title: str | GenericLink = "",
    enable_crosshair: bool = False,
    line: AxisLine | None = None,
    band: AxisBand | None = None,
)

Specs for category axis of a Categorical chart.

Construct category axis for a Categorical chart.

Parameters:

Name	Type	Description	Default
`title`	`str \| GenericLink`	axis title.	`''`
`data_column`	`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`	`str \| GenericLink \| None`	name of column in pandas dataframe(s) used for the label of each category. Same values are used for each series.	`None`
`line`	`AxisLine \| None`	specs for chart axis line.	`None`
`band`	`AxisBand \| None`	specs for chart axis band.	`None`

ValueAxis #

ValueAxis(
    *,
    series: ValueAxisSeries,
    formatting: AxisNumberFormatting | None = None,
    title: str | GenericLink | None = None,
    enable_crosshair: bool = False,
    scale: AxisScale | None = None,
    line: AxisLine | None = None,
    band: AxisBand | None = 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`	`AxisNumberFormatting \| None`	formatting spec for axis labels.	`None`
`title`	`str \| GenericLink \| None`	axis title.	`None`
`scale`	`AxisScale \| None`	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`	`AxisLine \| None`	line to be added to the axis.	`None`
`band`	`AxisBand \| None`	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: str | GenericLink,
    name: str | GenericLink | None = None,
    styling: Palette | AreaSeriesStyling | None = None,
    stacked: bool = False,
    show_in_legend: bool = True,
    required: bool = True,
    visible: bool = True,
    tooltips: list[TooltipItem] | None = None,
)

Spec for a Area Series of a Categorical widget.

Construct Area Series.

Parameters:

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

AreaRangeSeries #

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

Spec for a Area Range Series of a Categorical widget.

Construct Area Range Series.

Parameters:

Name	Type	Description	Default
`low_data_column`	`str \| GenericLink`	name of column in pandas dataframe(s) used for the low values of this series.	required
`high_data_column`	`str \| GenericLink`	name of column in pandas dataframe(s) used for the high values of this series.	required
`name`	`str \| GenericLink`	series name (shown in legend and tooltip).	required
`styling`	`Palette \| AreaRangeSeriesStyling \| None`	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`	`list[TooltipItem] \| None`	Tooltip items to show in the tooltip.	`None`

BubbleSeries #

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

Spec for a Bubble Series of a Categorical widget.

Construct a Bubble Series.

Parameters:

Name	Type	Description	Default
`bubble_size_data_column`	`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`	`str \| GenericLink`	name of column in pandas dataframe(s) used for the values of this series for the Y Axis.	required
`name`	`str \| GenericLink \| None`	series name (shown in legend and tooltip).	`None`
`bubble_name`	`str \| GenericLink \| None`	name for the bubble value (show in tooltip).	`None`
`bubble_size_formatting`	`NumberFormatting \| None`	formatting spec for size of the bubble (used in tooltip).	`None`
`styling`	`Palette \| BubbleSeriesStyling \| None`	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`	`list[TooltipItem] \| None`	Tooltip items to show in the tooltip.	`None`

ErrorBarSeries #

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

Spec forError Bar Series of a Categorical widget.

Construct Column Series.

Parameters:

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

ColumnSeries #

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

Spec for a Column Series of a Categorical widget.

Construct Column Series.

Parameters:

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

LineSeries #

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

Spec for a Line Series of a Categorical widget.

Construct Line Series.

Parameters:

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

PointSeries #

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

Spec for a Point Series of a Categorical widget.

Construct Point Series.

Parameters:

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

ScatterSeries #

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

Spec for a Scatter Series of a Categorical widget.

Construct Scatter Series.

Parameters:

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

Tooltips#

CategoryTooltipItem #

CategoryTooltipItem(
    *,
    data_column: TemplatedStringItem,
    formatting: MapperFormatting,
    label: str | DataField | None = 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: DateTimeFormatting | None = None,
    label: str | DataField | None = 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: NumberFormatting | None = None,
    label: str | DataField | None = 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`	`NumberFormatting \| None`	tooltip formatting spec. Defaults to None (Base NumberFormatting).	`None`
`label`	`str \| DataField \| None`	label to be used for tooltip item, it can be either a string or a DataField object.	`None`

TextTooltipItem #

TextTooltipItem(
    *,
    data_column: TemplatedStringItem,
    formatting: TextFormatting | None = None,
    label: str | DataField | None = 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: DataType | DataFrame,
    *,
    data_column: str,
    label: str | AxisLabel | None = None,
    styling: Palette | AxisLineStyling | None = None,
    dash_style: DashStyle = DASH,
)

Spec for Axis Line.

Construct a plot line for an axis.

Parameters:

Name	Type	Description	Default
`data`	`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`	`str \| AxisLabel \| None`	label annotation.	`None`
`styling`	`Palette \| AxisLineStyling \| None`	specs for chart band styling.	`None`
`dash_style`	`DashStyle`	line dash style.	`DASH`

AxisBand #

AxisBand(
    data: DataType | DataFrame,
    *,
    from_column: str,
    to_column: str,
    label: str | AxisLabel | None = None,
    styling: Palette | AxisBandStyling | None = None,
)

Spec for Axis Band.

Construct a plot line for an axis.

Parameters:

Name	Type	Description	Default
`data`	`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`	`str \| AxisLabel \| None`	label annotation.	`None`
`styling`	`Palette \| AxisBandStyling \| None`	specs for chart band styling.	`None`

AxisLabel #

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

Spec for label of axis band or line.

Construct spec for label of axis band or line.

Parameters:

Name	Type	Description	Default
`text`	`str \| DataField \| None`	name of column in pandas dataframe(s) used for the label text.	`None`
`x_position`	`int \| DataField`	name of column in pandas dataframe(s) used for the x value for the label position.	`-5`
`y_position`	`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`	`float \| int \| None`	Rotation of the text label in degrees.	`-90`