Risk Functions — Riskfolio-Lib 0.1 documentation

# Risk Functions

This module contains functions that calculates several risk measures that are widely used by the asset management industry and academics.

## Module Functions

`RiskFunctions.` `MAD`(X)

  Calculates the Mean Absolute Deviation (MAD) of a returns series.

  \[\text{MAD}(X) = \frac{1}{T}\sum_{t=1}^{T} | X_{t} - \mathbb{E}(X_{t}) |\]
  Parameters

    X (1d-array) – a returns series, must have Tx1 size.

  Returns

    value – MAD of a returns series.

  Return type

    float

  Raises

    ValueError – When the value cannot be calculated.

  Examples

  Examples should be written in doctest format, and should illustrate how to use the function.

      >>> print([i for i in example_generator(4)])
      [0, 1, 2, 3]

`RiskFunctions.` `SemiDeviation`(X)

  Calculates the Semi Deviation of a returns series.

  \[\text{SemiDev}(X) = \left [ \frac{1}{T-1}\sum_{t=1}^{T} (X_{t} - \mathbb{E}(X_{t}))^2 \right ]^{1/2}\]
  Parameters

    X (1d-array) – Returns series, must have Tx1 size.

  Raises

    ValueError – When the value cannot be calculated.

  Returns

    value – Semi Deviation of a returns series.

  Return type

    float

`RiskFunctions.` `VaR_Hist`(X, alpha=0.01)

  Calculates the Value at Risk (VaR) of a returns series.

  \[\text{VaR}_{\alpha}(X) = -\inf_{t \in (0,T)} \left \{ X_{t} \in \mathbb{R}: F_{X}(X_{t})>\alpha \right \}\]
  Parameters

    - X (1d-array) – Returns series, must have Tx1 size.

    - alpha (float, optional) – Significance level of VaR. The default is 0.01.

  Raises

    ValueError – When the value cannot be calculated.

  Returns

    value – VaR of a returns series.

  Return type

    float

`RiskFunctions.` `CVaR_Hist`(X, alpha=0.01)

  Calculates the Conditional Value at Risk (CVaR) of a returns series.

  \[\text{CVaR}_{\alpha}(X) = \text{VaR}_{\alpha}(X) + \frac{1}{\alpha T} \sum_{t=1}^{T} \max(-X_{t} - \text{VaR}_{\alpha}(X), 0)\]
  Parameters

    - X (1d-array) – Returns series, must have Tx1 size.

    - alpha (float, optional) – Significance level of CVaR. The default is 0.01.

  Raises

    ValueError – When the value cannot be calculated.

  Returns

    value – CVaR of a returns series.

  Return type

    float

`RiskFunctions.` `WR`(X)

  Calculates the Worst Realization (WR) or Worst Scenario of a returns series.

  \[\text{WR}(X) = \max(-X)\]
  Parameters

    X (1d-array) – Returns series, must have Tx1 size.

  Raises

    ValueError – When the value cannot be calculated.

  Returns

    value – WR of a returns series.

  Return type

    float

`RiskFunctions.` `LPM`(X, MAR=0, p=1)

  Calculates the p-th Lower Partial Moment of a returns series.

  \[\text{LPM}(X, \text{MAR}, p) = \left [ \frac{1}{T}\sum_{t=1}^{T} \max(\text{MAR} - X_{t}, 0) \right ]^{\frac{1}{p}}\]

  Where:

  \(\text{MAR}\) is the minimum acceptable return.

  Parameters

    - X (1d-array) – Returns series, must have Tx1 size.

    - MAR (float, optional) – Minimum acceptable return. The default is 0.

    - p (float, optional) – order of the \(\text{LPM}\). The default is 1.

  Raises

    ValueError – When the value cannot be calculated.

  Returns

    value – p-th Lower Partial Moment of a returns series.

  Return type

    float

`RiskFunctions.` `Entropic_RM`(X, theta=1)

  Calculates the Entropic Risk Measure (ERM) of a returns series.

  \[\text{ERM}(X) = \theta \log\left(\mathbb{E} [e^{-\frac{1}{\theta} X}]\right)\]
  Parameters

    - X (1d-array) – Returns series, must have Tx1 size.

    - theta (float, optional) – Risk aversion parameter, must be greater than zero. The default is 1.

  Raises

    ValueError – When the value cannot be calculated.

  Returns

    value – ERM of a returns series.

  Return type

    float

