Extended Plots (templates)

Ready-to-use specialized visualization templates that extend core dartwork-mpl with opinionated, publication-ready plot functions.

Warning

Module Renamed: The xplot module has been renamed to templates in v0.2.0. The old xplot name is available as a deprecated alias for backward compatibility. Please update your imports to use the new name:

# Old (deprecated - will be removed in v1.0)
from dartwork_mpl.xplot import plot_diverging_bar

# New (recommended)
from dartwork_mpl.templates import plot_diverging_bar
# or
import dartwork_mpl as dm
dm.plot_diverging_bar(...)

Example

from dartwork_mpl.templates import plot_diverging_bar  # New import path

fig, ax = plot_diverging_bar(
    categories=['Category A', 'Category B', 'Category C'],
    negatives=[-30, -15, -25],
    positives=[40, 55, 35],
    neg_label='Decrease',
    pos_label='Increase',
)

API

Extended plot functions for dartwork-mpl.

This package extends dartwork-mpl’s core functionality with ready-to-use specialized visualization template functions.

dartwork_mpl.templates.plot_diverging_bar(labels: list[str] | None = None, neg_values: ndarray | None = None, pos_values: ndarray | None = None, add_total: bool = True, figsize: tuple[float, float] | None = None, dpi: int = 300, title: str | None = None, neg_label: str = 'Review & Refactoring overhead', pos_label: str = 'Code Generation savings', colors: dict[str, str] | None = None, hbar_height: float = 0.5, hbar_spacing_factor: float = 1.6, left_margin: float = 0.35, right_margin: float = 0.95, figure_bottom: float = 0.03, base_x: float = 0.02, title_y: float = 0.95, title_to_legend_gap: float = 0.05, legend_to_figure_gap: float = 0.06) → tuple[Figure, Axes]

Create a diverging bar chart with positive and negative values.

Generates a horizontal bar chart where negative values extend left and positive values extend right from a central axis. Uses a cascading layout with title, legend, and figure stacked vertically.

Parameters:

• labels (list[str] | None, optional) – Category labels shown on the left. Labels are displayed from top to bottom in reverse order. If None, default sample data is used. Default is None.

• neg_values (np.ndarray | None, optional) – Array of negative values (one per label). Values should be negative. If None, default sample data is used. Default is None.

• pos_values (np.ndarray | None, optional) – Array of positive values (one per label). Values should be positive. If None, default sample data is used. Default is None.

• add_total (bool, optional) – If True, appends a “Total” row with mean values. Default is True.

• figsize (tuple[float, float] | None, optional) – Figure size (width, height) in inches. If None, (12cm, 12cm) is used. Default is None.

• dpi (int, optional) – Figure resolution in dots per inch. Default is 300.

• title (str | None, optional) – Title text shown at the top. If None, a default title is used. Default is None.

• neg_label (str, optional) – Legend label for negative bars. Default is “Review & Refactoring overhead”.

• pos_label (str, optional) – Legend label for positive bars. Default is “Code Generation savings”.

• colors (dict[str, str] | None, optional) – Dictionary with ‘neg’ and ‘pos’ keys. If None, default colors (MidnightBlue for negative, CornflowerBlue for positive) are used. Default is None.

• hbar_height (float, optional) – Height of each horizontal bar. Default is 0.5.

• hbar_spacing_factor (float, optional) – Bar spacing as a multiple of hbar_height. Default is 1.6.

• left_margin (float, optional) – Left margin of the Axes in figure coordinates (0–1). Default is 0.35.

• right_margin (float, optional) – Right margin of the Axes in figure coordinates (0–1). Default is 0.95.

• figure_bottom (float, optional) – Bottom margin of the Axes in figure coordinates (0–1). Default is 0.03.

• base_x (float, optional) – Common x-coordinate for title, legend, and labels in figure coordinates (0–1). Default is 0.02.

• title_y (float, optional) – Starting y-coordinate of the title in figure coordinates (0–1). Default is 0.95.

• title_to_legend_gap (float, optional) – Gap between title and legend in figure coordinates (0–1). Default is 0.05.

• legend_to_figure_gap (float, optional) – Gap between legend and figure area in figure coordinates (0–1). Default is 0.06.

Returns:

