tessl/pypi-quantstats
Portfolio analytics for quants - comprehensive statistical analysis, risk assessment, and performance visualization for quantitative finance
—
Pending
Quality
Pending
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
performance-visualization.mddocs/
Performance Visualization
Comprehensive plotting and charting functions for creating professional-grade performance visualizations including cumulative returns, rolling metrics, drawdown analysis, return distributions, and interactive charts for quantitative analysis.
Capabilities
Comprehensive Performance Snapshots
Multi-panel performance overviews combining key metrics and visualizations.
def snapshot(returns, grayscale=False, figsize=(10, 8), title="Portfolio Summary", show=True, log_scale=False, **kwargs):
"""
Create comprehensive performance snapshot with multiple panels.
Parameters:
- returns: pandas Series of returns
- grayscale: bool, whether to use grayscale color scheme
- figsize: tuple, figure size (width, height)
- title: str, chart title
- show: bool, whether to display the plot
- log_scale: bool, whether to use log scale for returns
- **kwargs: additional plotting parameters
Returns:
matplotlib Figure: Multi-panel performance chart
"""Cumulative Returns Visualization
Track portfolio performance over time with various return representations.
def returns(returns, benchmark=None, grayscale=False, figsize=(10, 6), log_scale=False, **kwargs):
"""
Plot cumulative returns over time.
Parameters:
- returns: pandas Series of returns
- benchmark: pandas Series of benchmark returns (optional)
- grayscale: bool, whether to use grayscale colors
- figsize: tuple, figure size
- log_scale: bool, whether to use logarithmic scale
- **kwargs: additional plotting parameters
Returns:
matplotlib Figure: Cumulative returns chart
"""
def log_returns(returns, benchmark=None, grayscale=False, figsize=(10, 6), **kwargs):
"""
Plot log-scaled cumulative returns.
Parameters:
- returns: pandas Series of returns
- benchmark: pandas Series of benchmark returns (optional)
- grayscale: bool, whether to use grayscale colors
- figsize: tuple, figure size
- **kwargs: additional plotting parameters
Returns:
matplotlib Figure: Log-scaled returns chart
"""
def earnings(returns, start_balance=1e5, mode="comp", grayscale=False, figsize=(10, 6), **kwargs):
"""
Plot portfolio earnings/value over time.
Parameters:
- returns: pandas Series of returns
- start_balance: float, starting portfolio balance
- mode: str, calculation mode ('comp' for compounded)
- grayscale: bool, whether to use grayscale colors
- figsize: tuple, figure size
- **kwargs: additional plotting parameters
Returns:
matplotlib Figure: Portfolio earnings chart
"""Drawdown Analysis Visualization
Visualize portfolio drawdowns and underwater periods.
def drawdown(returns, grayscale=False, figsize=(10, 5), **kwargs):
"""
Create underwater/drawdown plot showing portfolio drawdowns over time.
Parameters:
- returns: pandas Series of returns
- grayscale: bool, whether to use grayscale colors
- figsize: tuple, figure size
- **kwargs: additional plotting parameters
Returns:
matplotlib Figure: Drawdown underwater chart
"""
def drawdowns_periods(returns, periods=5, lw=1.5, log_scale=False, figsize=(10, 6), **kwargs):
"""
Plot the longest drawdown periods.
Parameters:
- returns: pandas Series of returns
- periods: int, number of longest periods to highlight
- lw: float, line width
- log_scale: bool, whether to use log scale
- figsize: tuple, figure size
- **kwargs: additional plotting parameters
Returns:
matplotlib Figure: Longest drawdown periods chart
"""Return Distribution Analysis
Analyze and visualize return distribution characteristics.
def distribution(returns, grayscale=False, figsize=(10, 6), **kwargs):
"""
Plot return distribution with histogram and normal curve overlay.
Parameters:
- returns: pandas Series of returns
- grayscale: bool, whether to use grayscale colors
- figsize: tuple, figure size
- **kwargs: additional plotting parameters
Returns:
matplotlib Figure: Return distribution chart
"""
def histogram(returns, benchmark=None, resample="ME", grayscale=False, figsize=(10, 6), **kwargs):
"""
Create histogram of resampled returns.
Parameters:
- returns: pandas Series of returns
- benchmark: pandas Series of benchmark returns (optional)
- resample: str, resampling frequency ('ME' for month-end, 'QE' for quarter-end)
- grayscale: bool, whether to use grayscale colors
- figsize: tuple, figure size
- **kwargs: additional plotting parameters
Returns:
matplotlib Figure: Returns histogram
"""
def daily_returns(returns, benchmark, grayscale=False, figsize=(10, 4), **kwargs):
"""
Plot daily returns time series.
Parameters:
- returns: pandas Series of portfolio returns
- benchmark: pandas Series of benchmark returns
- grayscale: bool, whether to use grayscale colors
- figsize: tuple, figure size
- **kwargs: additional plotting parameters
Returns:
matplotlib Figure: Daily returns chart
"""Rolling Metrics Visualization
Visualize time-varying performance metrics over rolling windows.
def rolling_sharpe(returns, benchmark=None, rf=0.0, periods=252, window=126, grayscale=False, figsize=(10, 6), **kwargs):
"""
Plot rolling Sharpe ratio over time.
Parameters:
- returns: pandas Series of returns
- benchmark: pandas Series of benchmark returns (optional)
- rf: float, risk-free rate
- periods: int, number of periods per year
- window: int, rolling window size
- grayscale: bool, whether to use grayscale colors
- figsize: tuple, figure size
- **kwargs: additional plotting parameters
Returns:
matplotlib Figure: Rolling Sharpe ratio chart
"""
def rolling_sortino(returns, benchmark=None, rf=0.0, periods=252, window=126, grayscale=False, figsize=(10, 6), **kwargs):
"""
Plot rolling Sortino ratio over time.
Parameters:
- returns: pandas Series of returns
- benchmark: pandas Series of benchmark returns (optional)
- rf: float, risk-free rate
- periods: int, number of periods per year
- window: int, rolling window size
- grayscale: bool, whether to use grayscale colors
- figsize: tuple, figure size
- **kwargs: additional plotting parameters
Returns:
matplotlib Figure: Rolling Sortino ratio chart
"""
def rolling_volatility(returns, benchmark=None, period=126, grayscale=False, figsize=(10, 6), **kwargs):
"""
Plot rolling volatility over time.
Parameters:
- returns: pandas Series of returns
- benchmark: pandas Series of benchmark returns (optional)
- period: int, rolling window size
- grayscale: bool, whether to use grayscale colors
- figsize: tuple, figure size
- **kwargs: additional plotting parameters
Returns:
matplotlib Figure: Rolling volatility chart
"""
def rolling_beta(returns, benchmark, window1=126, window2=252, grayscale=False, figsize=(10, 6), **kwargs):
"""
Plot rolling beta coefficients over time.
Parameters:
- returns: pandas Series of portfolio returns
- benchmark: pandas Series of benchmark returns
- window1: int, first rolling window size
- window2: int, second rolling window size
- grayscale: bool, whether to use grayscale colors
- figsize: tuple, figure size
- **kwargs: additional plotting parameters
Returns:
matplotlib Figure: Rolling beta chart
"""Calendar-Based Visualizations
Time-period performance analysis with calendar views.
def monthly_heatmap(returns, benchmark=None, grayscale=False, figsize=(10, 5), cbar=True, **kwargs):
"""
Create monthly returns heatmap showing performance by month and year.
Parameters:
- returns: pandas Series of returns
- benchmark: pandas Series of benchmark returns (optional)
- grayscale: bool, whether to use grayscale colors
- figsize: tuple, figure size
- cbar: bool, whether to show color bar
- **kwargs: additional plotting parameters
Returns:
matplotlib Figure: Monthly returns heatmap
"""
def monthly_returns(returns, grayscale=False, figsize=(10, 5), **kwargs):
"""
Create monthly returns heatmap (wrapper for monthly_heatmap).
Parameters:
- returns: pandas Series of returns
- grayscale: bool, whether to use grayscale colors
- figsize: tuple, figure size
- **kwargs: additional plotting parameters
Returns:
matplotlib Figure: Monthly returns heatmap
"""
def yearly_returns(returns, benchmark=None, grayscale=False, figsize=(10, 6), **kwargs):
"""
Plot end-of-year returns as bar chart.
Parameters:
- returns: pandas Series of returns
- benchmark: pandas Series of benchmark returns (optional)
- grayscale: bool, whether to use grayscale colors
- figsize: tuple, figure size
- **kwargs: additional plotting parameters
Returns:
matplotlib Figure: Annual returns bar chart
"""Interactive and Export Features
Enhance visualizations with interactivity and export capabilities.
def to_plotly(fig):
"""
Convert matplotlib figure to Plotly for interactivity (if Plotly available).
Parameters:
- fig: matplotlib Figure object
Returns:
plotly Figure: Interactive Plotly figure (if available)
"""Usage Examples
Basic Performance Visualization
import quantstats as qs
import pandas as pd
import numpy as np
# Create sample data
dates = pd.date_range('2020-01-01', '2023-12-31', freq='D')
returns = pd.Series(np.random.normal(0.001, 0.02, len(dates)), index=dates)
# Create comprehensive performance snapshot
qs.plots.snapshot(returns, title="Portfolio Performance Analysis")
# Plot cumulative returns
qs.plots.returns(returns, figsize=(12, 8))
# Visualize drawdowns
qs.plots.drawdown(returns)Benchmarking Visualization
# Load benchmark data
spy_returns = qs.utils.download_returns('SPY')
# Compare against benchmark
qs.plots.returns(returns, benchmark=spy_returns, title="Portfolio vs SPY")
qs.plots.rolling_sharpe(returns, benchmark=spy_returns)
qs.plots.monthly_heatmap(returns, benchmark=spy_returns)Distribution Analysis
# Analyze return distributions
qs.plots.distribution(returns)
qs.plots.histogram(returns, resample='ME') # Monthly returns histogram
qs.plots.yearly_returns(returns) # Annual performance barsConstants
_FLATUI_COLORS: list
"""Default color palette for plots"""
_GRAYSCALE_COLORS: list
"""Grayscale color palette for professional presentations"""
_HAS_PLOTLY: bool
"""Boolean indicating whether Plotly is available for interactive plots"""Install with Tessl CLI
npx tessl i tessl/pypi-quantstats