Skip to content

mplchart.chart

charting main module

Chart

Chart(
    prices=None,
    *,
    title=None,
    max_bars=None,
    start=None,
    end=None,
    figure=None,
    figsize=None,
    normalize=False,
    raw_dates=False,
    style=None,
    yaxis_right=None,
    color_scheme=(),
)

Main charting class for creating financial charts with technical indicators.

Composes a data view (chart.view) and a presentation canvas (chart.canvas). Prices are required at initialization; the data view is created lazily on first access (see get_view) and cached. Calls to plot() add indicators to existing or new panes.

Arguments:

  • prices (DataFrame): OHLCV prices DataFrame (pandas or polars), used to initialize the data view. Required.
  • title (str): Chart title displayed above the main pane.
  • max_bars (int): Maximum number of bars to display. When set, only the most recent max_bars bars are shown.
  • start (datetime or str): Start of the display range.
  • end (datetime or str): End of the display range.
  • figure (Figure): Existing matplotlib Figure to draw on. The figure is cleared before use.
  • figsize (tuple): Figure size as (width, height) in inches. Defaults to (12, 9).
  • normalize (bool): If True, normalize the prices DataFrame first (lowercase columns, promote a date/datetime column to the index). Defaults to False.
  • raw_dates (bool): If True, use raw-dates mode — the x-axis coordinates are actual datetime values and matplotlib handles date formatting natively. Defaults to False, which maps dates to integer rownum positions with a custom date formatter (eliminating weekend/holiday gaps).
  • style (optional): Style spec, normalized via get_styler — a shipped style name (see styles.available_styles()), a matplotlib stylesheet name, a spec mapping (stylesheet/rc/settings/aliases), or a prebuilt Styler. Defaults to the "mplchart" style. Styles are total — ambient rcParams never affect the chart.
  • yaxis_right (bool): Whether the pane y-axis labels render on the right. Defaults to None, which consults the yaxis.right style setting, else False — the shipped styles declare yaxis.right: True (the finance convention), while styles without an opinion (e.g. a plain matplotlib stylesheet) keep matplotlib's left convention.
  • color_scheme: Deprecated and ignored — use style= with settings (e.g. Styler(settings={"sma.color": "red"})).

Examples:

chart = Chart(prices, title="AAPL", max_bars=252)
chart.plot([Candlesticks(), SMA(50), Volume()])
chart.show()

Chart.figure

The canvas figure.

Chart.pane

pane(position: PanePosition = 'below', *, height_ratio=None, yticks=None)

create a new pane and return self for chaining

Creation is sticky: the new pane becomes current and subsequent plots land on it. To draw a single primitive on an existing pane use the renderers' pane= parameter instead (e.g. LinePlot(x, pane="main")).

Arguments:

  • position (PanePosition): "below" (default) or "above" — where the new pane is inserted in the vertical stack
  • height_ratio: relative height of the new pane
  • yticks: tuple of y-axis tick values (also draws heavy grid lines)

Chart.plot

plot(*args)

Plot one or more indicators onto the chart.

Arguments:

  • *args: Any number of indicators or lists of indicators. Indicators may be Indicator instances, Primitive instances, or any callable that accepts a prices DataFrame. Use pane() or the Pane primitive to select or create the target pane.

Returns:

  • Chart: self, for method chaining.

Examples:

chart.plot(Candlesticks(), Volume())
chart.pane("above").plot(RSI(14))
chart.plot(Pane("below"), MACD())

Chart.vline

vline(date, *, color=None, linestyle=None)

Draw a vertical line across all panes at the given date.

Arguments:

  • date: date or date string for the vertical line position
  • color: line color (default: matplotlib grid.color)
  • linestyle: line style (default: matplotlib grid.linestyle)

Chart.hline

hline(value, *, color=None, linestyle=None)

Draw a horizontal line on the current pane at the given value.

Arguments:

  • value: y-axis value for the horizontal line position
  • color: line color (default: matplotlib grid.color)
  • linestyle: line style (default: matplotlib grid.linestyle)

Chart.show

show()

Display the chart via matplotlib.pyplot.show.

In scripts this opens the interactive figure window and blocks until it is closed; in notebooks the chart displays inline automatically at the end of the cell, so calling show() is usually not needed.

Chart.render

render(format='svg', *, dpi='figure')

Render the chart to bytes in the specified image format.

Arguments:

  • format (str): Output format, e.g. "svg", "png", "pdf". Defaults to "svg".
  • dpi (float or str): Resolution in dots per inch. Pass "figure" to use the figure's own DPI setting. Defaults to "figure".

Returns:

  • bytes: The rendered image as a byte string.