# Conditional Drawdown
## Overview
`conditional-drawdown` is a Python library designed for advanced drawdown risk analysis, with a focus on the Conditional Expected Drawdown (CED) metric. Unlike traditional risk metrics like volatility or Value-at-Risk, CED accounts for the path dependency of drawdowns and provides a robust measure of extreme risk. This tool is ideal for portfolio managers, risk analysts, and quantitative researchers.
Key features include:
- **Maximum Drawdown (MDD):** Calculates the largest cumulative loss from peak to trough over a given time period.
- **Rolling Maximum Drawdown (RMD):** Computes drawdowns over sliding windows to track evolving risks.
- **Conditional Expected Drawdown (CED):** Estimates the expected maximum drawdown given that a threshold is breached, enabling deeper insights into tail risk.
- **Portfolio Risk Attribution:(WIP)** Analyze and attribute risk contributions across assets or factors using CED.
## Installation
You can install the library via pip:
```bash
pip install conditional-drawdown
```
# Usage
```python
from conditional_drawdown import CED, max_drawdown, rolling_max_drawdown
import yfinance as yf
# Download historical data
tickers = ["ES=F", "GLD"]
data = yf.download(tickers, end="2023-12-31")["Adj Close"]
# Calculate returns
returns = data.pct_change().dropna()
# Compute Conditional Expected Drawdown (CED)
es_ced = CED(returns['ES=F'].values)
gld_ced = CED(returns['GLD'].values)
print(f"S&P Futures CED: {es_ced}")
print(f"Gold ETF CED: {gld_ced}")
# Portfolio example
portfolio_returns = (returns * 0.5).sum(axis=1)
portfolio_ced = CED(portfolio_returns.values)
print(f"Portfolio CED: {portfolio_ced}")
```
# Features
- Maximum Drawdown (MDD):
Calculates the largest cumulative loss from peak to trough in a return series.
Example:
```py
max_dd = max_drawdown(returns['ES=F'].values)
print(f"Max Drawdown: {max_dd}")
```
- Rolling Maximum Drawdown (RMD):
Computes MDD over rolling windows, enabling time-sensitive risk tracking.
Example:
```py
rmd = rolling_max_drawdown(returns['GLD'].values, window=21)
print(f"Rolling Max Drawdown: {rmd}")
```
- Conditional Expected Drawdown (CED):
Focuses on the tail-end of drawdown distributions, providing a measure of extreme risk exposure.
Example:
```py
ced = CED(returns['GLD'].values, t=21, alpha=0.9)
print(f"Conditional Expected Drawdown: {ced}")
```
### Why CED?
- Path Dependency: CED captures consecutive losses, unlike volatility or Value-at-Risk.
- Convex and Linear: Useful for portfolio optimization and risk attribution.
- Tail Risk Sensitivity: Ideal for stress-testing portfolios under extreme market conditions.
## Contributing
Contributions are welcome! Please follow these steps:
- Fork the repository.
- Create a feature branch: git checkout -b feat/feature-name
- Commit your changes: git commit -m 'Add new feature'
- Push to your branch: git push origin feature-name
- Open a pull request.
### License
This project is licensed under the MIT License - see the LICENSE file for details.
## Acknowledgements
Inspired by the work of Lisa R. Goldberg and Ola Mahmoud, Drawdown: From Practice to Theory and Back Again.
arXiv:1404.7493
Raw data
{
"_id": null,
"home_page": "https://github.com/internQuant/conditional-drawdown",
"name": "conditional-drawdown",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "finance, drawdown, risk, portfolio, CED",
"author": "internQuant",
"author_email": "interQuant <cinzeis-rehang.0l@icloud.com>",
"download_url": "https://files.pythonhosted.org/packages/b1/a3/f81e07bfbc6200f2f89eeea538fbd1147b8a892395096cb53f567b7b65ae/conditional_drawdown-0.1.1.tar.gz",
"platform": null,
"description": "# Conditional Drawdown\r\n\r\n## Overview\r\n\r\n`conditional-drawdown` is a Python library designed for advanced drawdown risk analysis, with a focus on the Conditional Expected Drawdown (CED) metric. Unlike traditional risk metrics like volatility or Value-at-Risk, CED accounts for the path dependency of drawdowns and provides a robust measure of extreme risk. This tool is ideal for portfolio managers, risk analysts, and quantitative researchers.\r\n\r\nKey features include:\r\n\r\n- **Maximum Drawdown (MDD):** Calculates the largest cumulative loss from peak to trough over a given time period.\r\n- **Rolling Maximum Drawdown (RMD):** Computes drawdowns over sliding windows to track evolving risks.\r\n- **Conditional Expected Drawdown (CED):** Estimates the expected maximum drawdown given that a threshold is breached, enabling deeper insights into tail risk.\r\n- **Portfolio Risk Attribution:(WIP)** Analyze and attribute risk contributions across assets or factors using CED.\r\n\r\n## Installation\r\n\r\nYou can install the library via pip:\r\n\r\n```bash\r\npip install conditional-drawdown\r\n```\r\n# Usage\r\n\r\n```python\r\nfrom conditional_drawdown import CED, max_drawdown, rolling_max_drawdown\r\nimport yfinance as yf\r\n\r\n# Download historical data\r\ntickers = [\"ES=F\", \"GLD\"]\r\ndata = yf.download(tickers, end=\"2023-12-31\")[\"Adj Close\"]\r\n\r\n# Calculate returns\r\nreturns = data.pct_change().dropna()\r\n\r\n# Compute Conditional Expected Drawdown (CED)\r\nes_ced = CED(returns['ES=F'].values)\r\ngld_ced = CED(returns['GLD'].values)\r\n\r\nprint(f\"S&P Futures CED: {es_ced}\")\r\nprint(f\"Gold ETF CED: {gld_ced}\")\r\n\r\n# Portfolio example\r\nportfolio_returns = (returns * 0.5).sum(axis=1)\r\nportfolio_ced = CED(portfolio_returns.values)\r\nprint(f\"Portfolio CED: {portfolio_ced}\")\r\n```\r\n# Features\r\n\r\n- Maximum Drawdown (MDD):\r\nCalculates the largest cumulative loss from peak to trough in a return series.\r\nExample:\r\n```py\r\n max_dd = max_drawdown(returns['ES=F'].values)\r\n print(f\"Max Drawdown: {max_dd}\")\r\n```\r\n\r\n- Rolling Maximum Drawdown (RMD):\r\n\r\nComputes MDD over rolling windows, enabling time-sensitive risk tracking.\r\nExample:\r\n```py\r\n rmd = rolling_max_drawdown(returns['GLD'].values, window=21)\r\n print(f\"Rolling Max Drawdown: {rmd}\")\r\n```\r\n- Conditional Expected Drawdown (CED):\r\n\r\nFocuses on the tail-end of drawdown distributions, providing a measure of extreme risk exposure.\r\nExample:\r\n```py\r\n ced = CED(returns['GLD'].values, t=21, alpha=0.9)\r\n print(f\"Conditional Expected Drawdown: {ced}\")\r\n```\r\n### Why CED?\r\n\r\n- Path Dependency: CED captures consecutive losses, unlike volatility or Value-at-Risk.\r\n- Convex and Linear: Useful for portfolio optimization and risk attribution.\r\n- Tail Risk Sensitivity: Ideal for stress-testing portfolios under extreme market conditions.\r\n\r\n## Contributing\r\n\r\nContributions are welcome! Please follow these steps:\r\n\r\n- Fork the repository.\r\n- Create a feature branch: git checkout -b feat/feature-name\r\n- Commit your changes: git commit -m 'Add new feature'\r\n- Push to your branch: git push origin feature-name\r\n- Open a pull request.\r\n\r\n### License\r\n\r\nThis project is licensed under the MIT License - see the LICENSE file for details.\r\n\r\n## Acknowledgements\r\n\r\nInspired by the work of Lisa R. Goldberg and Ola Mahmoud, Drawdown: From Practice to Theory and Back Again.\r\narXiv:1404.7493\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python library for drawdown risk analysis with Conditional Expected Drawdown (CED).",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/internQuant/conditional-drawdown"
},
"split_keywords": [
"finance",
" drawdown",
" risk",
" portfolio",
" ced"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8ac9f8bf62d1765a0ec491f71f5ce7f2e5d8dc1cd02efff4e5d17345f688fb91",
"md5": "44f2cbd0f4571361423449017da4642b",
"sha256": "93d380dc3fd021562ee3e54ba218ed7bd96bb9d5e92fa70f3adcc1c0a9b4b02d"
},
"downloads": -1,
"filename": "conditional_drawdown-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "44f2cbd0f4571361423449017da4642b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 5984,
"upload_time": "2024-12-14T00:21:55",
"upload_time_iso_8601": "2024-12-14T00:21:55.105514Z",
"url": "https://files.pythonhosted.org/packages/8a/c9/f8bf62d1765a0ec491f71f5ce7f2e5d8dc1cd02efff4e5d17345f688fb91/conditional_drawdown-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b1a3f81e07bfbc6200f2f89eeea538fbd1147b8a892395096cb53f567b7b65ae",
"md5": "6605b8345a0c6cabbceebed93c4750bb",
"sha256": "6b99eb077bc428435f7db04f5c42eee2f4c210359bc1c8b5d2c5db632ab26ca3"
},
"downloads": -1,
"filename": "conditional_drawdown-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "6605b8345a0c6cabbceebed93c4750bb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 4719,
"upload_time": "2024-12-14T00:21:57",
"upload_time_iso_8601": "2024-12-14T00:21:57.424344Z",
"url": "https://files.pythonhosted.org/packages/b1/a3/f81e07bfbc6200f2f89eeea538fbd1147b8a892395096cb53f567b7b65ae/conditional_drawdown-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-14 00:21:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "internQuant",
"github_project": "conditional-drawdown",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "numpy",
"specs": []
},
{
"name": "pandas",
"specs": []
},
{
"name": "numba",
"specs": []
},
{
"name": "yfinance",
"specs": []
}
],
"lcname": "conditional-drawdown"
}
JSON
