Metadata-Version: 2.4
Name: finance-plots
Version: 0.1.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.10
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.10
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-calcs<0.2,>=0.1; extra == 'develop'
Requires-Dist: finance-datagen<0.3,>=0.2.1; 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-calcs<0.2,>=0.1; extra == 'examples'
Requires-Dist: finance-datagen<0.3,>=0.2.1; 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`.

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

## Current Table Catalog

| Function                                       | Use it for                                                                                               |
| ---------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `perf_stats(returns)`                          | Dictionary of cumulative return, annualized return/volatility, Sharpe, Sortino, max drawdown, and Calmar |
| `table_perf_stats(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                                                             |