`RiskFunctions.` `EVaR_Hist`(X, alpha=0.01)

  Calculates the Entropic Value at Risk (EVaR) of a returns series.

  \[\text{EVaR}_{\alpha}(X) = \inf_{z>0} \left \{ z^{-1} \ln \left (\frac{M_X(z)}{\alpha} \right ) \right \}\]

  Where:

  \(M_X(z)\) is the moment generating function of X.

  Parameters

    - X (1d-array) – Returns series, must have Tx1 size.

    - alpha (float, optional) – Significance level of EVaR. The default is 0.01.

  Raises

    ValueError – When the value cannot be calculated.

  Returns

    value – EVaR of a returns series.

  Return type

    float

`RiskFunctions.` `MaxAbsDD`(X)

  Calculates the Maximum Drawdown (MDD) of a returns series using uncumpound cumulated returns.

  \[\text{MDD}(X) = \max_{j \in (0,T)} \left [\max_{t \in (0,T)} \left ( \sum_{i=0}^{t}X_{i} - \sum_{i=0}^{j}X_{i} \right ) \right ]\]
  Parameters

    X (1d-array) – Returns series, must have Tx1 size.

  Raises

    ValueError – When the value cannot be calculated.

  Returns

    value – MDD of a uncumpound cumulated returns.

  Return type

    float

`RiskFunctions.` `AvgAbsDD`(X)

  Calculates the Average Drawdown (ADD) of a returns series using uncumpound cumulated returns.

  \[\text{ADD}(X) = \frac{1}{T}\sum_{i=0}^{T}\max_{t \in (0,T)} \left ( \sum_{i=0}^{t}X_{i} - \sum_{i=0}^{j}X_{i} \right )\]
  Parameters

    X (1d-array) – Returns series, must have Tx1 size.

  Raises

    ValueError – When the value cannot be calculated.

  Returns

    value – ADD of a uncumpound cumulated returns.

  Return type

    float

`RiskFunctions.` `ConAbsDD`(X, alpha=0.01)

  Calculates the Conditional Drawdown at Risk (CDaR) of a returns series using uncumpound cumulated returns.

  \[\text{CDaR}_{\alpha}(X) = \text{DaR}_{\alpha}(X) + \frac{1}{\alpha T} \sum_{i=0}^{T} \max \left [ \max_{t \in (0,T)} \left ( \sum_{i=0}^{t}X_{i} - \sum_{i=0}^{j}X_{i} \right ) - \text{DaR}_{\alpha}(X), 0 \right ]\]

  Where:

  \(\text{DaR}_{\alpha}\) is the Drawdown at Risk of an uncumpound cumulated return series \(X\).

  Parameters

    - X (1d-array) – Returns series, must have Tx1 size..

    - alpha (float, optional) – Significance level of CDaR. The default is 0.01.

  Raises

    ValueError – When the value cannot be calculated.

  Returns

    value – CDaR of a uncumpound cumulated returns series.

  Return type

    float

`RiskFunctions.` `MaxRelDD`(X)

  Calculates the Maximum Drawdown (MDD) of a returns series using cumpound cumulated returns.

  \[\text{MDD}(X) = \max_{j \in (0,T)}\left[\max_{t \in (0,T)} \left ( \prod_{i=0}^{t}(1+X_{i}) - \prod_{i=0}^{j}(1+X_{i}) \right ) \right]\]
  Parameters

    X (1d-array) – Returns series, must have Tx1 size.

  Raises

    ValueError – When the value cannot be calculated.

  Returns

    value – MDD of a cumpound cumulated returns.

  Return type

    float

`RiskFunctions.` `AvgRelDD`(X)

  Calculates the Average Drawdown (ADD) of a returns series using cumpound acumulated returns.

  \[\text{ADD}(X) = \frac{1}{T}\sum_{i=0}^{T}\max_{t \in (0,T)} \left ( \prod_{i=0}^{t}(1+X_{i}) - \prod_{i=0}^{j}(1+X_{i}) \right )\]
  Parameters

    X (1d-array) – Returns series, must have Tx1 size.

  Raises

    ValueError – When the value cannot be calculated.

  Returns

    value – ADD of a cumpound acumulated returns.

  Return type

    float

