chartbook.plotting._api

chartbook.plotting._api#

Core chart API functions for chartbook.plotting.

Module Contents#

Functions#

area

Create an area chart.

bar

Create a bar chart.

line

Create a line chart.

pie

Create a pie chart.

scatter

Create a scatter chart.

API#

chartbook.plotting._api.area(df: pandas.DataFrame, *, x: str, y: str | Sequence[str], stacked: bool = True, title: str | None = None, caption: str | None = None, note: str | None = None, source: str | None = None, color: str | Sequence[str] | None = None, labels: dict[str, str] | None = None, x_title: str | None = None, y_title: str | None = None, x_range: tuple[float, float] | None = None, y_range: tuple[float, float] | None = None, x_tickformat: str | None = None, y_tickformat: str | None = None, nber_recessions: bool | None = None, hlines: Sequence[dict[str, Any]] | None = None, shaded_regions: Sequence[dict[str, Any]] | None = None, **kwargs: Any) → chartbook.plotting._types.ChartResult[source]#

Create an area chart.

Returns a ChartResult with the figure. Call .show() to display inline, or .save(chart_id) to export to multiple formats.

Parameters:

  • df (DataFrame) – Data to plot.

  • x (str) – Column name for x-axis.

  • y (str or Sequence[str]) – Column name(s) for y-axis values.

  • stacked (bool) – If True, stack areas. Default: True

  • title (str, optional) – Chart title.

  • caption (str, optional) – Caption text displayed above the chart.

  • note (str, optional) – Note text displayed below the chart.

  • source (str, optional) – Source attribution text.

  • color (str or Sequence[str], optional) – Color(s) for the series.

  • labels (dict, optional) – Mapping of column names to display labels.

  • x_title (str, optional) – X-axis title.

  • y_title (str, optional) – Y-axis title.

  • x_range (tuple, optional) – X-axis range as (min, max).

  • y_range (tuple, optional) – Y-axis range as (min, max).

  • x_tickformat (str, optional) – X-axis tick format string.

  • y_tickformat (str, optional) – Y-axis tick format string.

  • nber_recessions (bool, optional) – Show NBER recession shading. None uses global config.

  • hlines (Sequence[dict], optional) – Horizontal reference lines.

  • shaded_regions (Sequence[dict], optional) – Shaded vertical regions.

Returns:

Object with .show(), .save(chart_id), .figure, .mpl_figure, .mpl_axes.

Return type:

ChartResult

chartbook.plotting._api.bar(df: pandas.DataFrame, *, x: str, y: str | Sequence[str], stacked: bool = False, title: str | None = None, caption: str | None = None, note: str | None = None, source: str | None = None, color: str | Sequence[str] | None = None, labels: dict[str, str] | None = None, x_title: str | None = None, y_title: str | None = None, x_range: tuple[float, float] | None = None, y_range: tuple[float, float] | None = None, y_tickformat: str | None = None, nber_recessions: bool | None = None, hlines: Sequence[dict[str, Any]] | None = None, shaded_regions: Sequence[dict[str, Any]] | None = None, **kwargs: Any) → chartbook.plotting._types.ChartResult[source]#

Create a bar chart.

Returns a ChartResult with the figure. Call .show() to display inline, or .save(chart_id) to export to multiple formats.

Parameters:

  • df (DataFrame) – Data to plot.

  • x (str) – Column name for x-axis (categories).

  • y (str or Sequence[str]) – Column name(s) for y-axis values.

  • stacked (bool) – If True, stack bars instead of grouping. Default: False

  • title (str, optional) – Chart title.

  • caption (str, optional) – Caption text displayed above the chart.

  • note (str, optional) – Note text displayed below the chart.

  • source (str, optional) – Source attribution text.

  • color (str or Sequence[str], optional) – Color(s) for the series.

  • labels (dict, optional) – Mapping of column names to display labels.

  • x_title (str, optional) – X-axis title.

  • y_title (str, optional) – Y-axis title.

  • x_range (tuple, optional) – X-axis range as (min, max).

  • y_range (tuple, optional) – Y-axis range as (min, max).

  • y_tickformat (str, optional) – Y-axis tick format string.

  • nber_recessions (bool, optional) – Show NBER recession shading. None uses global config.

  • hlines (Sequence[dict], optional) – Horizontal reference lines.

  • shaded_regions (Sequence[dict], optional) – Shaded vertical regions.

Returns:

Object with .show(), .save(chart_id), .figure, .mpl_figure, .mpl_axes.

Return type:

ChartResult

chartbook.plotting._api.line(df: pandas.DataFrame, *, x: str, y: str | Sequence[str], title: str | None = None, caption: str | None = None, note: str | None = None, source: str | None = None, color: str | Sequence[str] | None = None, labels: dict[str, str] | None = None, x_title: str | None = None, y_title: str | None = None, x_range: tuple[float, float] | None = None, y_range: tuple[float, float] | None = None, x_tickformat: str | None = None, y_tickformat: str | None = None, nber_recessions: bool | None = None, hlines: Sequence[dict[str, Any]] | None = None, vlines: Sequence[dict[str, Any]] | None = None, shaded_regions: Sequence[dict[str, Any]] | None = None, bands: Sequence[dict[str, Any]] | None = None, regression_line: bool = False, **kwargs: Any) → chartbook.plotting._types.ChartResult[source]#

Create a line chart.

Returns a ChartResult with the figure. Call .show() to display inline, or .save(chart_id) to export to multiple formats.

