feat: add compounded flag to calmar() for non-compounded return streams

.claude/2026-modernization-plan.md

@@ -0,0 +1,228 @@
+# QuantStats 2026 Modernization Plan
+
+## Overview
+
+Modernize QuantStats for Python 3.10+ with modern tooling, better typing, and bug fixes.
+
+---
+
+## 1. Python Version & Packaging
+
+### Drop Python 3.8/3.9 Support
+- **Minimum**: Python 3.10 (or 3.11 for even cleaner code)
+- **Benefits**:
+  - Native `X | Y` union types (no `Union[X, Y]`)
+  - `match` statements for cleaner branching
+  - Better error messages
+  - Structural pattern matching
+  - Parenthesized context managers
+
+### Migrate setup.py → pyproject.toml
+```toml
+[project]
+name = "quantstats"
+requires-python = ">=3.10"
+dependencies = [
+    "pandas>=2.0.0",
+    "numpy>=1.24.0",
+    ...
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+```
+
+**Tasks:**
+- [x] Create `pyproject.toml` with all metadata
+- [x] Remove `setup.py`
+- [x] Update classifiers for Python 3.10-3.13 only
+- [x] Update `README.md` requirements section
+
+---
+
+## 2. Dependency Updates
+
+| Current | Proposed | Why |
+|---------|----------|-----|
+| `pandas>=1.5.0` | `pandas>=2.0.0` | Better performance, CoW |
+| `numpy>=1.21.0` | `numpy>=1.24.0` | NumPy 2.0 compat |
+| `seaborn>=0.11.0` | `seaborn>=0.13.0` | Better defaults |
+| `matplotlib>=3.3.0` | `matplotlib>=3.7.0` | Style improvements |
+| `scipy>=1.7.0` | `scipy>=1.11.0` | Performance |
+
+**Optional modern deps:**
+- `polars` (optional) for faster data processing
+- `plotly>=5.0` for interactive plots
+
+---
+
+## 3. Type Hints & Code Quality
+
+### Add Comprehensive Type Hints
+Currently minimal typing. Add throughout:
+
+```python
+# Before
+def sharpe(returns, rf=0.0, periods=252, annualize=True, smart=False):
+
+# After
+def sharpe(
+    returns: pd.Series | pd.DataFrame,
+    rf: float = 0.0,
+    periods: int = 252,
+    annualize: bool = True,
+    smart: bool = False,
+) -> float | pd.Series:
+```
+
+**Tasks:**
+- [x] Add type hints to key public functions in `stats.py` (sharpe, volatility, etc.)
+- [ ] Add type hints to remaining functions in `stats.py`
+- [ ] Add type hints to all public functions in `utils.py`
+- [x] Add type hints to plotting functions
+- [x] Add `py.typed` marker for PEP 561
+- [x] Configure `pyright` in CI (with continue-on-error)
+
+### Remove Legacy Patterns
+- [ ] Remove `_pd`, `_np` import aliases (use `pd`, `np`) - optional, low priority
+- [x] Remove `# -*- coding: UTF-8 -*-` (Python 3 default)
+- [x] Fix deprecated IPython import
+
+---
+
+## 4. Open Issues to Address
+
+### High Priority Bugs
+
+| # | Issue | Priority | Status |
+|---|-------|----------|--------|
+| 493 | Trade-analysis metrics computed from returns | HIGH | Documented (valid for returns) |
+| 491 | Error generating HTML report with benchmark Series | HIGH | FIXED |
+| 486 | reports.metrics vs reports.full inconsistency | HIGH | FIXED |
+| 485 | Benchmark Omega always same as Strategy | HIGH | FIXED |
+| 484 | make_index is incorrect | HIGH | FIXED |
+
+### Medium Priority
+
+| # | Issue | Priority | Status |
+|---|-------|----------|--------|
+| 481 | NaN in EOY Returns vs Benchmark | MEDIUM | FIXED |
+| 480 | Inconsistent metrics benchmark vs return-only | MEDIUM | FIXED |
+| 479 | EOY Returns vs Benchmark section issues | MEDIUM | FIXED |
+| 475 | Double "%" in HTML report | MEDIUM | FIXED |
+| 477 | Noisy variance warning messages | MEDIUM | FIXED |
+
+### Low Priority / Features
+
+| # | Issue | Priority | Status |
+|---|-------|----------|--------|
+| 492 | Chrome dark mode styling | LOW | FIXED |
+| 489 | Underwater plot average drawdown | LOW | FIXED |
+| 472 | Add parameters table to HTML report | FEATURE | FIXED |
+| 473 | Mass closure communication | META | Open |
+
+---
+
+## 5. Code Structure Improvements
+
+### Simplify Module Structure
+```
+quantstats/
+├── __init__.py
+├── stats.py          # Core statistics
+├── plots.py          # Plotting wrappers
+├── reports.py        # Report generation
+├── utils.py          # Utilities
+├── _montecarlo.py    # Monte Carlo (new)
+├── _plotting/
+│   ├── __init__.py
+│   ├── core.py       # Plot implementations
+│   └── wrappers.py   # Public API
+└── py.typed          # PEP 561 marker
+```
+
+### Remove Compat Layers (if dropping old Python)
+- [ ] Review `_compat.py` - may be removable
+- [ ] Review `_numpy_compat.py` - may be removable
+
+---
+
+## 6. Testing & CI
+
+### Current: 179 tests passing
+
+### Improvements:
+- [x] Add GitHub Actions workflow
+- [x] Add type checking to CI (`pyright --warnings`)
+- [x] Add coverage reporting (Codecov integration)
+- [x] Add benchmarking tests for performance regression
+
+### Test Categories:
+```yaml
+# .github/workflows/test.yml
+jobs:
+  test:
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+```
+
+---
+
+## 7. Documentation
+
+- [ ] Keep README.md (done - converted from RST)
+- [ ] Monte Carlo docs (done)
+- [ ] Generate API docs with `mkdocs` or `pdoc`
+- [ ] Add examples notebook
+
+---
+
+## 8. Implementation Order
+
+### Phase 1: Foundation (Week 1)
+1. Create `pyproject.toml`
+2. Update Python version requirement
+3. Update dependency versions
+4. Remove `setup.py`
+
+### Phase 2: Bug Fixes (Week 2-3)
+1. Fix #493 (trade metrics)
+2. Fix #491 (HTML report benchmark)
+3. Fix #486 (metrics inconsistency)
+4. Fix #485 (Omega benchmark)
+5. Fix #484 (make_index)
+
+### Phase 3: Modernization (Week 4)
+1. Add type hints to stats.py
+2. Add type hints to utils.py
+3. Remove legacy patterns
+4. Add `py.typed`
+
+### Phase 4: Polish (Week 5)
+1. Fix remaining issues
+2. Add GitHub Actions CI
+3. Update all docs
+4. Release v1.0.0
+
+---
+
+## 9. Breaking Changes
+
+Document these for CHANGELOG:
+
+1. **Python 3.10+ required** (drop 3.8, 3.9)
+2. **pandas 2.0+ required** (drop 1.x)
+3. Any function signature changes from bug fixes
+
+---
+
+## 10. New Features (Post-Modernization)
+
+Ideas for future:
+- [ ] Polars backend support
+- [ ] Async data fetching
+- [ ] Interactive Plotly reports
+- [ ] PDF export
+- [ ] Multi-strategy comparison reports