`RiskFunctions.` `ConRelDD`(X, alpha=0.01)

  Calculates the Conditional Drawdown at Risk (CDaR) of a returns series using cumpound cumulated returns.

  \[\text{CDaR}_{\alpha}(X) = \text{DaR}_{\alpha}(X) + \frac{1}{\alpha T} \sum_{i=0}^{T} \max \left [ \max_{t \in (0,T)} \left ( \prod_{i=0}^{t}(1+X_{i}) - \prod_{i=0}^{j}(1+X_{i}) \right ) - \text{DaR}_{\alpha}(X), 0 \right ]\]

  Where:

  \(\text{DaR}_{\alpha}\) is the Drawdown at Risk of a cumpound acumulated return series \(X\).

  Parameters

    - X (1d-array) – Returns series, must have Tx1 size..

    - alpha (float, optional) – Significance level of CDaR. The default is 0.01.

  Raises

    ValueError – When the value cannot be calculated.

  Returns

    value – CDaR of a cumpound cumulated returns series.

  Return type

    float

`RiskFunctions.` `Sharpe_Risk`(w, cov=None, returns=None, rm='MV', rf=0, alpha=0.01)

  Calculate the risk measure available on the Sharpe function.

  Parameters

    - w (DataFrame or 1d-array of shape (n_assets, 1)) – Weights matrix, where n_assets is the number of assets.

    - cov (DataFrame or nd-array of shape (n_features, n_features)) – Covariance matrix, where n_features is the number of features.

    - returns (DataFrame or nd-array of shape (n_samples, n_features)) – Features matrix, where n_samples is the number of samples and n_features is the number of features.

    - rm (str, optional) –

      Risk measure used in the denominator of the ratio. The default is ‘MV’. Posible values are:

      - ’MV’: Standard Deviation.

      - ’MAD’: Mean Absolute Deviation.

      - ’MSV’: Semi Standard Deviation.

      - ’FLPM’: First Lower Partial Moment (Omega Ratio).

      - ’SLPM’: Second Lower Partial Moment (Sortino Ratio).

      - ’VaR’: Value at Risk.

      - ’CVaR’: Conditional Value at Risk.

      - ’WR’: Worst Realization (Minimax)

      - ’MDD’: Maximum Drawdown of uncompounded returns (Calmar Ratio).

      - ’ADD’: Average Drawdown of uncompounded returns.

      - ’CDaR’: Conditional Drawdown at Risk of uncompounded returns.

    - rf (float, optional) – Risk free rate. The default is 0.

    - **kwargs (dict) – Other arguments that depends on the risk measure.

  Raises

    ValueError – When the value cannot be calculated.

  Returns

    value – Risk measure of the portfolio.

  Return type

    float

`RiskFunctions.` `Sharpe`(w, mu, cov=None, returns=None, rm='MV', rf=0, alpha=0.01)

  Calculate the Risk Adjusted Return Ratio from a portfolio returns series.

  \[\text{Sharpe}(X) = \frac{\mathbb{E}(X) - r_{f}}{\phi(X)}\]

  Where:

  \(X\) is the vector of portfolio returns.

  \(r_{f}\) is the risk free rate, when the risk measure is

  \(\text{LPM}\) uses instead of \(r_{f}\) the \(\text{MAR}\).

  \(\phi(X)\) is a convex risk measure. The risk measures availabe are:

  Parameters

    - w (DataFrame or 1d-array of shape (n_assets, 1)) – Weights matrix, where n_assets is the number of assets.

    - mu (DataFrame or nd-array of shape (1, n_assets)) – Vector of expected returns, where n_assets is the number of assets.

    - cov (DataFrame or nd-array of shape (n_features, n_features)) – Covariance matrix, where n_features is the number of features.

    - returns (DataFrame or nd-array of shape (n_samples, n_features)) – Features matrix, where n_samples is the number of samples and n_features is the number of features.

    - rm (str, optional) –

      Risk measure used in the denominator of the ratio. The default is ‘MV’. Posible values are:

      - ’MV’: Standard Deviation.

      - ’MAD’: Mean Absolute Deviation.

      - ’MSV’: Semi Standard Deviation.

      - ’FLPM’: First Lower Partial Moment (Omega Ratio).

      - ’SLPM’: Second Lower Partial Moment (Sortino Ratio).

      - ’VaR’: Value at Risk.

      - ’CVaR’: Conditional Value at Risk.

      - ’WR’: Worst Realization (Minimax)

      - ’MDD’: Maximum Drawdown of uncompounded returns (Calmar Ratio).

      - ’ADD’: Average Drawdown of uncompounded returns.

      - ’CDaR’: Conditional Drawdown at Risk of uncompounded returns.

    - rf (float, optional) – Risk free rate. The default is 0.

    - **kwargs (dict) – Other arguments that depends on the risk measure.

  Raises

    ValueError – When the value cannot be calculated.

  Returns

    value – Risk adjusted return ratio of \(X\).

  Return type

    float