Utils Module

datachart.utils

The module containing the utils.

The utils module provides a set of public utilities for the package.

This module exports only the public API intended for end users. Internal implementation details are located in the _internal submodule and should not be imported directly by external code.

MODULE	DESCRIPTION
`stats`	The module containing the statistics functions (count, mean, median, etc.).

FUNCTION	DESCRIPTION
`save_figure`	Saves the figure into a file using the provided format parameters.
`FigureGridLayout`	Combines multiple figure objects into a single grid layout.
`figure_grid_layout`	(Deprecated) Legacy function for combining figures. Use FigureGridLayout instead.
`OverlayChart`	Overlays multiple charts on a single plot with optional dual y-axes.

Functions

datachart.utils.save_figure

save_figure(
    figure: plt.Figure,
    path: str,
    dpi: int = 300,
    format: FIG_FORMAT = None,
    transparent: bool = False,
) -> None

Save the figure to a file.

Examples:

>>> # 1. create the figure
>>> from datachart.charts import LineChart
>>> figure = LineChart({...})

>>> # 2. save the figure
>>> from datachart.utils.figure import save_figure
>>> from datachart.constants import FIG_FORMAT
>>> path = "/path/to/save/chart.png"
>>> save_figure(figure, path, dpi=300, format=FIG_FORMAT.PNG, transparent=True)

PARAMETER	DESCRIPTION
`figure`	The figure to save. TYPE: `plt.Figure`
`path`	The path where the figure is saved. TYPE: `str`
`dpi`	The DPI of the figure. TYPE: `int` DEFAULT: `300`
`format`	The format of the figure. If `None`, the format will be determined from the file extension. TYPE: `FIG_FORMAT` DEFAULT: `None`
`transparent`	Whether to make the background transparent. TYPE: `bool` DEFAULT: `False`

datachart.utils.FigureGridLayout

FigureGridLayout(
    charts: List[Dict[str, Any]],
    *,
    title: Optional[str] = None,
    max_cols: int = 4,
    figsize: Optional[Tuple[float, float]] = None,
    sharex: bool = False,
    sharey: bool = False
) -> plt.Figure

Combine multiple existing figure objects into a single grid layout.

This function extracts chart metadata from each figure and recreates them in a grid layout. Supports mixing different chart types in the same grid. Each chart can have custom layout specifications or use automatic uniform grid.

Examples:

>>> from datachart.charts import LineChart, BarChart, ScatterChart
>>> from datachart.utils import FigureGridLayout
>>>
>>> # Create individual charts
>>> fig1 = LineChart(data=[{"x": i, "y": i**2} for i in range(10)], title="Line Chart")
>>> fig2 = BarChart(data=[{"label": "A", "y": 10}, {"label": "B", "y": 20}], title="Bar Chart")
>>> fig3 = ScatterChart(data=[{"x": i, "y": i*2} for i in range(10)], title="Scatter Chart")
>>>
>>> # Example 1: Automatic uniform grid layout
>>> combined = FigureGridLayout(
...     charts=[
...         {"figure": fig1},
...         {"figure": fig2},
...         {"figure": fig3},
...     ],
...     title="Mixed Chart Grid",
...     max_cols=2,
...     figsize=(12, 8)
... )
>>>
>>> # Example 2: Custom layout with fig1 spanning full width on top
>>> combined = FigureGridLayout(
...     charts=[
...         {"figure": fig1, "layout_spec": {"row": 0, "col": 0, "rowspan": 1, "colspan": 2}},
...         {"figure": fig2, "layout_spec": {"row": 1, "col": 0, "rowspan": 1, "colspan": 1}},
...         {"figure": fig3, "layout_spec": {"row": 1, "col": 1, "rowspan": 1, "colspan": 1}},
...     ],
...     title="Custom Layout",
...     figsize=(12, 8)
... )
>>>
>>> # Example 3: Mixed auto and custom layout
>>> combined = FigureGridLayout(
...     charts=[
...         {"figure": fig1, "layout_spec": {"row": 0, "col": 0, "rowspan": 2, "colspan": 1}},
...         {"figure": fig2},  # Auto-placed
...         {"figure": fig3},  # Auto-placed
...     ],
...     title="Mixed Layout"
... )

