Risk-Adjusted Performance API

Risk-adjusted performance measurement functions for portfolio analysis.

This module provides functions for measuring risk-adjusted performance metrics including Sharpe ratio, Information ratio, CAPM alpha, and multifactor models.

All functions support both Python lists and NumPy arrays as inputs.

`benchmark_alpha(returns, benchmark_returns)`

Calculate the benchmark alpha, which is the difference between portfolio return and benchmark return.

Parameters:

Name	Type	Description	Default
`returns`	`array - like`	Array of portfolio returns	required
`benchmark_returns`	`array - like`	Array of benchmark returns for the same periods	required

Returns:

Type	Description
`float`	The benchmark alpha (difference in mean returns)

Examples:

>>> benchmark_alpha([0.01, 0.02, -0.01, 0.03, 0.01], [0.005, 0.01, -0.005, 0.02, 0.005])
0.005

`calmar_ratio(returns, max_drawdown=None, annualization_factor=1.0)`

Calculate the Calmar ratio, which measures return relative to maximum drawdown.

Parameters:

Name	Type	Description	Default
`returns`	`array - like`	Array of portfolio returns	required
`max_drawdown`	`float`	Maximum drawdown as a positive decimal. If None, it will be calculated from returns.	`None`
`annualization_factor`	`float`	Factor to annualize returns	`1.0`

Returns:

Type	Description
`float`	The Calmar ratio

Examples:

>>> calmar_ratio([0.01, 0.02, -0.01, 0.03, 0.01], 0.15, 252)
0.8

`capm_alpha(returns, benchmark_returns, risk_free_rate=0.0)`

Calculate the CAPM alpha (Jensen's alpha) and related statistics.

Parameters:

Name	Type	Description	Default
`returns`	`array - like`	Array of portfolio returns	required
`benchmark_returns`	`array - like`	Array of benchmark returns for the same periods	required
`risk_free_rate`	`float or array - like`	Risk-free rate for the same period as returns	`0.0`

Returns:

Type	Description
`tuple`	(alpha, beta, r_squared, p_value, std_err) - alpha: The CAPM alpha (intercept) - beta: The CAPM beta (slope) - r_squared: The R-squared of the regression - p_value: The p-value for alpha - std_err: The standard error of alpha

Examples:

>>> capm_alpha([0.01, 0.02, -0.01, 0.03, 0.01], [0.005, 0.01, -0.005, 0.02, 0.005], 0.001)
(0.0046, 1.2, 0.9, 0.0023, 0.0012)

`information_ratio(returns, benchmark_returns, annualization_factor=1.0)`

Calculate the Information ratio, which measures active return per unit of active risk.

Parameters:

Name	Type	Description	Default
`returns`	`array - like`	Array of portfolio returns	required
`benchmark_returns`	`array - like`	Array of benchmark returns for the same periods	required
`annualization_factor`	`float`	Factor to annualize the Information ratio (e.g., 252 for daily returns to annual)	`1.0`

Returns:

Type	Description
`float`	The Information ratio

Examples:

>>> information_ratio([0.01, 0.02, -0.01, 0.03, 0.01], [0.005, 0.01, -0.005, 0.02, 0.005], 252)
2.8284271247461903

`multifactor_alpha(returns, factor_returns, risk_free_rate=0.0)`

Calculate the alpha from a multifactor model (e.g., Fama-French).

Parameters:

Name	Type	Description	Default
`returns`	`array - like`	Array of portfolio returns	required
`factor_returns`	`array - like`	2D array where each column represents returns for a factor	required
`risk_free_rate`	`float or array - like`	Risk-free rate for the same period as returns	`0.0`

Returns:

Type	Description
`tuple`	(alpha, betas, r_squared, p_value, std_err) - alpha: The multifactor alpha (intercept) - betas: Array of factor betas (coefficients) - r_squared: The R-squared of the regression - p_value: The p-value for alpha - std_err: The standard error of alpha

Examples:

>>> # Example with market, size, and value factors
>>> portfolio_returns = [0.01, 0.02, -0.01, 0.03, 0.01]
>>> factor_returns = [
...     [0.005, 0.01, -0.005, 0.02, 0.005],  # Market
...     [0.002, 0.003, -0.001, 0.004, 0.001],  # Size
...     [0.001, 0.002, -0.002, 0.003, 0.002]   # Value
... ]
>>> multifactor_alpha(portfolio_returns, factor_returns, 0.001)
(0.0032, array([0.9, 0.5, 0.3]), 0.92, 0.04, 0.0015)  # Example values

`omega_ratio(returns, threshold=0.0, annualization_factor=1.0)`

Calculate the Omega ratio, which measures the probability-weighted ratio of gains versus losses.

Parameters:

Name	Type	Description	Default
`returns`	`array - like`	Array of portfolio returns	required
`threshold`	`float`	The threshold return	`0.0`
`annualization_factor`	`float`	Factor to annualize the threshold	`1.0`

Returns:

Type	Description
`float`	The Omega ratio

Examples:

>>> omega_ratio([0.01, 0.02, -0.01, 0.03, 0.01], 0.005)
2.0

`sharpe_ratio(returns, risk_free_rate=0.0, annualization_factor=1.0)`

Calculate the Sharpe ratio, which measures excess return per unit of risk.

Parameters:

Name	Type	Description	Default
`returns`	`array - like`	Array of periodic returns	required
`risk_free_rate`	`float or array - like`	Risk-free rate for the same period as returns	`0.0`
`annualization_factor`	`float`	Factor to annualize the Sharpe ratio (e.g., 252 for daily returns to annual)	`1.0`

Returns:

Type	Description
`float or ndarray`	The Sharpe ratio If array input is provided for risk_free_rate, returns an array of Sharpe ratios

Examples:

>>> sharpe_ratio([0.01, 0.02, -0.01, 0.03, 0.01], 0.001, 252)
2.5298221281347035
>>> sharpe_ratio([0.01, 0.02, -0.01, 0.03, 0.01], [0.001, 0.002], 252)
array([2.52982213, 2.26684001])

`sortino_ratio(returns, risk_free_rate=0.0, target_return=0.0, annualization_factor=1.0)`

Calculate the Sortino ratio, which measures excess return per unit of downside risk.

Parameters:

Name	Type	Description	Default
`returns`	`array - like`	Array of portfolio returns	required
`risk_free_rate`	`float or array - like`	Risk-free rate for the same period as returns	`0.0`
`target_return`	`float`	Minimum acceptable return	`0.0`
`annualization_factor`	`float`	Factor to annualize the Sortino ratio	`1.0`

Returns:

Type	Description
`float`	The Sortino ratio

Examples:

>>> sortino_ratio([0.01, 0.02, -0.01, 0.03, 0.01], 0.001, 0.0, 252)
3.7947331922020545

`treynor_ratio(returns, benchmark_returns, risk_free_rate=0.0, annualization_factor=1.0)`

Calculate the Treynor ratio, which measures excess return per unit of systematic risk.

Parameters:

Name	Type	Description	Default
`returns`	`array - like`	Array of portfolio returns	required
`benchmark_returns`	`array - like`	Array of benchmark returns for the same periods	required
`risk_free_rate`	`float or array - like`	Risk-free rate for the same period as returns	`0.0`
`annualization_factor`	`float`	Factor to annualize the Treynor ratio	`1.0`

Returns:

Type	Description
`float`	The Treynor ratio

Examples:

>>> treynor_ratio([0.01, 0.02, -0.01, 0.03, 0.01], [0.005, 0.01, -0.005, 0.02, 0.005], 0.001, 252)
0.0378