tessl/pypi-ffn

Financial functions for Python providing performance analysis, risk metrics, portfolio optimization, and data retrieval for quantitative finance

—

Pending

Overview

Eval results

Files

Performance Analysis

Name: tessl/pypi-ffn
Author: tessl

Comprehensive performance evaluation with detailed statistics, risk metrics, and visualization capabilities. Provides both single-asset analysis through PerformanceStats and multi-asset comparative analysis through GroupStats.

Capabilities

PerformanceStats Class

Performance evaluation class for individual price series containing comprehensive statistics, visualizations, and derived metrics.

class PerformanceStats:
    def __init__(self, prices, rf=0.0, annualization_factor=None):
        """
        Initialize performance statistics for a price series.

        Parameters:
        - prices (pd.Series): Price series with datetime index
        - rf (float, pd.Series): Risk-free rate (annualized) or risk-free rate price series
        - annualization_factor (float): Annualization factor (default: 252)
        """

    def set_riskfree_rate(self, rf):
        """
        Set annual risk-free rate and recalculate statistics.

        Parameters:
        - rf (float): Annual risk-free rate
        """

    def set_date_range(self, start, end):
        """
        Update date range for analysis and recalculate statistics.

        Parameters:
        - start: Start date
        - end: End date
        """

    def display(self):
        """Display comprehensive statistics overview."""

    def display_monthly_returns(self):
        """Display monthly returns table with YTD figures."""

    def display_lookback_returns(self):
        """Display current lookback returns for various periods."""

    def plot(self, freq='D', figsize=None, title=None, logy=False, **kwargs):
        """
        Plot price series.

        Parameters:
        - freq (str): Frequency for resampling ('D', 'M', 'Y')
        - figsize (tuple): Figure size
        - title (str): Plot title
        - logy (bool): Use logarithmic y-axis
        - **kwargs: Additional matplotlib arguments
        """

    def plot_histogram(self, freq='D', figsize=None, title=None, bins=50, **kwargs):
        """
        Plot return distribution histogram.

        Parameters:
        - freq (str): Frequency for resampling
        - figsize (tuple): Figure size
        - title (str): Plot title
        - bins (int): Number of histogram bins
        - **kwargs: Additional matplotlib arguments
        """

    def to_csv(self, sep=',', path=None):
        """
        Export statistics to CSV format.

        Parameters:
        - sep (str): Column separator
        - path (str): File path (if None, returns string)
        """

Core Properties:

name (str): Series name derived from input
prices (Series): Original price series
rf (float/Series): Risk-free rate used in calculations
annualization_factor (float): Trading days per year (default: 252)
start, end (datetime): Analysis period start and end dates

Price and Return Series:

daily_prices, monthly_prices, yearly_prices (Series): Resampled price series
returns, log_returns (Series): Daily return series (simple and log)
monthly_returns, yearly_returns (Series): Monthly and yearly return series

Return Performance Metrics:

total_return (float): Total return over entire period
cagr (float): Compound Annual Growth Rate
incep (float): Since inception return (same as CAGR)

Lookback Period Returns:

mtd, three_month, six_month (float): Short-term returns
ytd, one_year (float): Medium-term returns
three_year, five_year, ten_year (float): Long-term annualized returns

Risk and Drawdown Analysis:

max_drawdown (float): Maximum drawdown
drawdown (Series): Complete drawdown series
drawdown_details (DataFrame): Detailed drawdown analysis (Start, End, Length, drawdown)
avg_drawdown, avg_drawdown_days (float): Average drawdown and duration

Daily Statistics:

daily_mean, daily_vol (float): Daily mean and volatility (annualized)
daily_sharpe, daily_sortino (float): Daily Sharpe and Sortino ratios
daily_skew, daily_kurt (float): Daily returns skewness and kurtosis
best_day, worst_day (float): Best and worst single day returns

Monthly Statistics:

monthly_mean, monthly_vol (float): Monthly mean and volatility (annualized)
monthly_sharpe, monthly_sortino (float): Monthly Sharpe and Sortino ratios
monthly_skew, monthly_kurt (float): Monthly returns skewness and kurtosis
best_month, worst_month (float): Best and worst single month returns
pos_month_perc (float): Percentage of positive months
avg_up_month, avg_down_month (float): Average positive/negative month returns

Yearly Statistics:

yearly_mean, yearly_vol (float): Yearly mean and volatility
yearly_sharpe, yearly_sortino (float): Yearly Sharpe and Sortino ratios
yearly_skew, yearly_kurt (float): Yearly returns skewness and kurtosis
best_year, worst_year (float): Best and worst single year returns
win_year_perc, twelve_month_win_perc (float): Winning year percentages

