abaquant.portfolio.risk_metrics¶

Import path: abaquant.portfolio.risk_metrics

Domain: Portfolio construction, optimization, backtesting, risk metrics, and stress testing.

Purpose¶

Portfolio performance and downside-risk metrics.

When to use it¶

Use this package to transform return histories and covariance estimates into weights, then evaluate those weights out of sample and under explicit scenarios.

Public objects¶

function: portfolio_returns — Compute the weighted portfolio return series.
function: cumulative_returns — Convert periodic returns into a cumulative wealth index starting at one.
function: annualized_return — Annualize the implemented periodic return statistic.
function: annualized_volatility — Annualize sample volatility from periodic returns.
function: sharpe_ratio — Compute the annualized Sharpe ratio from periodic returns.
function: downside_deviation — Compute annualized downside deviation relative to the supplied threshold.
function: sortino_ratio — Compute the annualized Sortino ratio from periodic returns.
function: drawdown_series — Compute the drawdown series of a return stream.
function: max_drawdown — Return the most negative observed drawdown.
function: calmar_ratio — Compute annualized return divided by absolute maximum drawdown.
function: conditional_drawdown_at_risk — Compute the mean of the worst observed drawdowns at the selected tail level.
function: var_historical — Compute historical value at risk under the module sign convention.
function: cvar_historical — Compute historical conditional value at risk under the module sign convention.
function: compute_all_metrics — Compute the module portfolio-performance metric summary.

Detailed reference¶

Portfolio performance and downside-risk metrics.

Purpose¶

The module computes return, volatility, drawdown, Sharpe, Sortino, historical VaR, historical CVaR, and related summary statistics from periodic return series.

Conventions¶

Returns are simple periodic returns. The default annualization factor is 252 trading days. Historical VaR and CVaR retain the implementation sign convention in which negative values denote losses.

References

[ 1 ] Sharpe, W. F. (1966), “Mutual Fund Performance”. [ 2 ] Rockafellar, R. T., and S. Uryasev (2000), “Optimization of Conditional Value-at-Risk”.

abaquant.portfolio.risk_metrics.portfolio_returns(returns, weights)¶

Compute the weighted portfolio return series.

Parameters:

returns (pd.DataFrame) – Periodic simple return observations; rows are observation dates and columns are assets when two-dimensional.
weights (np.ndarray) – Portfolio weights, either a mapping keyed by asset or an ordered numeric vector as documented by the callable.

Returns:

One-dimensional labeled result aligned to the documented input order.

Return type:

pd.Series

Notes

This is an analytical in-sample calculation. It does not by itself model transaction costs, execution effects, taxes, or future return uncertainty.

abaquant.portfolio.risk_metrics.cumulative_returns(returns)¶

Convert periodic returns into a cumulative wealth index starting at one.

Parameters:: returns (pd.Series) – Periodic simple return observations; rows are observation dates and columns are assets when two-dimensional.
Returns:: One-dimensional labeled result aligned to the documented input order.
Return type:: pd.Series

Notes

This is an analytical in-sample calculation. It does not by itself model transaction costs, execution effects, taxes, or future return uncertainty.

abaquant.portfolio.risk_metrics.annualized_return(returns, periods=TRADING_DAYS)¶

Annualize the implemented periodic return statistic.

Parameters:

returns (pd.Series) – Periodic simple return observations; rows are observation dates and columns are assets when two-dimensional.
periods (int, default=TRADING_DAYS) – Number of discrete compounding or payment periods.

Returns:

Computed annualized return as a dimensionless decimal quantity.

Return type:

float

abaquant.portfolio.risk_metrics.annualized_volatility(returns, periods=TRADING_DAYS)¶

Annualize sample volatility from periodic returns.

Parameters:

returns (pd.Series) – Periodic simple return observations; rows are observation dates and columns are assets when two-dimensional.
periods (int, default=TRADING_DAYS) – Number of discrete compounding or payment periods.

Returns:

Computed annualized volatility as a dimensionless decimal quantity.

Return type:

float

abaquant.portfolio.risk_metrics.sharpe_ratio(returns, rf=0.0, periods=TRADING_DAYS)¶

Compute the annualized Sharpe ratio from periodic returns.

Parameters:

returns (pd.Series) – Periodic simple return observations; rows are observation dates and columns are assets when two-dimensional.
rf (float, default=0.0) – Risk-free rate under the function annualization convention.
periods (int, default=TRADING_DAYS) – Number of discrete compounding or payment periods.

Returns:

Computed sharpe ratio as a dimensionless decimal quantity.

