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,
    yaxis_log=False,
)

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.
  • yaxis_log (bool): Use a logarithmic y-axis on the main pane. Defaults to False. Additional panes and twin overlays retain their own linear scales. Logarithmic axes require positive values.

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. Line(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 columns, indicators, expressions, or primitives onto the chart.

Column names select data from prices; indicators and expressions are evaluated from prices during plotting. These inputs use default rendering (a line for a single series). Renderer primitives are optional: use Line, Area, or Bars to customize the display.

Arguments:

  • *args: Column names, indicators, expressions, primitives, or callables that accept a prices DataFrame; lists of these are also accepted. Use pane() or the Pane primitive to select or create the target pane.

Returns:

  • Chart: self, for method chaining.

Examples:

chart.plot("sma-50")  # existing column, default rendering
chart.plot(SMA(50))  # deferred calculation, default rendering
chart.plot(Line("sma-50", color="red"))  # optional customization
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', metadata: dict[str, Any] | None = None)

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".
  • metadata (dict): Metadata passed unchanged to Matplotlib's Figure.savefig. Supported keys and value types depend on the output format.

Returns:

  • bytes: The rendered image as a byte string.