PARAMETER	DESCRIPTION
`charts`	List of chart configuration dictionaries. Each dict must contain: - "figure": A matplotlib Figure from datachart chart functions - "layout_spec" (optional): Dict with keys 'row', 'col', 'rowspan', 'colspan' for custom grid positioning. If omitted, automatic uniform grid layout is used. TYPE: `List[Dict[str, Any]]`
`title`	Optional title for the combined figure. TYPE: `Optional[str]` DEFAULT: `None`
`max_cols`	Maximum number of columns for automatic grid layout (when layout_spec not provided). TYPE: `int` DEFAULT: `4`
`figsize`	Size of the combined figure (width, height) in inches. If None, will be calculated based on input figures. TYPE: `Optional[Tuple[float, float]]` DEFAULT: `None`
`sharex`	Whether to share the x-axis across all subplots. TYPE: `bool` DEFAULT: `False`
`sharey`	Whether to share the y-axis across all subplots. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`plt.Figure`	A new matplotlib Figure containing all charts in a grid layout.

RAISES	DESCRIPTION
`ValueError`	If charts list is empty, if a chart is missing 'figure' key, if a figure is missing metadata, or if layout_spec is invalid.

datachart.utils.OverlayChart

OverlayChart(
    charts: List[Dict[str, Any]],
    *,
    title: Optional[str] = None,
    xlabel: Optional[str] = None,
    ylabel_left: Optional[str] = None,
    ylabel_right: Optional[str] = None,
    figsize: Optional[
        Union[FIG_SIZE, Tuple[float, float]]
    ] = None,
    show_legend: Optional[bool] = False,
    show_grid: Optional[str] = None,
    auto_secondary_axis: Optional[float] = None,
    xmin: Optional[float] = None,
    xmax: Optional[float] = None,
    ymin: Optional[float] = None,
    ymax: Optional[float] = None
) -> plt.Figure

Overlay multiple charts on a single plot with optional dual y-axes.

This function combines different chart types (LineChart, BarChart, ScatterChart, Histogram) on a single plot. Charts are drawn in the order provided. Multiple y-axes (left and right) are supported for handling different scales.

Examples:

>>> from datachart.charts import LineChart, BarChart
>>> from datachart.utils import OverlayChart
>>>
>>> # Create individual charts
>>> bar_fig = BarChart(
...     data=[{"label": "A", "y": 100}, {"label": "B", "y": 200}],
... )
>>> line_fig = LineChart(
...     data=[{"x": 0, "y": 5}, {"x": 1, "y": 15}],
... )
>>>
>>> # Combine with dual axes
>>> combined_fig = OverlayChart(
...     charts=[
...         {"figure": bar_fig, "y_axis": "left"},
...         {"figure": line_fig, "y_axis": "right"},
...     ],
...     title="Sales Analysis",
...     xlabel="Category",
...     ylabel_left="Count",
...     ylabel_right="Average",
...     show_legend=True,
... )
>>>
>>> # Automatic axis assignment
>>> combined_fig = OverlayChart(
...     charts=[
...         {"figure": bar_fig},
...         {"figure": line_fig},
...     ],
...     title="Automatic Axis Assignment",
...     auto_secondary_axis=3.0,  # threshold
... )

PARAMETER	DESCRIPTION
`charts`	List of chart configuration dictionaries. Each dict must contain: - "figure": A matplotlib Figure from datachart chart functions - "y_axis" (optional): "left", "right", or "auto" (default: "auto") - "z_order" (optional): Integer for layering control (higher values on top) TYPE: `List[Dict[str, Any]]`
`title`	Title for the combined chart. TYPE: `Optional[str]` DEFAULT: `None`
`xlabel`	Label for x-axis. TYPE: `Optional[str]` DEFAULT: `None`
`ylabel_left`	Label for left y-axis. TYPE: `Optional[str]` DEFAULT: `None`
`ylabel_right`	Label for right y-axis (if using dual axes). TYPE: `Optional[str]` DEFAULT: `None`
`figsize`	Size of the figure (width, height) in inches. TYPE: `Optional[Union[FIG_SIZE, Tuple[float, float]]]` DEFAULT: `None`
`show_legend`	Whether to show the legend. TYPE: `Optional[bool]` DEFAULT: `False`
`show_grid`	Which grid lines to show ("x", "y", "both", or None). TYPE: `Optional[str]` DEFAULT: `None`
`auto_secondary_axis`	Threshold ratio for automatic secondary axis creation. If the ratio of data ranges exceeds this threshold, a secondary axis is created. Default is taken from config (overlay_auto_threshold, default 3.0). TYPE: `Optional[float]` DEFAULT: `None`
`xmin`	Minimum value for x-axis limits. TYPE: `Optional[float]` DEFAULT: `None`
`xmax`	Maximum value for x-axis limits. TYPE: `Optional[float]` DEFAULT: `None`
`ymin`	Minimum value for y-axis limits (applies to left y-axis). TYPE: `Optional[float]` DEFAULT: `None`
`ymax`	Maximum value for y-axis limits (applies to left y-axis). TYPE: `Optional[float]` DEFAULT: `None`

