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

Return Calculations

Name: tessl/pypi-ffn
Author: tessl

Convert between prices and returns using various methods, including simple returns, log returns, and price indexing with rebasing capabilities. Essential functions for time series transformations in financial analysis.

Capabilities

Price to Returns Conversion

Transform price series into return series using different calculation methods.

def to_returns(prices):
    """
    Calculate simple arithmetic returns from price series.

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

    Returns:
    pd.Series or pd.DataFrame: Simple returns (percent change)
    """

def to_log_returns(prices):
    """
    Calculate logarithmic returns from price series.

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

    Returns:
    pd.Series or pd.DataFrame: Log returns
    """

Returns to Price Index Conversion

Convert return series back to price index form for analysis and visualization.

def to_price_index(returns, start=100):
    """
    Convert returns to cumulative price index.

    Parameters:
    - returns (pd.Series or pd.DataFrame): Return series
    - start (float): Starting value for price index (default: 100)

    Returns:
    pd.Series or pd.DataFrame: Cumulative price index
    """

Price Rebasing

Standardize price series to common starting values for comparison.

def rebase(prices, value=100):
    """
    Rebase all price series to given initial value.

    Parameters:
    - prices (pd.Series or pd.DataFrame): Price series
    - value (float): New starting value (default: 100)

    Returns:
    pd.Series or pd.DataFrame: Rebased prices
    """

Performance Metrics from Returns

Calculate key performance metrics directly from return series.

def calc_cagr(prices):
    """
    Calculate compound annual growth rate.

    Parameters:
    - prices (pd.Series): Price series

    Returns:
    float: CAGR as decimal (e.g., 0.12 for 12%)
    """

def calc_total_return(prices):
    """
    Calculate total return over the entire period.

    Parameters:
    - prices (pd.Series): Price series

    Returns:
    float: Total return as decimal
    """

Usage Examples

Basic Return Calculations

import ffn

# Download price data
prices = ffn.get('AAPL', start='2020-01-01')['AAPL']

# Calculate simple returns
returns = ffn.to_returns(prices)
print(f"First 5 returns:\n{returns.head()}")

# Calculate log returns
log_returns = ffn.to_log_returns(prices)
print(f"Mean log return: {log_returns.mean():.4f}")

# Calculate CAGR
cagr = ffn.calc_cagr(prices)
print(f"CAGR: {cagr:.2%}")

Price Index Construction

import ffn

# Start with returns data
prices = ffn.get('AAPL,MSFT', start='2020-01-01')
returns = ffn.to_returns(prices).dropna()

# Convert back to price index starting at 100
price_index = ffn.to_price_index(returns, start=100)
print(f"Final values:\n{price_index.iloc[-1]}")

# Rebase original prices to 100
rebased_prices = ffn.rebase(prices, value=100)
print(f"All series start at: {rebased_prices.iloc[0]}")

Method Chaining with Pandas Extensions

import ffn

# FFN extends pandas automatically
prices = ffn.get('AAPL', start='2020-01-01')['AAPL']

# Method chaining for functional composition
result = (prices
    .to_returns()           # Convert to returns
    .dropna()               # Remove NaN values
    .to_price_index(100)    # Convert back to price index
    .calc_cagr()            # Calculate CAGR
)

print(f"CAGR via chaining: {result:.2%}")

# Multi-step transformation
analysis_ready = (prices
    .rebase(100)            # Rebase to 100
    .to_returns()           # Convert to returns  
    .dropna()               # Clean data
)

print(f"Returns summary:\n{analysis_ready.describe()}")

Portfolio Return Calculations

import ffn
import pandas as pd

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

# Equal weight portfolio returns
equal_weights = pd.Series([1/3, 1/3, 1/3], index=returns.columns)
portfolio_returns = (returns * equal_weights).sum(axis=1)

# Convert portfolio returns to price index
portfolio_index = ffn.to_price_index(portfolio_returns, start=1000)
portfolio_cagr = ffn.calc_cagr(portfolio_index)

print(f"Portfolio CAGR: {portfolio_cagr:.2%}")
print(f"Final portfolio value: ${portfolio_index.iloc[-1]:.2f}")

Install with Tessl CLI