Parameters:

  • df (DataFrame) – Data to plot.

  • x (str) – Column name for x-axis.

  • y (str or Sequence[str]) – Column name(s) for y-axis. Multiple columns create multiple series.

  • title (str, optional) – Chart title.

  • caption (str, optional) – Caption text displayed above the chart.

  • note (str, optional) – Note text displayed below the chart.

  • source (str, optional) – Source attribution text.

  • color (str or Sequence[str], optional) – Color(s) for the series.

  • labels (dict, optional) – Mapping of column names to display labels.

  • x_title (str, optional) – X-axis title.

  • y_title (str, optional) – Y-axis title.

  • x_range (tuple, optional) – X-axis range as (min, max).

  • y_range (tuple, optional) – Y-axis range as (min, max).

  • x_tickformat (str, optional) – X-axis tick format string.

  • y_tickformat (str, optional) – Y-axis tick format string.

  • nber_recessions (bool, optional) – Show NBER recession shading. None uses global config.

  • hlines (Sequence[dict], optional) – Horizontal reference lines. Each dict: {“y”: value, “color”: “gray”, “dash”: “solid”, “label”: “…”}.

  • vlines (Sequence[dict], optional) – Vertical reference lines. Each dict: {“x”: value, “color”: “gray”, “dash”: “solid”, “label”: “…”}.

  • shaded_regions (Sequence[dict], optional) – Shaded vertical regions. Each dict: {“x0”: start, “x1”: end, “color”: “gray”, “alpha”: 0.3, “label”: “…”}.

  • bands (Sequence[dict], optional) – Fill between y-columns. Each dict: {“y_upper”: col, “y_lower”: col, “color”: “blue”, “alpha”: 0.3}.

  • regression_line (bool) – If True, add a linear regression trend line. Default: False

Returns:

Object with .show(), .save(chart_id), .figure, .mpl_figure, .mpl_axes.

Return type:

ChartResult

Examples

import chartbook
import pandas as pd
df = pd.DataFrame({"date": pd.date_range("2020", periods=12, freq="M"), "gdp": range(12)})

# Display inline
chartbook.plotting.line(df, x="date", y="gdp").show()

# Save to files
result = chartbook.plotting.line(df, x="date", y="gdp", title="GDP Growth")
result.save(chart_id="gdp")
print(result.html_path)
# Output: ./_output/gdp.html

# Multiple series with NBER recessions
chartbook.plotting.line(
    df, x="date", y=["gdp", "cpi"],
    title="Economic Indicators", nber_recessions=True
).save("indicators")
chartbook.plotting._api.pie(df: pandas.DataFrame, *, names: str, values: str, title: str | None = None, caption: str | None = None, note: str | None = None, source: str | None = None, **kwargs: Any) → chartbook.plotting._types.ChartResult[source]#

Create a pie chart.

Returns a ChartResult with the figure. Call .show() to display inline, or .save(chart_id) to export to multiple formats.

Parameters:

  • df (DataFrame) – Data to plot.

  • names (str) – Column name for category labels.

  • values (str) – Column name for slice values.

  • title (str, optional) – Chart title.

  • caption (str, optional) – Caption text displayed above the chart.

  • note (str, optional) – Note text displayed below the chart.

  • source (str, optional) – Source attribution text.

Returns:

Object with .show(), .save(chart_id), .figure, .mpl_figure, .mpl_axes.

Return type:

ChartResult

chartbook.plotting._api.scatter(df: pandas.DataFrame, *, x: str, y: str, size: str | None = None, color_by: str | None = None, title: str | None = None, caption: str | None = None, note: str | None = None, source: str | None = None, color: str | None = None, x_title: str | None = None, y_title: str | None = None, x_range: tuple[float, float] | None = None, y_range: tuple[float, float] | None = None, x_tickformat: str | None = None, y_tickformat: str | None = None, hlines: Sequence[dict[str, Any]] | None = None, vlines: Sequence[dict[str, Any]] | None = None, regression_line: bool = False, **kwargs: Any) → chartbook.plotting._types.ChartResult[source]#

Create a scatter chart.

Returns a ChartResult with the figure. Call .show() to display inline, or .save(chart_id) to export to multiple formats.

Parameters:

  • df (DataFrame) – Data to plot.

  • x (str) – Column name for x-axis.

  • y (str) – Column name for y-axis.

  • size (str, optional) – Column name for marker size.

  • color_by (str, optional) – Column name for categorical coloring.

  • title (str, optional) – Chart title.

  • caption (str, optional) – Caption text displayed above the chart.

  • note (str, optional) – Note text displayed below the chart.

  • source (str, optional) – Source attribution text.

  • color (str, optional) – Color for the markers.

  • x_title (str, optional) – X-axis title.

  • y_title (str, optional) – Y-axis title.

  • x_range (tuple, optional) – X-axis range as (min, max).

  • y_range (tuple, optional) – Y-axis range as (min, max).

  • x_tickformat (str, optional) – X-axis tick format string.

  • y_tickformat (str, optional) – Y-axis tick format string.

  • hlines (Sequence[dict], optional) – Horizontal reference lines.

  • vlines (Sequence[dict], optional) – Vertical reference lines.

  • regression_line (bool) – If True, add a linear regression trend line. Default: False

Returns:

Object with .show(), .save(chart_id), .figure, .mpl_figure, .mpl_axes.

Return type:

ChartResult

Contents