{"id":34046238,"url":"https://github.com/enexqnt/py-vallocation","last_synced_at":"2026-04-02T03:17:04.421Z","repository":{"id":295801748,"uuid":"990851695","full_name":"enexqnt/Py-vAllocation","owner":"enexqnt","description":"Flexible Python library for asset allocation and investor view integration","archived":false,"fork":false,"pushed_at":"2026-03-28T18:24:25.000Z","size":2549,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-28T20:31:07.420Z","etag":null,"topics":["asset-allocation","bayesian-inference","black-litterman","cvar-optimization","entropy-pooling","mean-variance-optimization","portfolio-optimization","quantitative-finance","robust-optimization","shrinkage-estimators"],"latest_commit_sha":null,"homepage":"https://py-vallocation.readthedocs.io/en/latest/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/enexqnt.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-05-26T18:32:02.000Z","updated_at":"2026-03-28T18:24:29.000Z","dependencies_parsed_at":"2025-06-27T12:22:21.576Z","dependency_job_id":"1ea6657f-274a-4bcb-b1d2-3acf3786ce01","html_url":"https://github.com/enexqnt/Py-vAllocation","commit_stats":null,"previous_names":["enexqnt/py-vallocation"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/enexqnt/Py-vAllocation","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/enexqnt%2FPy-vAllocation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/enexqnt%2FPy-vAllocation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/enexqnt%2FPy-vAllocation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/enexqnt%2FPy-vAllocation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/enexqnt","download_url":"https://codeload.github.com/enexqnt/Py-vAllocation/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/enexqnt%2FPy-vAllocation/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31295020,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T01:43:37.129Z","status":"online","status_checked_at":"2026-04-02T02:00:08.535Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asset-allocation","bayesian-inference","black-litterman","cvar-optimization","entropy-pooling","mean-variance-optimization","portfolio-optimization","quantitative-finance","robust-optimization","shrinkage-estimators"],"created_at":"2025-12-13T23:41:45.439Z","updated_at":"2026-04-02T03:17:04.413Z","avatar_url":"https://github.com/enexqnt.png","language":"Python","readme":"# Py-vAllocation\n\n[![PyPI](https://img.shields.io/pypi/v/py-vallocation.svg)](https://pypi.org/project/py-vallocation/)\n[![Python versions](https://img.shields.io/pypi/pyversions/py-vallocation.svg)](https://pypi.org/project/py-vallocation/)\n\nPy-vAllocation is a research-to-production toolkit for scenario-based portfolio\noptimisation following Meucci's Prayer framework (invariants, projection,\nrepricing, optimisation). Build mean-variance, CVaR, and relaxed risk parity\nfrontiers; incorporate Black-Litterman and entropy pooling views; apply\nshrinkage-heavy statistics; ensemble strategies; stress-test at the\nrisk-driver level; and convert weights to discrete trades.\n\n## Highlights\n\n- **Meucci Prayer pipeline** - `from_prices()` for newbies, `from_invariants()` for the full P3-P4 pipeline with any instrument (equities, bonds, options, futures, ETFs).\n- **K-to-N repricing** - `compose_repricers()` maps K risk drivers to N instruments. Multi-driver specs for options: `(\"underlying\", \"vol\"): greeks_fn`.\n- **Flexible views** - mean, volatility, variance, correlation, skewness, CVaR, quantile (VaR), and rank views via entropy pooling. Helpers: `at_least()`, `at_most()`, `between()`.\n- **Consistent optimisation surface** - switch between mean-variance, CVaR, relaxed risk parity, and robust formulations without rewriting constraints.\n- **Robust models** - Bayesian NIW posteriors, relaxed risk parity, Meucci-style probability tilts. `from_robust_posterior()` supports both MV and robust frontiers from the same wrapper.\n- **Moment estimation** - Ledoit-Wolf, James-Stein, nonlinear shrinkage, Tyler, Huber, POET, graphical lasso, EWMA via `estimate_moments`.\n- **Invariant-level stress testing** - `stress_invariants()` applies views to risk drivers, flows through repricing, and reports nominal vs stressed metrics.\n- **Production plumbing** - ensemble builders, discrete allocation, plotting, reporting. Pandas labels preserved throughout.\n\n## Design principles\n\n- **No magic, no hidden assumptions** - every step of the Prayer is explicit and user-controlled.\n- **Pandas-first inputs/outputs** with consistent labels.\n- **Scenario-based risk** by default, with clear risk labels across frontiers.\n\n## Installation\n\n```bash\npip install py-vallocation\n```\n\nFor nonlinear shrinkage and POET estimators:\n\n```bash\npip install py-vallocation[robust]\n```\n\nRequires `cvxopt\u003e=1.2.0`. If you don't have it, see the [installation guide](https://cvxopt.org/install/).\n\n## Quickstart\n\nRun the end-to-end ETF example (writes plots and CSVs to `output/`):\n\n```bash\npython examples/quickstart_etf_allocation.py\n```\n\nKey artefacts:\n\n- `output/frontiers.png` - in-sample vs out-of-sample efficient frontiers with robust overlay.\n- `output/robust_uncertainty.png`, `robust_param_impact.png`, `robust_assumptions_3d.png` - robust diagnostics.\n- `output/stacked_weights.csv`, `selected_weights.csv`, `average_weights.csv` - ensemble summaries.\n- Terminal output covering discrete trade sizing and stress results.\n\nOr use the API directly -- five factory methods for every user level:\n\n```python\nfrom pyvallocation import PortfolioWrapper\n\n# --- Newbie: from prices ---\nport = PortfolioWrapper.from_prices(price_df)\nfrontier = port.variance_frontier()\nw, ret, risk = frontier.tangency(risk_free_rate=0.04)\n\n# --- Intermediate: log-return invariants, project 1Y, reprice to simple ---\nimport numpy as np\nlog_rets = np.log(price_df / price_df.shift(1)).dropna()\nport = PortfolioWrapper.from_invariants(log_rets, horizon=52, seed=42)\nfrontier = port.cvar_frontier(alpha=0.05)\n\n# --- Institutional: mixed instruments (stocks + bonds + options) ---\nfrom pyvallocation import compose_repricers, reprice_exp, reprice_taylor\nport = PortfolioWrapper.from_invariants(\n    invariants_df,  # columns: equity log-return, yield change, vol change\n    reprice={\n        \"SPY\":  reprice_exp,\n        \"TLT\":  ([\"yield_10y\"], lambda dy: reprice_taylor(dy, delta=-17, gamma=200)),\n        \"Call\": ([\"equity_lr\", \"iv_chg\"], my_greeks_fn),\n    },\n    horizon=52, seed=42,\n)\nfrontier = port.cvar_frontier(alpha=0.05)\n\n# --- Views with helpers ---\nfrom pyvallocation import FlexibleViewsProcessor, at_least, at_most, between\nep = FlexibleViewsProcessor(\n    prior_risk_drivers=invariants_df,\n    mean_views={\"SPY\": at_least(0.05)},\n    vol_views={\"TLT\": between(0.08, 0.15)},\n    rank_mean=[\"SPY\", \"TLT\", \"GLD\"],  # E[SPY] \u003e= E[TLT] \u003e= E[GLD]\n)\n```\n\n## Examples\n\nThe `examples/` directory contains runnable scripts (see `examples/README.md`):\n\n- `quickstart_etf_allocation.py` - moments → frontiers → ensemble → trades\n- `mean_variance_frontier.py`, `cvar_allocation.py`, `robust_frontier.py` (use `variance_frontier` / `cvar_frontier`)\n- `relaxed_risk_parity_frontier.py`, `portfolio_ensembles.py`, `discrete_allocation.py`\n- `stress_and_pnl.py` - probability tilts + linear shocks + performance reports\n- `group_constraints.py` - sector/group weight constraints\n\nNotebooks under `docs/tutorials/notebooks/` cover Bayesian views, CVaR frontiers,\nderivatives repricing, stress testing, and more.\n\n## Documentation\n\n- Full documentation: https://py-vallocation.readthedocs.io\n- Tutorials live under `docs/tutorials/` and mirror the runnable scripts.\n- API reference is generated from docstrings (`docs/pyvallocation*.rst`).\n- Build locally:\n\n```bash\npip install -e .[robust]\nsphinx-build -b html docs docs/_build/html\n```\n\n## Repository layout\n\n- `pyvallocation/` - library source code.\n- `examples/` - runnable workflows (ETF quickstart, CVaR frontier, ensembles, stress testing, discrete allocation).\n- `docs/` - Sphinx site (tutorials, API reference, bibliography).\n- `tests/` - pytest suite covering numerical routines, ensembles, plotting, and discrete allocation.\n- `output/` - artefacts written by example scripts.\n\n## Requirements\n\n- Python 3.9+\n- numpy, pandas, scipy, cvxopt\n\n## References\n\n- Meucci (2005) - Risk and Asset Allocation (Prayer framework)\n- Meucci (2008) - Fully Flexible Views (entropy pooling)\n- Vorobets (2024) - Derivatives Portfolio Optimization \u0026 Exposure Stacking\n- Markowitz (1952) - Portfolio Selection\n- Black \u0026 Litterman (1992) - Global Portfolio Optimization\n- Rockafellar \u0026 Uryasev (2000) - CVaR optimization\n- Gambeta \u0026 Kwon (2020) - Relaxed Risk Parity\n- Ledoit \u0026 Wolf (2004, 2020) - Covariance shrinkage\n\nSee the [bibliography](https://py-vallocation.readthedocs.io/en/latest/bibliography.html) for the complete list.\n\n## Contributing\n\nIssues and PRs welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## License\n\nGPL-3.0-or-later — see [LICENSE](LICENSE) for the full text. Portions of the optimisation routines are adapted (with attribution) from [fortitudo-tech](https://github.com/fortitudo-tech/fortitudo.tech).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fenexqnt%2Fpy-vallocation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fenexqnt%2Fpy-vallocation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fenexqnt%2Fpy-vallocation/lists"}