finance plots

Matplotlib plots and performance tables for financial return series, price paths, and technical-indicator panels.

Overview

finance-plots is the presentation layer for the finance stack. It accepts Narwhals-compatible inputs such as pandas, Polars, numpy, and other supported series-like objects, then returns ordinary matplotlib figures or Great Tables objects that can be saved, embedded in notebooks, or composed into tearsheets.

The initial release focuses on a compact, useful surface:

• Return/risk plots for cumulative returns, rolling volatility, rolling Sharpe, rolling beta/correlation, benchmark scatter, drawdowns, and period-return views.
• Technical-indicator plots for price overlays, secondary-axis indicators, and indicator sub-panels.
• Performance summary tables backed by great-tables.
• Post-trade diagnostics for trading-cost breakdowns, MAE/MFE scatter, and execution-quality distributions.
• Alpha-analysis plots for IC, quantile returns, turnover, and cumulative factor returns.

Install

pip install finance-plots

The gallery and documentation examples use the released data/calculation stack:

pip install "finance-plots[examples]"

Quick Start

Generate deterministic prices with finance-datagen, compute returns with finance-calcs, and plot them with finance-plots.

from datetime import datetime, timezone

import polars as pl
from finance_datagen import generate_prices

import finance_calcs as fc
import finance_plots as fp

start_ms = int(datetime(2021, 1, 4, tzinfo=timezone.utc).timestamp() * 1000)
prices = generate_prices(symbol="ACME", seed=7, start_ms=start_ms)
returns = prices.with_columns(
    fc.simple_returns(pl.col("price")).alias("ret"),
).select("ret").drop_nulls()["ret"]

fig = fp.plot_rolling_returns(returns)

Current Plot Catalog

Function	Use it for
plot_returns(returns)	Simple cumulative return path
plot_rolling_returns(returns, benchmark=None, live_start=None)	Cumulative return path with optional benchmark and out-of-sample shading
plot_rolling_volatility(returns, window=63)	Rolling annualized volatility
plot_rolling_sharpe(returns, window=63)	Rolling annualized Sharpe ratio
plot_rolling_beta(returns, benchmark, window=63)	Rolling beta versus a benchmark
plot_rolling_correlation(returns, benchmark, window=63)	Rolling correlation versus a benchmark
plot_return_scatter(returns, benchmark)	Strategy returns against benchmark returns with a fitted beta line
plot_drawdown_underwater(returns)	Filled underwater drawdown chart
plot_returns_heatmap(returns, period="month")	Year-by-month, year-by-quarter, or year-by-week return heatmap
plot_returns_bar(returns, period="year")	Compounded period returns as a bar chart
plot_returns_dist(returns, period="month")	Distribution of compounded period returns
plot_returns_timeseries(returns, period="month")	Compounded period returns through time
plot_price_with_overlays(price, overlays, secondary_overlays)	Price line with moving averages and secondary-axis indicators
plot_indicator_panel(price, panels)	Price chart with one or more aligned indicator sub-panels
plot_trading_cost_breakdown_bar(costs)	Trading cost attribution by component
plot_mfe_mae_scatter(trades)	Maximum adverse versus favorable excursion by trade
plot_execution_quality(executions)	Implementation-shortfall distribution
plot_ic_ts(ic)	Information-coefficient time series with rolling mean
plot_ic_hist(ic)	Information-coefficient distribution
plot_ic_qq(ic)	Information-coefficient Q-Q plot
plot_ic_by_group(data)	Mean IC by sector/group
plot_ic_heatmap(ic)	Calendar heatmap of mean IC
plot_rolling_ic(ic)	Rolling mean IC
plot_quantile_returns_bar(data)	Mean return by signal quantile
plot_top_bottom_quantile_turnover(data)	Top/bottom quantile turnover
plot_cumulative_factor_returns(factor_returns)	Compounded long-short factor return path

Current Table Catalog

Function	Use it for
performance_statistics(returns)	Dictionary of cumulative return, annualized return/volatility, Sharpe, Sortino, max drawdown, and Calmar
table_performance_statistics(returns, benchmark=None)	Great Tables performance summary with optional benchmark column
table_period_returns(returns, period="year")	Great Tables period-return summary
table_drawdowns(returns, top=5)	Great Tables largest-drawdown-period summary
table_cost_breakdown(costs)	Great Tables trading-cost attribution summary
table_round_trip_stats(trades)	Great Tables round-trip trade-quality summary
table_execution_quality(executions)	Great Tables implementation-shortfall summary
table_information(ic)	Great Tables information-coefficient summary
table_returns_by_quantile(data)	Great Tables mean return by quantile
table_turnover(data)	Great Tables quantile-turnover summary
table_quantile_statistics(data)	Great Tables quantile counts and signal statistics