Skip to content

Portfolio Guide

The Portfolio class provides a comprehensive suite of methods for portfolio analysis, risk management, and performance attribution.

Basic Usage

from pypulate import Portfolio

# Initialize portfolio analyzer
portfolio = Portfolio()

# Calculate basic returns
simple_ret = portfolio.simple_return(10, 12)
log_ret = portfolio.log_return(10, 12)

Return Metrics

Simple Returns

# Calculate simple returns
returns = portfolio.simple_return([10, 20, 25], [12, 21, 20])

# Calculate holding period return
hpr = portfolio.holding_period_return(
    [10, 20, 25]
)

# Calculate annualized return
annual_ret = portfolio.annualized_return(
    [10, 20, 25],
    years=2
)

Time-Weighted Returns

# Calculate time-weighted return
twrr = portfolio.time_weighted_return(
    [0.01, 0.03, 0.02, 0.02, 0.001],
)

Money-Weighted Returns

# Calculate money-weighted return (IRR)
mwrr = portfolio.money_weighted_return([-1000, -500, 1700], [0, 0.5, 1], 0)

Risk Metrics

Volatility Measures

# Calculate standard deviation
std_dev = portfolio.standard_deviation([0.01, 0.03, 0.02, 0.02, 0.001])

Value at Risk

# Calculate parametric VaR
var = portfolio.value_at_risk(
    [0.01, 0.03, 0.02, 0.02, 0.001],
    confidence_level=0.95,
    method = 'monte_carlo'
)

# Calculate conditional VaR (Expected Shortfall)
cvar = portfolio.conditional_value_at_risk(
    returns,
    confidence_level=0.95
)

Drawdown Analysis

# Calculate maximum drawdown
max_dd = portfolio.max_drawdown(prices)

# Get drawdown details
dd_amount, dd_percent, dd_length = portfolio.drawdown_details(prices)

Risk-Adjusted Performance

Sharpe Ratio

# Calculate Sharpe ratio
sharpe = portfolio.sharpe_ratio(
    returns,
    risk_free_rate=0.02,
    periods_per_year=252
)

Information Ratio

# Calculate Information ratio
info_ratio = portfolio.information_ratio(
    returns,
    benchmark_returns,
    periods_per_year=252
)

CAPM Metrics

# Calculate beta
beta = portfolio.beta(returns, market_returns)

# Calculate alpha
alpha = portfolio.alpha(
    returns,
    market_returns,
    risk_free_rate=0.02
)

Health Assessment

The health property provides a comprehensive assessment of portfolio health:

health = portfolio.health

# Health assessment structure
{
    'overall_score': 82.5,
    'status': 'Good',
    'components': {
        'returns': {
            'score': 85.0,
            'status': 'Good'
        },
        'risk': {
            'score': 78.0,
            'status': 'Good'
        },
        'risk_adjusted': {
            'score': 88.0,
            'status': 'Good'
        }
    }
}

Health Score Components

The portfolio health score is calculated based on three main components:

  • Returns (30%)
  • Absolute Returns
  • Relative Returns

  • Consistency of Returns

  • Risk Metrics (40%)

  • Volatility
  • Value at Risk
  • Maximum Drawdown

  • Recovery Time

  • Risk-Adjusted Performance (30%)

  • Sharpe Ratio
  • Information Ratio
  • Sortino Ratio
  • Treynor Ratio

Each component is scored from 0-100 and assigned a status: - Excellent: ≥ 90 - Good: ≥ 75 - Fair: ≥ 60 - Poor: ≥ 45 - Critical: < 45

State Management

The Portfolio class maintains state for calculated metrics in the _state dictionary:

# Access stored metrics
stored_returns = portfolio._state['returns']
stored_volatility = portfolio._state['volatility']
stored_sharpe = portfolio._state['sharpe_ratio']

Best Practices

1. Data Management

  • 1.1. Data Quality: Ensure price and return data is clean and properly formatted
  • 1.2. Time Consistency: Use consistent time periods for comparative analysis
  • 1.3. Adjustments: Account for dividends, splits, and corporate actions

2. Risk Assessment

  • 2.1. Regular Monitoring: Regularly monitor risk metrics
  • 2.2. Multiple Metrics: Use multiple risk measures for comprehensive assessment
  • 2.3. Stress Testing: Conduct stress tests under various market scenarios

3. Performance Analysis

  • 3.1. Benchmark Selection: Choose appropriate benchmarks for relative analysis
  • 3.2. Attribution: Analyze sources of returns and risk
  • 3.3. Health Monitoring: Regularly assess portfolio health

4. Reporting and Communication

  • 4.1. Clear Visualization: Present portfolio metrics with clear visualizations
  • 4.2. Context Provision: Provide context for performance numbers
  • 4.3. Consistent Reporting: Maintain consistent reporting formats