Charts

Chart and data visualization components for the UI Generator.

This module provides a comprehensive charting system for creating interactive data visualizations. It supports multiple chart types, customizable data series, marker configurations, and combination charts that can display multiple series with different visualization styles.

Main Components

Chart Types:

ChartType enum defines available visualization types:

Line-based:

• LINE: Standard line chart with straight segments

• SPLINE: Smoothed line chart using spline curves

• AREA: Line chart with filled area underneath

• AREA_SPLINE: Smoothed area chart

Bar-based:

• BAR: Vertical bar chart for categorical data

• BAR_RANGE: Bar chart showing value ranges

Statistical:

• BOX_PLOT: Distribution visualization with quartiles and outliers

• SCATTER: Individual data points on x-y axis

Range-based:

• AREA_RANGE: Area chart showing min-max ranges

Proportional:

• PIE: Circular chart showing proportional values

Configuration Enums:

• ChartViewOrientation: VERTICAL, HORIZONTAL (chart layout direction)

• ChartViewStacking: NORMAL, PERCENT (how series stack)

• DataPointMarkerSymbol: CIRCLE, SQUARE, TRIANGLE, DIAMOND, TRIANGLE_DOWN

Core Classes:

• DataPointMarker: Visual configuration for individual data points

• ChartSeries: Single data series with styling and source field

• CombinationChartComponent: Main chart container supporting multiple series

Stacking Modes

NORMAL Stacking:

Series values are added on top of each other to show cumulative totals. Each segment shows its absolute value contribution to the total.

PERCENT Stacking:

Series values are converted to percentages of the total for each category. The chart always reaches 100%, showing relative proportions rather than absolute values.

Data Point Markers

Markers can be customized with:

• symbol: Shape (circle, square, triangle, diamond, triangle down)

• radius: Size in pixels

• fill_color: Interior color

• line_color: Border/outline color

• line_width: Border width in pixels

Markers help identify individual data points and can differentiate series.

Combination Charts

CombinationChartComponent allows multiple data series with potentially different chart types in the same visualization. This enables:

• Comparing different metrics on the same axis

• Overlaying trend lines on bar charts

• Mixing line and area series

• Creating complex multi-metric dashboards

Examples

Creating a simple line chart:

from daitum_ui.charts import (
    CombinationChartComponent,
    ChartType,
    ChartViewOrientation
)

# Create line chart component
line_chart = CombinationChartComponent(
    chart_type=ChartType.LINE,
    orientation=ChartViewOrientation.VERTICAL
)

# Add data series
line_chart.add_data_series(
    source_field=sales_table.revenue_field,
    name="Monthly Revenue",
    color="#2196f3"
)

Creating a stacked area chart:

from daitum_ui.charts import ChartViewStacking

# Stacked area chart showing composition over time
stacked_area = CombinationChartComponent(
    chart_type=ChartType.AREA,
    stacking=ChartViewStacking.NORMAL,
    orientation=ChartViewOrientation.VERTICAL
)

# Add multiple series that will stack
stacked_area.add_data_series(
    source_field=sales_table.product_a_field,
    name="Product A",
    color="#4caf50"
)
stacked_area.add_data_series(
    source_field=sales_table.product_b_field,
    name="Product B",
    color="#ff9800"
)
stacked_area.add_data_series(
    source_field=sales_table.product_c_field,
    name="Product C",
    color="#f44336"
)

Creating a scatter plot with custom markers:

from daitum_ui.charts import DataPointMarker, DataPointMarkerSymbol

# Scatter plot with custom markers
scatter_chart = CombinationChartComponent(
    chart_type=ChartType.SCATTER
)

# Custom marker configuration
custom_marker = DataPointMarker(
    symbol=DataPointMarkerSymbol.DIAMOND,
    radius=6,
    fill_color="#9c27b0",
    line_color="#ffffff",
    line_width=2
)

scatter_chart.add_data_series(
    source_field=analysis_table.correlation_field,
    name="Correlation Data",
    marker=custom_marker
)

Creating a percentage stacked bar chart:

# Percentage stacked bar chart
percent_stack = CombinationChartComponent(
    chart_type=ChartType.BAR,
    stacking=ChartViewStacking.PERCENT,
    orientation=ChartViewOrientation.VERTICAL
)

percent_stack.add_data_series(
    source_field=survey_table.option_a_field,
    name="Strongly Agree"
)
percent_stack.add_data_series(
    source_field=survey_table.option_b_field,
    name="Agree"
)
percent_stack.add_data_series(
    source_field=survey_table.option_c_field,
    name="Neutral"
)

Creating a combination chart with different series types:

# Combination chart with multiple series
combo_chart = CombinationChartComponent(
    chart_type=ChartType.BAR,
    orientation=ChartViewOrientation.VERTICAL
)

# Bar series for sales volume
combo_chart.add_data_series(
    source_field=sales_table.volume_field,
    name="Sales Volume",
    color="#2196f3"
)