Return type:

float

Notes

This is an analytical in-sample calculation. It does not by itself model transaction costs, execution effects, taxes, or future return uncertainty.

abaquant.portfolio.risk_metrics.downside_deviation(returns, rf_daily=0.0, periods=TRADING_DAYS)¶

Compute annualized downside deviation relative to the supplied threshold.

Parameters:

returns (pd.Series) – Periodic simple return observations; rows are observation dates and columns are assets when two-dimensional.
rf_daily (float, default=0.0) – Daily risk-free or target return threshold in decimal units.
periods (int, default=TRADING_DAYS) – Number of discrete compounding or payment periods.

Returns:

Computed downside deviation as a scalar in the units implied by the input values.

Return type:

float

abaquant.portfolio.risk_metrics.sortino_ratio(returns, rf=0.0, periods=TRADING_DAYS)¶

Compute the annualized Sortino ratio from periodic returns.

Parameters:

returns (pd.Series) – Periodic simple return observations; rows are observation dates and columns are assets when two-dimensional.
rf (float, default=0.0) – Risk-free rate under the function annualization convention.
periods (int, default=TRADING_DAYS) – Number of discrete compounding or payment periods.

Returns:

Computed sortino ratio as a dimensionless decimal quantity.

Return type:

float

abaquant.portfolio.risk_metrics.drawdown_series(returns)¶

Compute the drawdown series of a return stream.

Parameters:: returns (pd.Series) – Periodic simple return observations; rows are observation dates and columns are assets when two-dimensional.
Returns:: One-dimensional labeled result aligned to the documented input order.
Return type:: pd.Series

abaquant.portfolio.risk_metrics.max_drawdown(returns)¶

Return the most negative observed drawdown.

Parameters:: returns (pd.Series) – Periodic simple return observations; rows are observation dates and columns are assets when two-dimensional.
Returns:: Computed max drawdown as a scalar in the units implied by the input values.
Return type:: float

abaquant.portfolio.risk_metrics.calmar_ratio(returns, periods=TRADING_DAYS)¶

Compute annualized return divided by absolute maximum drawdown.

Parameters:

returns (pd.Series) – Periodic simple return observations; rows are observation dates and columns are assets when two-dimensional.
periods (int, default=TRADING_DAYS) – Number of discrete compounding or payment periods.

Returns:

Computed calmar ratio as a dimensionless decimal quantity.

Return type:

float

abaquant.portfolio.risk_metrics.conditional_drawdown_at_risk(returns, alpha=0.05)¶

Compute the mean of the worst observed drawdowns at the selected tail level.

Parameters:

returns (pd.Series) – Periodic simple return observations; rows are observation dates and columns are assets when two-dimensional.
alpha (float, default=0.05) – Model-specific alpha parameter; consult the module convention.

Returns:

Computed conditional drawdown at risk as a scalar in the units implied by the input values.

Return type:

float

Notes

This is an analytical in-sample calculation. It does not by itself model transaction costs, execution effects, taxes, or future return uncertainty.

abaquant.portfolio.risk_metrics.var_historical(returns, alpha=0.05)¶

Compute historical value at risk under the module sign convention.

Parameters:

returns (pd.Series) – Periodic simple return observations; rows are observation dates and columns are assets when two-dimensional.
alpha (float, default=0.05) – Model-specific alpha parameter; consult the module convention.

Returns:

Computed var historical as a scalar in the units implied by the input values.

Return type:

float

abaquant.portfolio.risk_metrics.cvar_historical(returns, alpha=0.05)¶

Compute historical conditional value at risk under the module sign convention.

Parameters:

returns (pd.Series) – Periodic simple return observations; rows are observation dates and columns are assets when two-dimensional.
alpha (float, default=0.05) – Model-specific alpha parameter; consult the module convention.

Returns:

Computed cvar historical as a scalar in the units implied by the input values.

Return type:

float

abaquant.portfolio.risk_metrics.compute_all_metrics(returns, rf=0.0, periods=TRADING_DAYS, alpha=0.05)¶

Compute the module portfolio-performance metric summary.

Parameters:

returns (pd.Series) – Periodic simple return observations; rows are observation dates and columns are assets when two-dimensional.
rf (float, default=0.0) – Risk-free rate under the function annualization convention.
periods (int, default=TRADING_DAYS) – Number of discrete compounding or payment periods.
alpha (float, default=0.05) – Model-specific alpha parameter; consult the module convention.

Returns:

Dictionary of named model outputs, metrics, or workflow results defined by the current public schema.

Return type:

dict[str, object]