Metadata-Version: 2.4
Name: pystatsfinance
Version: 0.1.1
Summary: Financial and quantitative statistical computing for Python
Project-URL: Homepage, https://sgcx.org/technology/pystatsfinance/
Project-URL: Documentation, https://sgcx.org/docs/pystatsfinance/
Project-URL: Repository, https://github.com/sgcx-org/pystatsfinance
Project-URL: Issues, https://github.com/sgcx-org/pystatsfinance/issues
Author-email: Hai-Shuo <contact@sgcx.org>
License-Expression: MIT
License-File: LICENSE
Keywords: finance,quantitative-finance,risk,statistics,value-at-risk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
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.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: numpy>=1.24
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Description-Content-Type: text/markdown

# PyStatsFinance

**Financial and quantitative statistical computing for Python.**

> **Status: `0.1.0` — first module shipped.** Return-series performance metrics
> are available now; more quantitative-finance methods are on the roadmap below.

PyStatsFinance is part of the open-core PyStatistics family:

| Package | Layer |
|---|---|
| [`pystatistics`](https://github.com/sgcx-org/pystatistics) | Fundamental, general statistics |
| [`pystatsbio`](https://github.com/sgcx-org/pystatsbio) | Biotech / pharma statistics |
| [`pystatsclinical`](https://github.com/sgcx-org/pystatsclinical) | Clinical-trial / clinical-research statistics |
| [`pystatsgenomic`](https://github.com/sgcx-org/pystatsgenomic) | Genomics / computational-biology statistics |
| **`pystatsfinance`** | Financial / quantitative statistics |
| [`pystatsinsurance`](https://github.com/sgcx-org/pystatsinsurance) | Actuarial / insurance statistics |

Like its siblings, it builds on `pystatistics` for the general statistical layer
and adds methods specific to quantitative finance.

## What's available now (0.1.0)

**Return-series risk and performance metrics:**

```python
from pystatsfinance import performance

returns = [0.01, -0.02, 0.03, -0.01, 0.02]

performance.sharpe_ratio(returns)              # annualized Sharpe ratio
performance.annualized_volatility(returns)     # annualized volatility
performance.max_drawdown(returns)              # worst peak-to-trough decline
```

`sharpe_ratio` annualizes `mean(excess) / std(excess)` (sample standard
deviation; per-period risk-free rate). `max_drawdown` works on returns or a
price series (`are_prices=True`) and reports the decline magnitude with its peak
and trough indices. All three fail loud on empty/non-finite input, and the
Sharpe ratio is raised — not returned as inf/nan — when volatility is zero.

## Roadmap (candidates, not commitments)

- Value-at-Risk and Conditional VaR (historical and parametric).
- Extended performance ratios (Sortino, Calmar, Information) and drawdown
  analytics.
- GARCH-family volatility and portfolio optimization.

## Installation

```bash
pip install pystatsfinance
```

## License

MIT © Hai-Shuo. Part of the [SGCX](https://sgcx.org) open-core ecosystem.