• fig (matplotlib.figure.Figure) – The created Figure object.

• ax (matplotlib.axes.Axes) – The Axes containing the chart.

Examples

>>> import numpy as np
>>> import dartwork_mpl as dm
>>> dm.style.use('scientific')
>>>
>>> # Minimal setup — uses default sample data
>>> fig, ax = plot_diverging_bar()
>>> dm.save_and_show(fig)
>>>
>>> # Custom data
>>> labels = [
...     "Frontend Development",
...     "Backend Architecture",
...     "Data Engineering",
...     "API Integration",
...     "Quality Assurance",
...     "DevOps & Infrastructure",
...     "Security Compliance",
...     "Technical Documentation",
... ]
>>> neg_values = np.array([-5, -8, -10, -10, -8, -9, -10, -7])
>>> pos_values = np.array([20, 35, 32, 40, 20, 28, 38, 30])
>>> fig, ax = plot_diverging_bar(
...     labels,
...     neg_values,
...     pos_values
... )
>>> dm.save_and_show(fig)
>>>
>>> # Customize title and colors without Total row
>>> fig, ax = plot_diverging_bar(
...     labels,
...     neg_values,
...     pos_values,
...     add_total=False,
...     title="Custom Title",
...     colors={'neg': 'oc.red5', 'pos': 'oc.green5'}
... )
>>> dm.save_and_show(fig)

Notes

• This function uses a cascading layout where the title, legend, and chart are spaced automatically from top to bottom.

• Labels are positioned using blended_transform_factory which blends figure x-coordinates with data y-coordinates.

• The “Total” row (if enabled) is automatically bolded via dm.fw(1).

• Value labels are placed inside the bars (left for negative, right for positive).

See also

dartwork_mpl.style.use

Apply a dartwork-mpl style preset

dartwork_mpl.simple_layout

Optimize figure layout

matplotlib.transforms.blended_transform_factory

Create blended transforms

Diverging bar chart visualization module.

Provides functions for creating horizontal bar charts that display positive and negative values extending in opposite directions from a central axis.

dartwork_mpl.templates.diverging_bar.get_source_code() → str

Return the source code of this module as a string.

Intended for providing source code as input to coding agents (AI) for further development or modification.

Returns:

The complete source code of this module.

Return type:

str

Examples

>>> source = get_source_code()
>>> print(source)

dartwork_mpl.templates.diverging_bar.plot_diverging_bar(labels: list[str] | None = None, neg_values: ndarray | None = None, pos_values: ndarray | None = None, add_total: bool = True, figsize: tuple[float, float] | None = None, dpi: int = 300, title: str | None = None, neg_label: str = 'Review & Refactoring overhead', pos_label: str = 'Code Generation savings', colors: dict[str, str] | None = None, hbar_height: float = 0.5, hbar_spacing_factor: float = 1.6, left_margin: float = 0.35, right_margin: float = 0.95, figure_bottom: float = 0.03, base_x: float = 0.02, title_y: float = 0.95, title_to_legend_gap: float = 0.05, legend_to_figure_gap: float = 0.06) → tuple[Figure, Axes]

Create a diverging bar chart with positive and negative values.

Generates a horizontal bar chart where negative values extend left and positive values extend right from a central axis. Uses a cascading layout with title, legend, and figure stacked vertically.

Parameters:

• labels (list[str] | None, optional) – Category labels shown on the left. Labels are displayed from top to bottom in reverse order. If None, default sample data is used. Default is None.

• neg_values (np.ndarray | None, optional) – Array of negative values (one per label). Values should be negative. If None, default sample data is used. Default is None.

• pos_values (np.ndarray | None, optional) – Array of positive values (one per label). Values should be positive. If None, default sample data is used. Default is None.

• add_total (bool, optional) – If True, appends a “Total” row with mean values. Default is True.

• figsize (tuple[float, float] | None, optional) – Figure size (width, height) in inches. If None, (12cm, 12cm) is used. Default is None.

• dpi (int, optional) – Figure resolution in dots per inch. Default is 300.

• title (str | None, optional) – Title text shown at the top. If None, a default title is used. Default is None.

• neg_label (str, optional) – Legend label for negative bars. Default is “Review & Refactoring overhead”.

