Risk Measurement API

Risk measurement functions for portfolio analysis.

This module provides various risk metrics used in portfolio management and financial analysis.

`capm_beta(portfolio_returns, market_returns)`

Calculate the CAPM beta of a portfolio.

Parameters:

Name	Type	Description	Default
`portfolio_returns`	`array - like`	Array or list of portfolio returns	required
`market_returns`	`array - like`	Array or list of market returns	required

Returns:

Type	Description
`float`	CAPM beta

Notes

Beta measures the sensitivity of portfolio returns to market returns. It is the covariance of portfolio returns and market returns divided by the variance of market returns.

`conditional_value_at_risk(returns, confidence_level=0.95, method='historical', current_value=1.0)`

Calculate the Conditional Value-at-Risk (CVaR) of a portfolio.

Parameters:

Name	Type	Description	Default
`returns`	`array - like`	Array or list of returns	required
`confidence_level`	`float`	Confidence level for CVaR calculation (e.g., 0.95 for 95% confidence)	`0.95`
`method`	`str`	Method for calculating CVaR ('historical' or 'parametric')	`'historical'`
`current_value`	`float`	Current value of the portfolio	`1.0`

Returns:

Type	Description
`float`	Conditional Value-at-Risk (CVaR) as a positive number representing the potential loss

Notes

CVaR, also known as Expected Shortfall, measures the expected loss given that the loss exceeds the VaR threshold. It provides a more conservative risk measure than VaR.

`correlation_matrix(returns_matrix)`

Calculate the correlation matrix of returns.

Parameters:

Name	Type	Description	Default
`returns_matrix`	`array - like`	Matrix of returns where each column represents an asset	required

Returns:

Type	Description
`ndarray`	Correlation matrix

Notes

The correlation matrix measures the strength of the relationship between returns of different assets, normalized to be between -1 and 1.

`covariance_matrix(returns_matrix)`

Calculate the covariance matrix of returns.

Parameters:

Name	Type	Description	Default
`returns_matrix`	`array - like`	Matrix of returns where each column represents an asset	required

Returns:

Type	Description
`ndarray`	Covariance matrix

Notes

The covariance matrix measures how returns of different assets move together.

`drawdown(returns, as_list=False)`

Calculate the drawdown, maximum drawdown, and drawdown duration of returns.

Parameters:

Name	Type	Description	Default
`returns`	`array - like`	Array or list of returns	required
`as_list`	`bool`	If True, returns the drawdowns as a list instead of numpy array	`False`

Returns:

Type	Description
`Tuple containing:`	Array or list of drawdowns Maximum drawdown (as a positive number) Start index of maximum drawdown End index of maximum drawdown

Notes

Drawdown measures the decline from a historical peak in cumulative returns.

`semi_standard_deviation(returns, threshold=0.0, annualize=False, periods_per_year=252)`

Calculate the semi-standard deviation of returns below a threshold.

Parameters:

Name	Type	Description	Default
`returns`	`array - like`	Array or list of returns	required
`threshold`	`float`	Threshold below which to calculate semi-standard deviation	`0.0`
`annualize`	`bool`	Whether to annualize the semi-standard deviation	`False`
`periods_per_year`	`int`	Number of periods in a year (252 for daily returns, 12 for monthly, 4 for quarterly)	`252`

Returns:

Type	Description
`float`	Semi-standard deviation of returns

Notes

Semi-standard deviation only considers returns below the threshold (typically 0), making it a measure of downside risk.

`standard_deviation(returns, annualize=False, periods_per_year=252)`

Calculate the standard deviation of returns.

Parameters:

Name	Type	Description	Default
`returns`	`array - like`	Array or list of returns	required
`annualize`	`bool`	Whether to annualize the standard deviation	`False`
`periods_per_year`	`int`	Number of periods in a year (252 for daily returns, 12 for monthly, 4 for quarterly)	`252`

Returns:

Type	Description
`float`	Standard deviation of returns

Notes

Standard deviation measures the dispersion of returns around the mean. It is the square root of the variance.

`tracking_error(portfolio_returns, benchmark_returns, annualize=False, periods_per_year=252)`

Calculate the tracking error between portfolio returns and benchmark returns.

Parameters:

Name	Type	Description	Default
`portfolio_returns`	`array - like`	Array or list of portfolio returns	required
`benchmark_returns`	`array - like`	Array or list of benchmark returns	required
`annualize`	`bool`	Whether to annualize the tracking error	`False`
`periods_per_year`	`int`	Number of periods in a year (252 for daily returns, 12 for monthly, 4 for quarterly)	`252`

Returns:

Type	Description
`float`	Tracking error

Notes

Tracking error measures how closely a portfolio follows its benchmark. It is the standard deviation of the difference between portfolio and benchmark returns.

`value_at_risk(returns, confidence_level=0.95, method='historical', parametric_mean=None, parametric_std=None, current_value=1.0)`

Calculate the Value-at-Risk (VaR) of a portfolio.

Parameters:

Name	Type	Description	Default
`returns`	`array - like`	Array or list of returns	required
`confidence_level`	`float`	Confidence level for VaR calculation (e.g., 0.95 for 95% confidence)	`0.95`
`method`	`str`	Method for calculating VaR ('historical', 'parametric', or 'monte_carlo')	`'historical'`
`parametric_mean`	`float`	Mean for parametric VaR calculation (if None, calculated from returns)	`None`
`parametric_std`	`float`	Standard deviation for parametric VaR calculation (if None, calculated from returns)	`None`
`current_value`	`float`	Current value of the portfolio	`1.0`

Returns:

Type	Description
`float`	Value-at-Risk (VaR) as a positive number representing the potential loss

Notes

VaR measures the potential loss in value of a portfolio over a defined period for a given confidence interval.