Metadata-Version: 2.4
Name: portlab
Version: 0.2.1
Summary: Portfolio analysis toolkit — risk measurement and VaR backtesting, optimization, Monte Carlo simulation, factor models, tax-aware portfolio management, and daily risk monitoring, with a documented validation record.
Author: Ibrahim Oyeyinka
License: MIT
Project-URL: Homepage, https://github.com/Realosunboy6/portlab
Keywords: portfolio,risk,var,backtesting,optimization,finance
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: scipy>=1.10
Requires-Dist: scikit-learn>=1.3
Requires-Dist: statsmodels>=0.14
Requires-Dist: plotly>=5.15
Provides-Extra: opt
Requires-Dist: cvxpy>=1.4; extra == "opt"
Provides-Extra: data
Requires-Dist: yfinance>=0.2.40; extra == "data"
Requires-Dist: pandas-datareader>=0.10; extra == "data"
Requires-Dist: pyarrow>=14; extra == "data"
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Requires-Dist: arch; extra == "test"
Dynamic: license-file

# portlab

[![PyPI version](https://img.shields.io/pypi/v/portlab.svg)](https://pypi.org/project/portlab/)
[![Python versions](https://img.shields.io/pypi/pyversions/portlab.svg)](https://pypi.org/project/portlab/)
[![License: MIT](https://img.shields.io/pypi/l/portlab.svg)](LICENSE)

portlab is the complete portfolio analysis toolkit: risk measurement
and VaR backtesting, optimization, Monte Carlo simulation, factor
models, tax-aware portfolio management, and daily risk monitoring,
in one Python package. It is built on one principle: **a risk number
you cannot backtest is an opinion.** Every estimator is cross-checked
against an independent implementation, and the tests that pin its
conventions down ship with the package. See
[VALIDATION.md](VALIDATION.md) for the record, including the defects
that process found and fixed.

## Install

```bash
pip install portlab            # core
pip install "portlab[data]"    # + market-data loaders (yfinance etc.)
pip install "portlab[opt]"     # + cvxpy solver backend
```

Requires Python 3.10+. From source:
`pip install git+https://github.com/Realosunboy6/portlab.git`

## Quick start

```python
import pandas as pd
from portlab.risk.var import historical_var
from portlab.risk.backtest import exceptions, kupiec_pof, christoffersen_ind

rets = pd.Series(...)                       # daily simple returns
var = historical_var(rets, alpha=0.05, window=250)
exc = exceptions(rets, var)                 # nullable boolean Series
print(kupiec_pof(exc, 0.05))                # coverage test
print(christoffersen_ind(exc))              # gap-aware independence test
```

Validation anchor (SPY, through 2026-10-09): n=1,703, 86 exceptions,
Kupiec LR = 0.0089, Christoffersen LR_ind = 10.589773. SPY passes
coverage but fails independence: the exceptions bunch in Feb to Apr
2020. Cite conditional coverage, not Kupiec alone. Reproduction
code is in VALIDATION.md.

## What's inside

- **Risk:** `risk.var`, `risk.backtest`, `risk.tail`, `risk.regime`.
  VaR/ES (historical, parametric, EWMA, GARCH), Kupiec and
  Christoffersen backtests, Basel traffic light, tail diagnostics,
  regimes.
- **Optimization:** `optimize`, `mpo`. Max-Sharpe and GMV frontiers,
  min-CVaR/CDaR, Black-Litterman, HRP, risk parity, robust weights,
  multi-period optimization with transaction costs.
- **Simulation:** `montecarlo`, `scenarios`, `stress`. Seeded Monte
  Carlo with withdrawal rules, filtered historical simulation,
  historical-episode stress.
- **Factors and signals:** `factor`, `analytics`, `forecast`,
  `indicators`, `tactical`. Factor regressions, PCA, cointegration,
  ARIMA/ETS forecasts, technical indicators, tactical allocation.
- **Portfolio operations:** `taxlots`, `taxopt`, `corpactions`,
  `costs`, `attribution`, `rebalance`. Tax-lot ledger and tax-aware
  optimization, corporate actions, cost models, Brinson attribution.
- **Monitoring and output:** `risk.monitor`, `data`, `derivatives`,
  `alm`, `report`, `plots`. Fills-to-risk-report daily watcher
  (RiskLens), data loaders, options pricing, liability-driven
  investing, tear sheets and charts.

## Conventions

- Inputs are **simple returns**; VaR/ES are **positive = losses**.
  An exception is `returns < -VaR`.
- `alpha` is the *tail probability* in `portlab.risk.*` (0.05 = 95%
  VaR) and the *confidence level* in `portlab.metrics` and the CVaR
  optimizer (0.95). Each docstring states which.
- Rolling estimators are forecast-aligned: the value at day *t*
  uses only data strictly before *t*. Unscored days in
  `exceptions()` are `<NA>`, never silently passed.

## Citation

Cite via [CITATION.cff](CITATION.cff) (GitHub's "Cite this
repository" button reads the same file).

## License

MIT. See [LICENSE](LICENSE).

## Author

Ibrahim Oyeyinka, PhD candidate, Industrial & Systems Engineering,
Northern Illinois University.
