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