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

Overview

Eval results

Files

Report Generation

Name: tessl/pypi-quantstats
Author: tessl

Professional tearsheet and report generation capabilities including comprehensive HTML reports, performance metrics tables, and customizable analysis layouts with benchmarking support for institutional-grade portfolio reporting.

Capabilities

HTML Report Generation

Create comprehensive HTML tearsheets with embedded charts and detailed analytics.

def html(returns, benchmark=None, rf=0.0, grayscale=False, title="Strategy Tearsheet", output=None, download_filename="quantstats-tearsheet.html", figfmt="svg", template_path=None, match_dates=True, **kwargs):
    """
    Generate comprehensive HTML tearsheet report.
    
    Parameters:
    - returns: pandas Series of portfolio returns
    - benchmark: pandas Series of benchmark returns (optional)
    - rf: float, risk-free rate (default 0.0)
    - grayscale: bool, whether to use grayscale color scheme
    - title: str, report title
    - output: str, output file path (optional)
    - download_filename: str, default filename for download
    - figfmt: str, figure format ('svg', 'png', 'jpg')
    - template_path: str, path to custom HTML template
    - match_dates: bool, whether to match portfolio and benchmark dates
    - **kwargs: additional parameters
    
    Returns:
    str: HTML content string
    """

def full(returns, benchmark=None, rf=0.0, grayscale=False, figsize=(10, 8), display=True, compounded=True, **kwargs):
    """
    Generate full performance report with plots and metrics.
    
    Parameters:
    - returns: pandas Series of portfolio returns
    - benchmark: pandas Series of benchmark returns (optional)
    - rf: float, risk-free rate
    - grayscale: bool, whether to use grayscale colors
    - figsize: tuple, figure size for plots
    - display: bool, whether to display the report
    - compounded: bool, whether returns are compounded
    - **kwargs: additional parameters
    
    Returns:
    dict: Dictionary containing plots and metrics
    """

def basic(returns, benchmark=None, display=True, compounded=True, **kwargs):
    """
    Generate basic performance metrics report without plots.
    
    Parameters:
    - returns: pandas Series of portfolio returns
    - benchmark: pandas Series of benchmark returns (optional)
    - display: bool, whether to display the report
    - compounded: bool, whether returns are compounded
    - **kwargs: additional parameters
    
    Returns:
    pandas DataFrame: Basic performance metrics
    """

Metrics Tables

Generate structured performance metrics tables and summaries.

def metrics(returns, benchmark=None, rf=0.0, display=True, mode="basic", compounded=True, **kwargs):
    """
    Generate comprehensive performance metrics table.
    
    Parameters:
    - returns: pandas Series of portfolio returns
    - benchmark: pandas Series of benchmark returns (optional)
    - rf: float, risk-free rate
    - display: bool, whether to display the metrics
    - mode: str, metrics mode ('basic', 'full')
    - compounded: bool, whether returns are compounded
    - **kwargs: additional parameters
    
    Returns:
    pandas DataFrame: Performance metrics table with portfolio and benchmark columns
    """

Plot Collections

Generate complete sets of performance visualizations.

def plots(returns, benchmark=None, grayscale=False, figsize=(10, 8), **kwargs):
    """
    Generate comprehensive collection of performance plots.
    
    Parameters:
    - returns: pandas Series of portfolio returns
    - benchmark: pandas Series of benchmark returns (optional)  
    - grayscale: bool, whether to use grayscale colors
    - figsize: tuple, default figure size
    - **kwargs: additional plotting parameters
    
    Returns:
    dict: Dictionary of matplotlib Figure objects for each plot type
    """

Usage Examples

Basic HTML Report

import quantstats as qs
import pandas as pd

# Load portfolio returns
returns = pd.read_csv('portfolio_returns.csv', index_col=0, parse_dates=True).squeeze()

# Generate basic HTML tearsheet
qs.reports.html(returns, output='portfolio_tearsheet.html')

# Generate with benchmark comparison
benchmark = qs.utils.download_returns('SPY')
qs.reports.html(returns, benchmark=benchmark, 
                title="Portfolio vs S&P 500",
                output='portfolio_vs_spy.html')

Metrics Analysis

# Generate comprehensive metrics table
metrics_df = qs.reports.metrics(returns, benchmark=benchmark, rf=0.02)
print(metrics_df)

# Basic metrics without benchmark
basic_metrics = qs.reports.basic(returns)
print(basic_metrics)

Custom Report Generation

# Generate full report with custom parameters
full_report = qs.reports.full(
    returns, 
    benchmark=benchmark,
    rf=0.025,
    grayscale=True,
    figsize=(12, 8),
    title="Institutional Portfolio Analysis"
)

# Access individual components
plots_dict = full_report['plots']
metrics_table = full_report['metrics']

Professional Tearsheet with Custom Styling

# Generate professional grayscale tearsheet
qs.reports.html(
    returns,
    benchmark=benchmark,
    rf=0.02,
    grayscale=True,
    title="Quantitative Strategy Performance",
    output='strategy_tearsheet.html',
    figfmt='svg',  # High-quality vector graphics
    download_filename='strategy_analysis.html'
)

Report Components

The HTML reports include the following sections:

Performance Summary

Key performance metrics table
Risk-adjusted returns analysis
Drawdown statistics
Win/loss analysis

Visualizations

Cumulative returns chart
Rolling Sharpe ratio
Drawdown underwater plot
Monthly returns heatmap
Return distribution histogram
Rolling volatility

Risk Analysis

Value at Risk metrics
Tail risk measures
Correlation analysis (when benchmark provided)
Beta analysis (when benchmark provided)

Detailed Metrics

Return statistics
Risk metrics
Ratios and factors
Calendar analysis

Internal Functions

def _get_trading_periods(periods_per_year=252):
    """
    Calculate trading periods for different time windows.
    
    Parameters:
    - periods_per_year: int, number of trading periods per year
    
    Returns:
    dict: Dictionary with trading period information
    """

def _match_dates(returns, benchmark):
    """
    Match dates between portfolio returns and benchmark.
    
    Parameters:
    - returns: pandas Series of portfolio returns
    - benchmark: pandas Series of benchmark returns
    
    Returns:
    tuple: Matched returns and benchmark series
    """

def _calc_dd(df, display=True, as_pct=False):
    """
    Calculate detailed drawdown analysis.
    
    Parameters:
    - df: pandas DataFrame or Series
    - display: bool, whether to display results
    - as_pct: bool, whether to format as percentages
    
    Returns:
    pandas DataFrame: Drawdown analysis details
    """

def _html_table(obj, showindex="default"):
    """
    Convert pandas object to HTML table format.
    
    Parameters:
    - obj: pandas DataFrame or Series
    - showindex: str, whether to show index ('default', True, False)
    
    Returns:
    str: HTML table string
    """

def _download_html(html, filename="quantstats-tearsheet.html"):
    """
    Prepare HTML content for download.
    
    Parameters:
    - html: str, HTML content
    - filename: str, download filename
    
    Returns:
    str: Prepared HTML with download headers
    """

def _open_html(html):
    """
    Open HTML content in default browser.
    
    Parameters:
    - html: str, HTML content
    
    Returns:
    None
    """

def _embed_figure(figfiles, figfmt):
    """
    Embed figure files into HTML report.
    
    Parameters:
    - figfiles: list, list of figure file paths
    - figfmt: str, figure format
    
    Returns:
    str: Embedded HTML figure content
    """

Install with Tessl CLI