Metadata-Version: 2.5
Name: finance-plots
Version: 0.2.0
Summary: Standard financial plots
Project-URL: Repository, https://github.com/prettygoodcapital/finance-plots
Project-URL: Homepage, https://github.com/prettygoodcapital/finance-plots
Author-email: PrettyGoodCapital <prettygoodcapital@gmail.com>
License: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.11
Requires-Dist: finance-calcs<0.4,>=0.3.0
Requires-Dist: finance-enums<0.8,>=0.5.1
Requires-Dist: great-tables>=0.10
Requires-Dist: matplotlib>=3.7
Requires-Dist: narwhals>=1.0
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: polars>=1.0
Provides-Extra: develop
Requires-Dist: build; extra == 'develop'
Requires-Dist: bump-my-version; extra == 'develop'
Requires-Dist: check-dist; extra == 'develop'
Requires-Dist: codespell; extra == 'develop'
Requires-Dist: finance-datagen<0.4,>=0.3.2; extra == 'develop'
Requires-Dist: hatchling; extra == 'develop'
Requires-Dist: mdformat; extra == 'develop'
Requires-Dist: mdformat-tables>=1; extra == 'develop'
Requires-Dist: pytest; extra == 'develop'
Requires-Dist: pytest-cov; extra == 'develop'
Requires-Dist: ruff; extra == 'develop'
Requires-Dist: twine; extra == 'develop'
Requires-Dist: ty; extra == 'develop'
Requires-Dist: uv; extra == 'develop'
Requires-Dist: wheel; extra == 'develop'
Requires-Dist: yardang; extra == 'develop'
Provides-Extra: examples
Requires-Dist: finance-datagen<0.4,>=0.3.2; extra == 'examples'
Description-Content-Type: text/markdown

# finance plots

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

[![Build Status](https://github.com/prettygoodcapital/finance-plots/actions/workflows/build.yaml/badge.svg?branch=main&event=push)](https://github.com/prettygoodcapital/finance-plots/actions/workflows/build.yaml)
[![codecov](https://codecov.io/gh/prettygoodcapital/finance-plots/branch/main/graph/badge.svg)](https://codecov.io/gh/prettygoodcapital/finance-plots)
[![License](https://img.shields.io/github/license/prettygoodcapital/finance-plots)](https://github.com/prettygoodcapital/finance-plots)
[![PyPI](https://img.shields.io/pypi/v/finance-plots.svg)](https://pypi.python.org/pypi/finance-plots)

## 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

```bash
pip install finance-plots
```

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

```bash
pip install "finance-plots[examples]"
```

## Quick Start

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

```python
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                                                       |