Composite Risk Metrics:

calmar (float): Calmar ratio (CAGR / |Max Drawdown|)

Structured Data Properties:

stats (Series): All key statistics in one Series with labeled index
return_table (DataFrame): Monthly returns table (years × months + YTD column)
lookback_returns (Series): Returns for different periods ['mtd', '3m', '6m', 'ytd', '1y', '3y', '5y', '10y', 'incep']

GroupStats Class

Comparative analysis class for multiple price series providing side-by-side statistics and visualization capabilities.

class GroupStats:
    def __init__(self, *prices):
        """
        Initialize comparative statistics for multiple price series.

        Parameters:
        - *prices: Multiple price series (pd.Series) to compare
        """

    def set_riskfree_rate(self, rf):
        """
        Set risk-free rate for all series and recalculate statistics.

        Parameters:
        - rf (float): Annual risk-free rate
        """

    def set_date_range(self, start, end):
        """
        Update date range for all series and recalculate statistics.

        Parameters:
        - start: Start date
        - end: End date
        """

    def display(self):
        """Display comparative statistics table."""

    def display_lookback_returns(self):
        """Display lookback returns for all series."""

    def plot(self, freq='D', figsize=None, title=None, logy=False, **kwargs):
        """
        Plot all series on same chart.

        Parameters:
        - freq (str): Frequency for resampling
        - figsize (tuple): Figure size
        - title (str): Plot title
        - logy (bool): Use logarithmic y-axis
        - **kwargs: Additional matplotlib arguments
        """

    def plot_scatter_matrix(self, freq='D', title=None, figsize=None, **kwargs):
        """
        Create scatter plot matrix showing correlations.

        Parameters:
        - freq (str): Frequency for resampling
        - title (str): Plot title
        - figsize (tuple): Figure size
        - **kwargs: Additional matplotlib arguments
        """

    def plot_histograms(self, freq='D', title=None, figsize=None, **kwargs):
        """
        Plot histogram matrix for return distributions.

        Parameters:
        - freq (str): Frequency for resampling
        - title (str): Plot title
        - figsize (tuple): Figure size
        - **kwargs: Additional matplotlib arguments
        """

    def plot_correlation(self, freq='D', title=None, figsize=None, **kwargs):
        """
        Plot correlation heatmap.

        Parameters:
        - freq (str): Frequency for resampling
        - title (str): Plot title
        - figsize (tuple): Figure size
        - **kwargs: Additional matplotlib arguments
        """

    def to_csv(self, sep=',', path=None):
        """
        Export comparative statistics to CSV.

        Parameters:
        - sep (str): Column separator
        - path (str): File path (if None, returns string)
        """

Key Properties:

stats: DataFrame with statistics for each series (rows=stats, columns=series)
lookback_returns: DataFrame with lookback returns for all series
prices: Merged and rebased prices DataFrame

Convenience Functions

High-level functions for quick performance analysis without manually creating class instances.

def calc_perf_stats(prices, risk_free_rate=0.0, annualization_factor=252):
    """
    Calculate PerformanceStats object for given prices.

    Parameters:
    - prices (pd.Series): Price series
    - risk_free_rate (float): Risk-free rate (default: 0.0)
    - annualization_factor (int): Annualization factor (default: 252)

    Returns:
    PerformanceStats object
    """

def calc_stats(prices):
    """
    Calculate PerformanceStats or GroupStats based on input type.

    Parameters:
    - prices (pd.Series or pd.DataFrame): Price data

    Returns:
    PerformanceStats if Series input, GroupStats if DataFrame input
    """

Usage Examples

Single Asset Analysis

import ffn

# Download and analyze single stock
prices = ffn.get('AAPL', start='2020-01-01')['AAPL']
perf = ffn.calc_perf_stats(prices, risk_free_rate=0.02)

# Display comprehensive statistics
perf.display()

# Access specific metrics
print(f"CAGR: {perf.cagr:.2%}")
print(f"Max Drawdown: {perf.max_drawdown:.2%}")
print(f"Sharpe Ratio: {perf.sharpe:.2f}")

# Generate plots
perf.plot(title='AAPL Price Performance')
perf.plot_histogram(title='AAPL Return Distribution')

Multi-Asset Comparison

import ffn

# Download multiple assets
prices = ffn.get('AAPL,MSFT,GOOGL', start='2020-01-01')

# Create comparative analysis
group = ffn.GroupStats(prices['AAPL'], prices['MSFT'], prices['GOOGL'])

# Display comparative statistics
group.display()

# Visualization
group.plot(title='Tech Stock Comparison')
group.plot_correlation(title='Correlation Matrix')
group.plot_scatter_matrix(title='Return Relationships')

Install with Tessl CLI