# Line series for target (different visual style)
combo_chart.add_data_series(
    source_field=sales_table.target_field,
    name="Target",
    color="#ff5722"
)

Using tooltips and point labels:

# Chart with custom tooltips
detailed_chart = CombinationChartComponent(
    chart_type=ChartType.SPLINE,
    tooltip="${series.name}: ${point.y}",
    point_label="${point.y}"
)

detailed_chart.add_data_series(
    source_field=metrics_table.value_field,
    name="Performance Metric",
    display_field=metrics_table.formatted_value_field
)

Creating a horizontal bar chart:

# Horizontal bar chart (useful for rankings)
horizontal_bars = CombinationChartComponent(
    chart_type=ChartType.BAR,
    orientation=ChartViewOrientation.HORIZONTAL
)

horizontal_bars.add_data_series(
    source_field=products_table.sales_rank_field,
    name="Product Rankings",
    color="#00bcd4"
)

Box plot for statistical analysis:

# Box plot showing distribution
box_plot = CombinationChartComponent(
    chart_type=ChartType.BOX_PLOT,
    orientation=ChartViewOrientation.VERTICAL
)

box_plot.add_data_series(
    source_field=experiments_table.results_field,
    name="Experiment Results"
)

Setting series colors at chart level:

# Define color palette for entire chart
chart = CombinationChartComponent(
    chart_type=ChartType.BAR
)

# Add series
chart.add_data_series(source_field=data.series1, name="Series 1")
chart.add_data_series(source_field=data.series2, name="Series 2")
chart.add_data_series(source_field=data.series3, name="Series 3")

# Apply color palette
chart.add_series_color("#e3f2fd")
chart.add_series_color("#90caf9")
chart.add_series_color("#1976d2")

Area range chart for min-max visualization:

# Area range showing value boundaries
range_chart = CombinationChartComponent(
    chart_type=ChartType.AREA_RANGE,
    orientation=ChartViewOrientation.VERTICAL
)

range_chart.add_data_series(
    source_field=temperature_table.range_field,
    name="Temperature Range",
    color="#ff9800"
)

Multiple series with individual markers:

# Chart with different markers per series
multi_marker_chart = CombinationChartComponent(
    chart_type=ChartType.LINE
)

# Series 1 with circle markers
multi_marker_chart.add_data_series(
    source_field=data.metric1,
    name="Metric 1",
    color="#4caf50",
    marker=DataPointMarker(
        symbol=DataPointMarkerSymbol.CIRCLE,
        radius=4
    )
)

# Series 2 with square markers
multi_marker_chart.add_data_series(
    source_field=data.metric2,
    name="Metric 2",
    color="#2196f3",
    marker=DataPointMarker(
        symbol=DataPointMarkerSymbol.SQUARE,
        radius=4
    )
)

class DataPointMarkerSymbol(*values)

Bases: Enum

Enumeration of supported marker shapes for data points in charts.

Values:

CIRCLE:

A circular marker shape.

SQUARE:

A square marker shape.

TRIANGLE:

An upward-pointing triangular marker.

DIAMOND:

A diamond-shaped marker.

TRIANGLE_DOWN:

A downward-pointing triangular marker.

CIRCLE = 'CIRCLE'

SQUARE = 'SQUARE'

TRIANGLE = 'TRIANGLE'

DIAMOND = 'DIAMOND'

TRIANGLE_DOWN = 'TRIANGLE_DOWN'

class ChartViewOrientation(*values)

Bases: Enum

Defines the orientation of the chart layout.

VERTICAL

The chart is rendered with a vertical orientation.

HORIZONTAL

The chart is rendered with a horizontal orientation.

VERTICAL = 'VERTICAL'

HORIZONTAL = 'HORIZONTAL'

class ChartType(*values)

Bases: Enum

Specifies the type of chart to be rendered.

LINE

A standard line chart where data points are connected by straight lines.

BAR

A vertical bar chart where values are represented as rectangular bars.

PIE

A circular chart divided into sectors to illustrate proportional values.

SCATTER

A scatter plot where individual data points are placed on an x-y axis.

AREA

An area chart similar to a line chart, but the area under the line is filled.

SPLINE

A smoothed line chart using spline curves instead of straight segments.

AREA_SPLINE

A spline-based area chart where the area under a smooth curve is filled.

AREA_RANGE

An area chart representing a range (e.g., min and max values) between two boundaries.

BAR_RANGE

A bar chart that displays ranges instead of single numeric values.

BOX_PLOT

A statistical chart showing distribution through quartiles, median, and outliers.

LINE = 'LINE'

BAR = 'BAR'

PIE = 'PIE'

SCATTER = 'SCATTER'

AREA = 'AREA'

SPLINE = 'SPLINE'

AREA_SPLINE = 'AREA_SPLINE'

AREA_RANGE = 'AREA_RANGE'

BAR_RANGE = 'BAR_RANGE'

