portfolio_toolkit.optimization.efficient_frontier module

Efficient Frontier Calculation Module

This module provides functions to calculate the efficient frontier for portfolio optimization using mean-variance optimization theory.

portfolio_toolkit.optimization.efficient_frontier.compute_efficient_frontier(expected_returns: Series, covariance_matrix: DataFrame, num_points: int = 100, risk_free_rate: float = 0.0) → Dict[str, List[float]]

Calculate the efficient frontier for a given set of assets.

The efficient frontier represents the set of optimal portfolios that offer the highest expected return for each level of risk (volatility).

Parameters:

expected_returnspd.Series

Expected returns for each asset. Index should match covariance_matrix columns.

covariance_matrixpd.DataFrame

Covariance matrix of asset returns. Must be symmetric and positive semi-definite.

num_pointsint, default=100

Number of points to calculate along the efficient frontier.

risk_free_ratefloat, default=0.0

Risk-free rate for Sharpe ratio calculations.

Returns:

Dict[str, List[float]]

Dictionary containing: - ‘volatility’: List of portfolio volatilities (standard deviations) - ‘returns’: List of portfolio expected returns - ‘weights’: List of weight arrays for each portfolio

Example:

>>> expected_returns = pd.Series([0.10, 0.12, 0.08], index=['A', 'B', 'C'])
>>> cov_matrix = pd.DataFrame([[0.05, 0.02, 0.01],
...                           [0.02, 0.08, 0.03],
...                           [0.01, 0.03, 0.04]],
...                          index=['A', 'B', 'C'], columns=['A', 'B', 'C'])
>>> frontier = get_efficient_frontier(expected_returns, cov_matrix, 50)
>>> print(f"Min volatility: {min(frontier['volatility']):.4f}")
>>> print(f"Max return: {max(frontier['returns']):.4f}")

portfolio_toolkit.optimization.efficient_frontier.calculate_portfolio_metrics(weights: List[float] | ndarray, expected_returns: Series, covariance_matrix: DataFrame, risk_free_rate: float = 0.0) → Dict[str, float]

Calculate key portfolio metrics for given weights.

Parameters:

weightsList[float] or np.ndarray

Portfolio weights

expected_returnspd.Series

Expected returns for each asset

covariance_matrixpd.DataFrame

Covariance matrix of asset returns

risk_free_ratefloat, default=0.0

Risk-free rate for Sharpe ratio calculation

Returns:

Dict[str, float]

Dictionary containing portfolio metrics: - ‘return’: Expected portfolio return - ‘volatility’: Portfolio volatility (standard deviation) - ‘sharpe_ratio’: Sharpe ratio

portfolio_toolkit.optimization.efficient_frontier.find_maximum_sharpe_portfolio(expected_returns: Series, covariance_matrix: DataFrame, risk_free_rate: float = 0.0) → Dict[str, ndarray | float]

Find the portfolio with maximum Sharpe ratio (tangency portfolio).

Parameters:

expected_returnspd.Series

Expected returns for each asset

covariance_matrixpd.DataFrame

Covariance matrix of asset returns

risk_free_ratefloat, default=0.0

Risk-free rate

Returns:

Dict[str, Union[np.ndarray, float]]

Dictionary containing: - ‘weights’: Optimal weights - ‘return’: Expected portfolio return - ‘volatility’: Portfolio volatility - ‘sharpe_ratio’: Sharpe ratio