• pos_label (str, optional) – Legend label for positive bars. Default is “Code Generation savings”.

• colors (dict[str, str] | None, optional) – Dictionary with ‘neg’ and ‘pos’ keys. If None, default colors (MidnightBlue for negative, CornflowerBlue for positive) are used. Default is None.

• hbar_height (float, optional) – Height of each horizontal bar. Default is 0.5.

• hbar_spacing_factor (float, optional) – Bar spacing as a multiple of hbar_height. Default is 1.6.

• left_margin (float, optional) – Left margin of the Axes in figure coordinates (0–1). Default is 0.35.

• right_margin (float, optional) – Right margin of the Axes in figure coordinates (0–1). Default is 0.95.

• figure_bottom (float, optional) – Bottom margin of the Axes in figure coordinates (0–1). Default is 0.03.

• base_x (float, optional) – Common x-coordinate for title, legend, and labels in figure coordinates (0–1). Default is 0.02.

• title_y (float, optional) – Starting y-coordinate of the title in figure coordinates (0–1). Default is 0.95.

• title_to_legend_gap (float, optional) – Gap between title and legend in figure coordinates (0–1). Default is 0.05.

• legend_to_figure_gap (float, optional) – Gap between legend and figure area in figure coordinates (0–1). Default is 0.06.

Returns:

• fig (matplotlib.figure.Figure) – The created Figure object.

• ax (matplotlib.axes.Axes) – The Axes containing the chart.

Examples

>>> import numpy as np
>>> import dartwork_mpl as dm
>>> dm.style.use('scientific')
>>>
>>> # Minimal setup — uses default sample data
>>> fig, ax = plot_diverging_bar()
>>> dm.save_and_show(fig)
>>>
>>> # Custom data
>>> labels = [
...     "Frontend Development",
...     "Backend Architecture",
...     "Data Engineering",
...     "API Integration",
...     "Quality Assurance",
...     "DevOps & Infrastructure",
...     "Security Compliance",
...     "Technical Documentation",
... ]
>>> neg_values = np.array([-5, -8, -10, -10, -8, -9, -10, -7])
>>> pos_values = np.array([20, 35, 32, 40, 20, 28, 38, 30])
>>> fig, ax = plot_diverging_bar(
...     labels,
...     neg_values,
...     pos_values
... )
>>> dm.save_and_show(fig)
>>>
>>> # Customize title and colors without Total row
>>> fig, ax = plot_diverging_bar(
...     labels,
...     neg_values,
...     pos_values,
...     add_total=False,
...     title="Custom Title",
...     colors={'neg': 'oc.red5', 'pos': 'oc.green5'}
... )
>>> dm.save_and_show(fig)

Notes

• This function uses a cascading layout where the title, legend, and chart are spaced automatically from top to bottom.

• Labels are positioned using blended_transform_factory which blends figure x-coordinates with data y-coordinates.

• The “Total” row (if enabled) is automatically bolded via dm.fw(1).

• Value labels are placed inside the bars (left for negative, right for positive).

See also

dartwork_mpl.style.use

Apply a dartwork-mpl style preset

dartwork_mpl.simple_layout

Optimize figure layout

matplotlib.transforms.blended_transform_factory

Create blended transforms

Legacy Compatibility

For backward compatibility, the old xplot module name is still available:

Extended plot functions for dartwork-mpl.

This package extends dartwork-mpl’s core functionality with ready-to-use specialized visualization template functions.

dartwork_mpl.xplot.plot_diverging_bar(labels: list[str] | None = None, neg_values: ndarray | None = None, pos_values: ndarray | None = None, add_total: bool = True, figsize: tuple[float, float] | None = None, dpi: int = 300, title: str | None = None, neg_label: str = 'Review & Refactoring overhead', pos_label: str = 'Code Generation savings', colors: dict[str, str] | None = None, hbar_height: float = 0.5, hbar_spacing_factor: float = 1.6, left_margin: float = 0.35, right_margin: float = 0.95, figure_bottom: float = 0.03, base_x: float = 0.02, title_y: float = 0.95, title_to_legend_gap: float = 0.05, legend_to_figure_gap: float = 0.06) → tuple[Figure, Axes]

Create a diverging bar chart with positive and negative values.