BOX_PLOT = 'BOX_PLOT'

class ChartViewStacking(*values)

Bases: Enum

Defines how multiple data series should be stacked in the chart.

NORMAL

Standard stacking mode. Series values are added on top of each other, producing a cumulative effect (e.g., stacked bar or stacked area chart).

PERCENT

Percentage stacking mode. Each series value is converted into a percentage of the total for that category, so stacked segments represent relative proportions rather than absolute values.

NORMAL = 'NORMAL'

PERCENT = 'PERCENT'

class DataPointMarker(symbol=None, radius=None, fill_color=None, line_color=None, line_width=None)

Bases: Buildable

Represents the visual marker used to display individual data points on a chart.

symbol

The marker shape for data points (e.g., circle, square, triangle). If None, the chart may use a default marker or render without markers.

Type:

Optional[DataPointMarkerSymbol]

radius

The radius (in pixels) of the marker. Applies to circular markers and is used as a size reference for other shapes. If None, the chart’s default marker size is used.

Type:

Optional[int]

fill_color

The fill colour of the marker, expressed as a hex code or colour name. If None, the marker may inherit the series colour.

Type:

Optional[str]

line_color

The colour of the marker’s border/outline. If None, no border may be drawn.

Type:

Optional[str]

line_width

The width (in pixels) of the marker outline. If None, the default width applies.

Type:

Optional[int]

symbol: DataPointMarkerSymbol | None = None

radius: int | None = None

fill_color: str | None = None

line_color: str | None = None

line_width: int | None = None

class ChartSeries(source_field, name=None, color=None, display_field=None, marker=None)

Bases: Buildable

Represents a single series in a chart, including its data source, styling preferences, and optional data point marker configuration.

source_field

The underlying data field used as the source values for this series.

Type:

str

name

The display name for the series, shown in the legend or tooltips.

Type:

Optional[str]

color

A custom colour for the series line or bars (hex code or colour name).

Type:

Optional[str]

display_field

A field used for formatting or displaying values (e.g., tooltip text).

Type:

Optional[str]

marker

Optional configuration defining the appearance of data point markers.

Type:

Optional[DataPointMarker]

__init__(source_field, name=None, color=None, display_field=None, marker=None)

Parameters:

• source_field (Field) – The field whose values are plotted by this series.

• name (str | None) – Optional display name shown in the legend and tooltips.

• color (str | None) – Optional colour override (hex code or colour name).

• display_field (str | None) – Optional alternate field ID used for label or tooltip text.

• marker (DataPointMarker | None) – Optional visual configuration for individual data-point markers.

set_name(name)

Sets the display name for this series.

Return type:

ChartSeries

set_color(color)

Sets the colour override for this series.

Return type:

ChartSeries

set_display_field(field)

Sets the alternate display field for tooltips or labels.

Return type:

ChartSeries

set_marker(marker)

Sets the marker configuration for individual data points.

Return type:

ChartSeries

class CombinationChartComponent(orientation=None, chart_type=None, stacking=None, point_label=None, tooltip=None)

Bases: Buildable

Represents a chart component capable of rendering multiple data series, potentially using different chart types within the same chart area. This component defines general chart configuration (such as orientation, stacking mode, and tooltip formatting) and holds all series that form the combination chart.

orientation

Orientation of the chart.

Type:

Optional[ChartViewOrientation]

type

Chart type associated with this component.

Type:

Optional[ChartType]

stacking

Stacking behaviour for all included series.

Type:

Optional[ChartViewStacking]

point_label

Label displayed for each data point.

Type:

Optional[str]

tooltip

Hover text or formatting for data point tooltips.

Type:

Optional[str]

data_series

A collection of chart series included in the combination chart.

Type:

List[ChartSeries]

series_colors

Optional color overrides applied to each series in rendering order.

Type:

List[str]

__init__(orientation=None, chart_type=None, stacking=None, point_label=None, tooltip=None)

Parameters:

• orientation (ChartViewOrientation | None) – Chart orientation (vertical or horizontal).

• chart_type (ChartType | None) – The chart type for this component (e.g. LINE, BAR).

• stacking (ChartViewStacking | None) – How multiple series are stacked (NORMAL or PERCENT).

• point_label (str | None) – Optional label template displayed on each data point.

• tooltip (str | None) – Optional tooltip template for hover interactions.

data_series: list[ChartSeries]

series_colors: list[str]

add_data_series(source_field, name=None, color=None, display_field=None, marker=None)

Adds a new data series to the chart.

Parameters:

• source_field (Field) – Name of the field supplying values for this series.

• name (str | None) – Display name for the series.

• color (str | None) – Optional color override for the series.

• display_field (str | None) – Optional alternate display field for tooltips or labels.

• marker (DataPointMarker | None) – Marker configuration for individual data points.

Notes

This method constructs a new ChartSeries object and appends it to self.data_series.

add_series_color(color)

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.