{"repo":"ranaroussi/quantstats","free":true,"listed":false,"github":"https://github.com/ranaroussi/quantstats","clone":"git clone https://github.com/ranaroussi/quantstats.git","description":"Portfolio analytics for quants, written in Python","language":"Python","stars":7554,"topics":["algo-trading","algorithmic-trading","algotrading","finance","plotting","python","quant","quantitative-analysis","quantitative-finance","quantitative-trading","visualization"],"license":"Apache-2.0","category":"quant_analysis","readme_excerpt":"[![Python version](https://img.shields.io/badge/python-3.10+-blue.svg?style=flat)](https://pypi.python.org/pypi/quantstats)\n[![PyPi version](https://img.shields.io/pypi/v/quantstats.svg?maxAge=60)](https://pypi.python.org/pypi/quantstats)\n[![PyPi status](https://img.shields.io/pypi/status/quantstats.svg?maxAge=60)](https://pypi.python.org/pypi/quantstats)\n[![PyPi downloads](https://img.shields.io/pypi/dm/quantstats.svg?maxAge=2592000&label=installs&color=%2327B1FF)](https://pypi.python.org/pypi/quantstats)\n[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/ranaroussi/quantstats)\n[![Star this repo](https://img.shields.io/github/stars/ranaroussi/quantstats.svg?style=social&label=Star&maxAge=60)](https://github.com/ranaroussi/quantstats)\n[![Follow me on twitter](https://img.shields.io/twitter/follow/aroussi.svg?style=social&label=Follow&maxAge=60)](https://twitter.com/aroussi)\n\n# QuantStats: Portfolio analytics for quants\n\n**QuantStats** Python library that performs portfolio profiling, allowing quants and portfolio managers to understand their performance better by providing them with in-depth analytics and risk metrics.\n\n[Changelog »](./CHANGELOG.md)\n\n### QuantStats is comprised of 3 main modules:\n\n1. `quantstats.stats` - for calculating various performance metrics, like Sharpe ratio, Win rate, Volatility, etc.\n2. `quantstats.plots` - for visualizing performance, drawdowns, rolling statistics, monthly returns, etc.\n3. `quantstats.reports` - for generating metrics reports, batch plotting, and creating tear sheets that can be saved as an HTML file.\n\n---\n\n### **NEW! Monte Carlo Simulations**\n\n<img src=\"https://raw.githubusercontent.com/ranaroussi/pandas-montecarlo/master/demo.png\" alt=\"Monte Carlo Simulation\" width=\"640\">\n\nRun probabilistic risk analysis with built-in Monte Carlo simulations:\n\n```python\nmc = qs.stats.montecarlo(returns, sims=1000, bust=-0.20, goal=0.50)\nprint(f\"Bust probability: {mc.bust_probability:.1%}\")\nprint(f\"Goal probability: {mc.goal_probability:.1%}\")\nmc.plot()\n```\n\n[Full Monte Carlo documentation »](./docs/montecarlo.md)\n\n---\n\n## Quick Start\n\n```python\n%matplotlib inline\nimport quantstats as qs\n\n# extend pandas functionality with metrics, etc.\nqs.extend_pandas()\n\n# fetch the daily returns for a stock\nstock = qs.utils.download_returns('META')\n\n# show sharpe ratio\nqs.stats.sharpe(stock)\n\n# or using extend_pandas() :)\nstock.sharpe()\n```\n\nOutput:\n\n```\n0.7604779884378278\n```\n\n### Visualize stock performance\n\n```python\nqs.plots.snapshot(stock, title='Facebook Performance', show=True)\n\n# can also be called via:\n# stock.plot_snapshot(title='Facebook Performance', show=True)\n```\n\nOutput:\n\n![Snapshot plot](https://github.com/ranaroussi/quantstats/blob/main/docs/snapshot.webp?raw=true)\n\n### Creating a report\n\nYou can create 7 different report tearsheets:\n\n1. `qs.reports.metrics(mode='basic|full\", ...)` - shows basic/full metrics\n2. `qs.reports.plots(mode='basic|full\", ...)` - shows basic/full plots\n3. `qs.reports.basic(...)` - shows basic metrics and plots\n4. `qs.reports.full(...)` - shows full metrics and plots\n5. `qs.reports.html(...)` - generates a complete report as html\n\nLet's create an html tearsheet:\n\n```python\n# benchmark can be a pandas Series or ticker\nqs.reports.html(stock, \"SPY\")\n```\n\nOutput will generate something like this:\n\n![HTML tearsheet](https://github.com/ranaroussi/quantstats/blob/main/docs/report.webp?raw=true)\n\n[View original html file](https://rawcdn.githack.com/ranaroussi/quantstats/main/docs/tearsheet.html)\n\n### Available methods\n\nTo view a complete list of available methods, run:\n\n```python\n[f for f in dir(qs.stats) if f[0] != '_']\n```\n\n```python\n['avg_loss',\n 'avg_return',\n 'avg_win',\n 'best',\n 'cagr',\n 'calmar',\n 'common_sense_ratio',\n 'comp',\n 'compare',\n 'compsum',\n 'conditional_value_at_risk',\n 'consecutive_losses',\n 'consecutive_wins',\n 'cpc_index',\n 'cvar',\n 'drawdown_details',\n 'expected_return',\n 'expected_shortfall',\n 'exposure',\n 'gain_to_pain_ratio',\n 'geometric_mean',\n 'ghpr',\n 'greeks',\n 'implied_volatility',\n 'information_ratio',\n 'kelly_criterion',\n 'kurtosis',\n 'max_drawdown',\n 'monthly_returns',\n 'montecarlo',\n 'montecarlo_cagr',\n 'montecarlo_drawdown',\n 'montecarlo_sharpe',\n 'outlier_loss_ratio',\n 'outlier_win_ratio',\n 'outliers',\n 'payoff_ratio',\n 'profit_factor',\n 'profit_ratio',\n 'r2',\n 'r_squared',\n 'rar',\n 'recovery_factor',\n 'remove_outliers',\n 'risk_of_ruin',\n 'risk_return_ratio',\n 'rolling_greeks',\n 'ror',\n 'sharpe',\n 'skew',\n 'sortino',\n 'adjusted_sortino',\n 'tail_ratio',\n 'to_drawdown_series',\n 'ulcer_index',\n 'ulcer_performance_index',\n 'upi',\n 'value_at_risk',\n 'var',\n 'volatility',\n 'win_loss_ratio',\n 'win_rate',\n 'worst']\n```\n\n```python\n[f for f in dir(qs.plots) if f[0] != '_']\n```\n\n```python\n['daily_returns',\n 'distribution',\n 'drawdown',\n 'drawdowns_periods',\n 'earnings',\n 'histogram',\n 'log_returns',\n 'monthly_heatmap',\n 'montecarlo',\n 'montecarlo_distribution',\n 'returns',\n 'rolling_beta',\n 'rolling_sharpe',\n 'rolling_sortino',\n 'rolling_volatility',\n 'snapshot',\n 'yearly_returns']\n```\n\n**\\*\\*\\* Full documentation coming soon \\*\\*\\***\n\n### Important: Period-Based vs Trade-Based Metrics\n\nQuantStats analyzes **return series** (daily, weekly, monthly returns), not discrete trade data. This means:\n\n- **Win Rate** = percentage of periods with positive returns\n- **Consecutive Wins/Losses** = consecutive positive/negative return periods\n- **Payoff Ratio** = average winning period return / average losing period return\n- **Profit Factor** = sum of positive returns / sum of negative returns\n\nThese metrics are **valid and useful** for:\n- Systematic/algorithmic strategies with regular rebalancing\n- Analyzing return-series behavior over time\n- Comparing strategies on a period-by-period basis\n\nFor **discretionary traders** with multi-day trades, these period-based metrics may differ from trade-level statistics. A single 5-day trade might span 3 positive days and 2 negative days - QuantStats would count these as 3 \"wins\" and 2 \"losses\" at the daily level.\n\nThis is consistent with how all return-based analytics work (Sharpe ratio, Sortino ratio, drawdown analysis, etc.) - they operate on return periods, not discrete trade entries/exits.\n\n---\n\nIn the meantime, you can get insights as to optional parameters for each method, by using Python's `help` method:\n\n```python\nhelp(qs.stats.conditional_value_at_risk)\n```\n\n```\nHelp on function conditional_value_at_risk in module quantstats.stats:\n\nconditional_value_at_risk(returns, sigma=1, confidence=0.99)\n    calculates the conditional daily value-at-risk (aka expected shortfall)\n    quantifies the amount of tail risk an investment\n```\n\n## Installation\n\nInstall using `pip`:\n\n```bash\n$ pip install quantstats --upgrade --no-cache-dir\n```\n\nInstall using `conda`:\n\n```bash\n$ conda install -c ranaroussi quantstats\n```\n\n## Requirements\n\n* [Python](https://www.python.org) >= 3.10\n* [pandas](https://github.com/pydata/pandas) >= 1.5.0\n* [numpy](http://www.numpy.org) >= 1.24.0\n* [scipy](https://www.scipy.org) >= 1.11.0\n* [matplotlib](https://matplotlib.org) >= 3.7.0\n* [seaborn](https://seaborn.pydata.org) >= 0.13.0\n* [tabulate](https://bitbucket.org/astanin/python-tabulate) >= 0.9.0\n* [yfinance](https://github.com/ranaroussi/yfinance) >= 0.2.40\n* [plotly](https://plot.ly/) >= 5.0.0 (optional, for using `plots.to_plotly()`)\n\n## Questions?\n\nThis is a new library... If you find a bug, please\n[open an issue](https://github.com/ranaroussi/quantstats/issues).\n\nIf you'd like to contribute, a great place to look is the\n[issues marked with help-wanted](https://github.com/ranaroussi/quantstats/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22).\n\n## Known Issues\n\nFor some reason, I couldn't find a way to tell seaborn not to return the\nmonthly returns heatmap when instructed to save - so even if you save the plot (by passing `savefig={...}`) it will still show the plot.\n\n## Legal Stuff\n\n**QuantStats** is distributed under the **Apache Software License**. See the [LICENSE.txt](./LICENSE.txt) file in the release for details.\n\n## P.S.\n\nPlease drop me a note with any feedback you have.\n\n**Ran Aroussi**\n","default_branch":"main","files":44,"tree":[".claude/2026-modernization-plan.md",".claude/PROJECT.md",".deepsource.toml",".flake8",".github/FUNDING.yml",".github/dependabot.yml",".github/workflows/python-publish.yml",".github/workflows/test-compatibility.yml",".gitignore",".travis.yml","CHANGELOG.md","CONTRIBUTORS.txt","LICENSE.txt","MANIFEST.in","README.md","docs/montecarlo.md","docs/report.webp","docs/snapshot.webp","docs/tearsheet.html","pyproject.toml","quantstats/__init__.py","quantstats/_compat.py","quantstats/_montecarlo.py","quantstats/_numpy_compat.py","quantstats/_plotting/__init__.py","quantstats/_plotting/core.py","quantstats/_plotting/wrappers.py","quantstats/plots.py","quantstats/py.typed","quantstats/report.html","quantstats/reports.py","quantstats/stats.py","quantstats/utils.py","quantstats/version.py","requirements.txt","setup.cfg","tests/__init__.py","tests/test_compat.py","tests/test_extend_pandas.py","tests/test_montecarlo.py","tests/test_plots.py","tests/test_reports.py","tests/test_stats.py","tests/test_utils.py"],"storefront":"/r/ranaroussi","claimed":false,"request_supported":{"post":"https://gitbuyer.com/r/ranaroussi/quantstats/request-supported","requests":0},"note":"indexed from public GitHub; nothing is for sale on this page. Clone it from GitHub. Paid listings live at /search."}