Chart View

Chart view components for the UI Generator framework.

This module provides chart visualization capabilities through the ChartView and CombinationChartView classes. Charts are powerful tools for visualizing data trends, comparisons, distributions, and relationships in an intuitive graphical format.

Chart views transform tabular data into visual representations including bar charts, line charts, pie charts, scatter plots, and more. They support multiple data series, customizable styling, interactive tooltips, and flexible axis configurations.

The CombinationChartView extends ChartView to support:

Mixed chart types in a single visualization (e.g., line + bar)
Multiple chart components with independent configurations
Complex multi-dimensional data presentations

Classes:

ChartView: Standard chart view supporting various chart types
CombinationChartView: Advanced chart view for mixed chart type visualizations

Example

>>> # Define the data source
>>> sales_table = Table("monthly_sales")
>>>
>>> # Create chart series
>>> primary_series = ChartSeries(
...     source_field=Field("month", DataType.STRING),
...     name="Month"
... )
>>> secondary_series = ChartSeries(
...     source_field=Field("revenue", DataType.DECIMAL),
...     name="Revenue"
... )
>>>
>>> # Create and register a bar chart
>>> builder = UiBuilder()
>>> chart_view = builder.add_chart_view(
...     primary_series=primary_series,
...     chart_type=ChartType.BAR,
...     table=sales_table,
...     display_name="Sales Dashboard"
... )
>>>
>>> # Configure chart properties
>>> chart_view.set_chart_title("Monthly Revenue")
>>> chart_view.set_secondary_series(secondary_series)
>>> chart_view.xaxis_label = "Month"
>>> chart_view.yaxis_label = "Revenue ($)"
>>> chart_view.orientation = ChartViewOrientation.VERTICAL
>>>
>>> # Add additional data series for comparison
>>> chart_view.add_data_series(
...     source_field=Field("target_revenue", DataType.DECIMAL),
... )

class ChartView(primary_series, chart_type, table, display_name=None, hidden=False)[source]

Bases: BaseView, FilterableView

Represents a chart view configuration within the UI model. This class defines chart metadata, axes configuration, series data, and rendering behaviour.

table

The table providing the source data for this chart.

Type:: str

chart_title

Title text displayed above the chart.

Type:: ChartSeries

primary_series

The primary chart series used to position or group data points.

Type:: ChartSeries

secondary_series

Additional series used for secondary grouping or comparative displays.

Type:: ChartSeries

orientation

Orientation of the chart (vertical or horizontal).

Type:: ChartViewOrientation

type

Type of chart to render (line, bar, pie, scatter, etc.).

Type:: ChartType

stacking

Stacking behaviour for multi-series charts (normal or percent).

Type:: ChartViewStacking

xaxis_label

Label text displayed along the X-axis.

Type:: str | None

yaxis_label

Label text displayed along the Y-axis.

Type:: str | None

xaxis_type

Defines how x-axis values are interpreted (e.g., numeric, category, datetime).

Type:: str | None

ignore_empty_series

Whether to hide or skip rendering for data series with no values.

Type:: bool

point_label

Custom label displayed on individual data points (if supported).

Type:: str | None

tooltip

Tooltip text or template for hover interactions.

Type:: str | None

data_series

A list of additional chart data series beyond the primary and secondary series.

Type:: list[ChartSeries]

series_colors

Optional colour overrides applied to series in rendering order.

Type:: list[str] | None

__init__(primary_series, chart_type, table, display_name=None, hidden=False)[source]

Parameters:

primary_series (ChartSeries) – The primary data series for the chart.
chart_type (ChartType) – The chart type to render.
table (Table) – The source data table.
display_name (str | None) – Optional display name for this view.
hidden (bool) – If True, the view is not visible in the UI.

Raises:

ValueError – If any series references a field not present in table.

set_chart_title(chart_title)[source]

Sets the title displayed above the chart.

Return type:: ChartView

set_secondary_series(secondary_series)[source]

Sets the secondary data series for comparative display.

Return type:: ChartView

set_use_filter(use_filter)[source]

Attaches a filter component to this chart view.

Return type:: ChartView

add_data_series(source_field)[source]

Adds a new data series to the chart.

Parameters:: source_field (Field) – Name of the field supplying values for this series.
Returns:: The constructed series for further configuration via setters.
Return type:: ChartSeries
Raises:: ValueError – If the field does not exist in the associated table.

add_series_color(color)[source]

Appends a color value to the list of series-level color overrides.

Parameters:: color (str) – A color code or name used to override chart series colors in rendering order.

class CombinationChartView(primary_series, chart_type, table, display_name=None, hidden=False)[source]

Bases: ChartView

A view definition used for rendering combination charts.

This class extends ChartView by allowing multiple CombinationChartComponent objects to be attached to the chart. A combination chart typically includes multiple dataset types or multiple chart styles (e.g., line + bar), which are represented as individual components.

Parameters:

display_name (str | None) – Display name of the chart view.
hidden (bool) – Whether the chart view should be initially hidden.
table (Table) – Optional data source table from which the chart values are derived.
chart_title – Title displayed above the chart.
primary_series (ChartSeries) – Primary data series associated with the chart.
secondary_series – Secondary data series (if applicable).

__init__(primary_series, chart_type, table, display_name=None, hidden=False)[source]

Parameters:

primary_series (ChartSeries) – The primary data series for the chart.
chart_type (ChartType) – The default chart type for new components.
table (Table) – The source data table.
display_name (str | None) – Optional display name for this view.
hidden (bool) – If True, the view is not visible in the UI.

add_combination_chart_component(chart_component)[source]

Add a CombinationChartComponent to the view with field validation.

This method validates all data series defined within the given CombinationChartComponent to ensure that their source_field and optional display_field exist in the associated table. If any referenced field does not exist, a ValueError is raised.

Parameters:: chart_component (CombinationChartComponent) – The combination chart component containing one or more ChartSeries definitions to attach to this view.
Raises:: ValueError – If any series references a source_field or display_field that does not exist in the underlying table.