.claude/PROJECT.md

@@ -0,0 +1,102 @@
+---
+updated: 2026-01-13T14:49:14Z
+---
+
+# QuantStats
+
+## Purpose
+Portfolio analytics library for quants - calculates 50+ performance metrics (Sharpe, Sortino, max drawdown, VaR, etc.) and generates HTML tearsheet reports comparing strategies to benchmarks.
+
+## Domain Knowledge
+- Returns can be simple (arithmetic) or log returns; most metrics use simple
+- "Compounded" means geometric growth (1+r1)*(1+r2)... vs arithmetic sum
+- Drawdown = peak-to-trough decline; max drawdown is worst historical decline
+- Risk-free rate (rf) typically US Treasury; affects Sharpe/Sortino calculations
+- Trading days: 252/year (US equities), 365 for crypto
+- Monte Carlo: shuffling returns preserves distribution but varies paths
+- **Period-based metrics**: win_rate, consecutive_wins, payoff_ratio analyze return periods (not discrete trades)
+
+## Conventions
+- `_prepare_returns()` normalizes all input data before calculations
+- `_compat.py` handles pandas 1.5+/2.0+ specifics (freq aliases, timezone normalization)
+- `_numpy_compat.py` handles numpy 1.24+ specifics (product deprecation)
+- Stats functions return scalar for Series input, Series for DataFrame input
+- `extend_pandas()` adds methods directly to DataFrame/Series objects
+- Monte Carlo functions return `MonteCarloResult` dataclass with properties
+
+## Current Focus
+v0.0.78 released - 2026 modernization complete.
+Remaining open: #493 (trade-based metrics - documented as period-based, not removing)
+
+## Recently Completed (v0.0.78)
+- GitHub release v0.0.78 published
+- 12 issues closed (#472, #475, #477, #479, #480, #481, #484, #485, #486, #489, #491, #492)
+- 5 PRs closed (superseded by #494)
+- PR #495 merged: README updated with period-based metrics clarification
+- PR #483 merged: Dependabot - actions/checkout v4 → v6
+- Feature #472: Parameters table in HTML/text reports
+- Type hints: Python 3.10+ union syntax throughout
+- pyproject.toml migration (setup.py removed)
+- Monte Carlo integration (stats, plots, pandas extension)
+- pandas >=1.5.0 (supports both 1.x and 2.x)
+- 104 tests passing
+
+## Project Structure
+
+```
+quantstats/
+├── __init__.py          # Main exports (stats, plots, reports, utils)
+├── stats.py             # Statistical metrics (Sharpe, Sortino, drawdown, etc.)
+├── plots.py             # Visualization functions
+├── reports.py           # Report generation (HTML, metrics tables)
+├── utils.py             # Utility functions (data prep, download)
+├── _compat.py           # Pandas version compatibility layer
+├── _numpy_compat.py     # NumPy version compatibility layer
+├── _montecarlo.py       # Monte Carlo simulation module
+├── version.py           # Version string
+└── report.html          # HTML template for reports
+```
+
+## Development
+
+### Testing
+```bash
+pytest tests/ -v                          # Run all tests
+pytest tests/test_stats.py -v             # Run specific test file
+pytest tests/ --cov=quantstats            # Run with coverage
+```
+
+### Code Quality
+```bash
+ruff check quantstats/                    # Lint
+pyright quantstats/                       # Type check
+```
+
+## Common Tasks
+
+### Adding a New Metric
+1. Add function to `stats.py` with full type hints
+2. Add tests to `tests/test_stats.py`
+3. If shown in reports, update `reports.py` metrics dict
+
+### Updating Dependencies
+1. Edit `pyproject.toml` dependencies section
+2. Update README Requirements section to match
+3. If pandas/numpy behavior changed, update `_compat.py` or `_numpy_compat.py`
+
+### Version Bump
+1. Update `quantstats/version.py`
+2. Update `CHANGELOG.md`
+3. Create GitHub release with tag
+
+## Gotchas
+
+1. **yfinance MultiIndex**: When downloading data, use `.squeeze()` to flatten single-ticker results
+2. **Frequency aliases**: Use `_compat.get_frequency_alias()` for pandas 2.2.0+ compatibility
+3. **DataFrame vs Series**: Many stats functions handle both - check `isinstance()` and handle appropriately
+4. **NaN handling**: Use `dropna()` before calculations, especially for CVaR/VaR
+
+## Notes
+- Author: Ran Aroussi (same as yfinance)
+- Target: Python 3.10+, pandas >=1.5.0, numpy >=1.24.0
+- PR #470 still open (Dependabot setup-python) - requires workflow scope to merge

.flake8

@@ -0,0 +1,3 @@
+[flake8]
+max-line-length = 120
+exclude = .git,__pycache__,build,dist

.github/FUNDING.yml

@@ -0,0 +1,15 @@
+# These are supported funding model platforms
+
+github: # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
+patreon: # Replace with a single Patreon username
+open_collective: # Replace with a single Open Collective username
+ko_fi: # Replace with a single Ko-fi username
+tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: # Replace with a single Liberapay username
+issuehunt: # Replace with a single IssueHunt username
+otechie: # Replace with a single Otechie username
+custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']
+
+# custom: ['https://paypal.me/ranaroussi']
+patreon: ranaroussi

.github/dependabot.yml

@@ -0,0 +1,12 @@
+version: 2
+updates:
+- package-ecosystem: pip
+  directory: "/"
+  schedule:
+    interval: daily
+  open-pull-requests-limit: 10
+- package-ecosystem: "github-actions"
+  directory: "/"
+  schedule:
+    interval: daily
+  open-pull-requests-limit: 10

.github/workflows/python-publish.yml

@@ -0,0 +1,31 @@
+# This workflow will upload a Python Package using Twine when a release is created
+# For more information see: https://help.github.com/en/actions/language-and-framework-guides/using-python-with-github-actions#publishing-to-package-registries
+
+name: Upload Python Package
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  deploy:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v6
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.x'
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install setuptools wheel twine
+    - name: Build and publish
+      env:
+        TWINE_USERNAME: ${{ secrets.PYPI_USERNAME }}
+        TWINE_PASSWORD: ${{ secrets.PYPI_PASSWORD }}
+      run: |
+        python setup.py sdist bdist_wheel
+        twine upload dist/*