RETURNS	DESCRIPTION
`plt.Figure`	A matplotlib Figure containing the overlaid charts.

RAISES	DESCRIPTION
`ValueError`	If charts list is empty or if figures are missing metadata.

Deprecated

datachart.utils.figure_grid_layout

figure_grid_layout(
    figures: List[plt.Figure],
    *,
    title: Optional[str] = None,
    layout_specs: Optional[List[Dict[str, int]]] = None,
    max_cols: Optional[int] = 4,
    figsize: Optional[Tuple[float, float]] = None,
    sharex: Optional[bool] = False,
    sharey: Optional[bool] = False
) -> plt.Figure

Combine multiple existing figure objects into a single grid layout.

.. deprecated:: This function is deprecated. Use :func:FigureGridLayout instead, which provides a cleaner API where figures and layout specs are combined.

This function extracts chart metadata from each figure and recreates them in a grid layout. Supports mixing different chart types in the same grid.

Examples:

>>> from datachart.charts import LineChart, BarChart, ScatterChart
>>> from datachart.utils import figure_grid_layout
>>>
>>> # Create individual charts
>>> fig1 = LineChart(data=[{"x": i, "y": i**2} for i in range(10)], title="Line Chart")
>>> fig2 = BarChart(data=[{"label": "A", "y": 10}, {"label": "B", "y": 20}], title="Bar Chart")
>>> fig3 = ScatterChart(data=[{"x": i, "y": i*2} for i in range(10)], title="Scatter Chart")
>>>
>>> # Example 1: Uniform grid layout (default behavior)
>>> combined = figure_grid_layout(
...     [fig1, fig2, fig3],
...     title="Mixed Chart Grid",
...     max_cols=2,
...     figsize=(12, 8)
... )
>>>
>>> # Example 2: Custom layout with figure 1 spanning full width on top
>>> layout_specs = [
...     {"row": 0, "col": 0, "rowspan": 1, "colspan": 2},  # fig1 spans 2 columns
...     {"row": 1, "col": 0, "rowspan": 1, "colspan": 1},  # fig2 left column
...     {"row": 1, "col": 1, "rowspan": 1, "colspan": 1},  # fig3 right column
... ]
>>> combined = figure_grid_layout(
...     [fig1, fig2, fig3],
...     layout_specs=layout_specs,
...     title="Custom Layout",
...     figsize=(12, 8)
... )

PARAMETER	DESCRIPTION
`figures`	List of matplotlib Figure objects to combine. Each figure must have `_chart_metadata` attribute (automatically added by datachart chart functions). TYPE: `List[plt.Figure]`
`title`	Optional title for the combined figure. TYPE: `Optional[str]` DEFAULT: `None`
`layout_specs`	Optional list of layout specifications for custom grid layouts. Each specification is a dict with keys: 'row', 'col', 'rowspan', 'colspan'. If provided, overrides max_cols. If None, creates uniform grid layout. TYPE: `Optional[List[Dict[str, int]]]` DEFAULT: `None`
`max_cols`	Maximum number of columns in the grid layout. Ignored if layout_specs is provided. TYPE: `Optional[int]` DEFAULT: `4`
`figsize`	Size of the combined figure (width, height) in inches. If None, will be calculated based on input figures. TYPE: `Optional[Tuple[float, float]]` DEFAULT: `None`
`sharex`	Whether to share the x-axis across all subplots. TYPE: `Optional[bool]` DEFAULT: `False`
`sharey`	Whether to share the y-axis across all subplots. TYPE: `Optional[bool]` DEFAULT: `False`

RETURNS	DESCRIPTION
`plt.Figure`	A new matplotlib Figure containing all charts in a grid layout.

RAISES	DESCRIPTION
`ValueError`	If figures list is empty, if a figure is missing metadata, or if layout_specs length doesn't match figures length.