Generates a horizontal bar chart where negative values extend left and positive values extend right from a central axis. Uses a cascading layout with title, legend, and figure stacked vertically.

Parameters:

• labels (list[str] | None, optional) – Category labels shown on the left. Labels are displayed from top to bottom in reverse order. If None, default sample data is used. Default is None.

• neg_values (np.ndarray | None, optional) – Array of negative values (one per label). Values should be negative. If None, default sample data is used. Default is None.

• pos_values (np.ndarray | None, optional) – Array of positive values (one per label). Values should be positive. If None, default sample data is used. Default is None.

• add_total (bool, optional) – If True, appends a “Total” row with mean values. Default is True.

• figsize (tuple[float, float] | None, optional) – Figure size (width, height) in inches. If None, (12cm, 12cm) is used. Default is None.

• dpi (int, optional) – Figure resolution in dots per inch. Default is 300.

• title (str | None, optional) – Title text shown at the top. If None, a default title is used. Default is None.

• neg_label (str, optional) – Legend label for negative bars. Default is “Review & Refactoring overhead”.

• pos_label (str, optional) – Legend label for positive bars. Default is “Code Generation savings”.

• colors (dict[str, str] | None, optional) – Dictionary with ‘neg’ and ‘pos’ keys. If None, default colors (MidnightBlue for negative, CornflowerBlue for positive) are used. Default is None.

• hbar_height (float, optional) – Height of each horizontal bar. Default is 0.5.

• hbar_spacing_factor (float, optional) – Bar spacing as a multiple of hbar_height. Default is 1.6.

• left_margin (float, optional) – Left margin of the Axes in figure coordinates (0–1). Default is 0.35.

• right_margin (float, optional) – Right margin of the Axes in figure coordinates (0–1). Default is 0.95.

• figure_bottom (float, optional) – Bottom margin of the Axes in figure coordinates (0–1). Default is 0.03.

• base_x (float, optional) – Common x-coordinate for title, legend, and labels in figure coordinates (0–1). Default is 0.02.

• title_y (float, optional) – Starting y-coordinate of the title in figure coordinates (0–1). Default is 0.95.

• title_to_legend_gap (float, optional) – Gap between title and legend in figure coordinates (0–1). Default is 0.05.

• legend_to_figure_gap (float, optional) – Gap between legend and figure area in figure coordinates (0–1). Default is 0.06.

Returns:

• fig (matplotlib.figure.Figure) – The created Figure object.

• ax (matplotlib.axes.Axes) – The Axes containing the chart.

Examples

>>> import numpy as np
>>> import dartwork_mpl as dm
>>> dm.style.use('scientific')
>>>
>>> # Minimal setup — uses default sample data
>>> fig, ax = plot_diverging_bar()
>>> dm.save_and_show(fig)
>>>
>>> # Custom data
>>> labels = [
...     "Frontend Development",
...     "Backend Architecture",
...     "Data Engineering",
...     "API Integration",
...     "Quality Assurance",
...     "DevOps & Infrastructure",
...     "Security Compliance",
...     "Technical Documentation",
... ]
>>> neg_values = np.array([-5, -8, -10, -10, -8, -9, -10, -7])
>>> pos_values = np.array([20, 35, 32, 40, 20, 28, 38, 30])
>>> fig, ax = plot_diverging_bar(
...     labels,
...     neg_values,
...     pos_values
... )
>>> dm.save_and_show(fig)
>>>
>>> # Customize title and colors without Total row
>>> fig, ax = plot_diverging_bar(
...     labels,
...     neg_values,
...     pos_values,
...     add_total=False,
...     title="Custom Title",
...     colors={'neg': 'oc.red5', 'pos': 'oc.green5'}
... )
>>> dm.save_and_show(fig)

Notes

• This function uses a cascading layout where the title, legend, and chart are spaced automatically from top to bottom.

• Labels are positioned using blended_transform_factory which blends figure x-coordinates with data y-coordinates.

• The “Total” row (if enabled) is automatically bolded via dm.fw(1).

• Value labels are placed inside the bars (left for negative, right for positive).

See also

dartwork_mpl.style.use

Apply a dartwork-mpl style preset

dartwork_mpl.simple_layout

Optimize figure layout

matplotlib.transforms.blended_transform_factory

Create blended transforms