{"id":15029684,"url":"https://github.com/fmilthaler/finquant","last_synced_at":"2025-05-15T04:04:27.232Z","repository":{"id":41448787,"uuid":"166674659","full_name":"fmilthaler/FinQuant","owner":"fmilthaler","description":"A program for financial portfolio management, analysis and optimisation.","archived":false,"fork":false,"pushed_at":"2023-11-04T08:38:31.000Z","size":1218,"stargazers_count":1541,"open_issues_count":18,"forks_count":211,"subscribers_count":33,"default_branch":"master","last_synced_at":"2025-05-15T04:04:20.905Z","etag":null,"topics":["analysis","bollinger-bands","efficient-frontier","finance","financial","financial-analysis","financial-portfolio-management","investment","investment-analysis","investment-portfolio","investment-strategies","markowitz-portfolio","monte-carlo","monte-carlo-simulation","moving-average","optimisation","portfolio-management","portfolio-optimisation","portfolio-properties","returns"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fmilthaler.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2019-01-20T15:07:19.000Z","updated_at":"2025-05-14T11:23:10.000Z","dependencies_parsed_at":"2022-08-10T02:27:06.036Z","dependency_job_id":"fb857c4e-64f8-4f2c-93a7-a64e579ebc98","html_url":"https://github.com/fmilthaler/FinQuant","commit_stats":{"total_commits":505,"total_committers":8,"mean_commits":63.125,"dds":"0.11089108910891088","last_synced_commit":"55112a9b3d5182cb291225ea530fce5b403e49e6"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fmilthaler%2FFinQuant","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fmilthaler%2FFinQuant/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fmilthaler%2FFinQuant/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fmilthaler%2FFinQuant/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fmilthaler","download_url":"https://codeload.github.com/fmilthaler/FinQuant/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254270641,"owners_count":22042858,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["analysis","bollinger-bands","efficient-frontier","finance","financial","financial-analysis","financial-portfolio-management","investment","investment-analysis","investment-portfolio","investment-strategies","markowitz-portfolio","monte-carlo","monte-carlo-simulation","moving-average","optimisation","portfolio-management","portfolio-optimisation","portfolio-properties","returns"],"created_at":"2024-09-24T20:11:21.762Z","updated_at":"2025-05-15T04:04:27.187Z","avatar_url":"https://github.com/fmilthaler.png","language":"Python","readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/fmilthaler/finquant/master/images/finquant-logo.png\" width=\"45%\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://GitHub.com/fmilthaler/FinQuant/stargazers/\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/stars/fmilthaler/FinQuant.svg?style=social\u0026label=Star\" alt='pypi'\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://pypi.org/project/FinQuant\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/pypi-v0.7.0-brightgreen.svg?style=popout\" alt='pypi'\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/fmilthaler/FinQuant\"\u003e\n    \u003cimg src=\"https://github.com/fmilthaler/finquant/actions/workflows/pytest.yml/badge.svg?branch=master\" alt='GitHub Actions'\u003e\n  \u003c/a\u003e\n  \u003ca href=\"http://finquant.readthedocs.io/\"\u003e\n    \u003cimg src=\"https://img.shields.io/readthedocs/finquant.svg?style=popout\" alt=\"docs\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://GitHub.com/fmilthaler/FinQuant/graphs/contributors/\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/contributors/fmilthaler/FinQuant.svg?style=popout\" alt=\"contributors\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/fmilthaler/FinQuant/issues\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=popout\" alt=\"contributions\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/fmilthaler/FinQuant/blob/master/LICENSE.txt\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/license/fmilthaler/FinQuant.svg?style=popout\" alt=\"license\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n# FinQuant\n*FinQuant* is a program for financial **portfolio management, analysis and optimisation**.\n\nThis README only gives a brief overview of *FinQuant*. The interested reader should refer to its [documentation](https://finquant.readthedocs.io \"FinQuant Documentation\").\n\n## Table of contents\n - [Motivation](#Motivation)\n - [Installation](#Installation)\n - [Portfolio Management](#Portfolio-Management)\n - [Returns](#Returns)\n - [Moving Averages](#Moving-Averages)\n - [Portfolio Optimisation](#Portfolio-Optimisation)\n   - [Efficient Frontier](#Efficient-Frontier)\n   - [Monte Carlo](#Monte-Carlo)\n - [Examples](#Examples)\n   - [Building a portfolio with data from web](#Building-a-portfolio-with-data-from-web)\n   - [Building a portfolio with preset data](#Building-a-portfolio-with-preset-data)\n   - [Analysis of a portfolio](#Analysis-of-a-portfolio)\n   - [Optimisation of a portfolio](#Optimisation-of-a-portfolio)\n\n## Motivation\nWithin a few lines of code, *FinQuant* can generate an object that holds your stock prices of your desired financial portfolio, analyses it, and can create plots of different kinds of *Returns*, *Moving Averages*, *Moving Average Bands with buy/sell signals*, and *Bollinger Bands*. It also allows for the optimisation based on the *Efficient Frontier* or a *Monte Carlo* run of the financial portfolio within a few lines of code. Some of the results are shown here.\n\n### Automatically generating an instance of `Portfolio`\n`finquant.portfolio.build_portfolio` is a function that eases the creating of your portfolio. See below for one of several ways of using `build_portfolio`.\n```\nfrom finquant.portfolio import build_portfolio\nnames = ['GOOG', 'AMZN', 'MCD', 'DIS']\nstart_date = '2015-01-01'\nend_date = '2017-12-31'\npf = build_portfolio(names=names,\n                    start_date=start_date,\n                    end_date=end_date)\n```\n`pf` is an instance of `finquant.portfolio.Portfolio`, which contains the prices of the stocks in your portfolio. Then...\n```\npf.data.head(3)\n```\nyields\n```\n              GOOG    AMZN        MCD        DIS\nDate\n2015-01-02  524.81  308.52  85.783317  90.586146\n2015-01-05  513.87  302.19  84.835892  89.262380\n2015-01-06  501.96  295.29  84.992263  88.788916\n```\n\n### Portfolio properties\nNicely printing out the portfolio's properties\n```\npf.properties()\n```\nDepending on the stocks within your portfolio, the output looks something like the below.\n```\n----------------------------------------------------------------------\nStocks: GOOG, AMZN, MCD, DIS\nTime window/frequency: 252\nRisk free rate: 0.005\nPortfolio expected return: 0.266\nPortfolio volatility: 0.156\nPortfolio Sharpe ratio: 1.674\n\nSkewness:\n       GOOG      AMZN      MCD       DIS\n0  0.124184  0.087516  0.58698  0.040569\n\nKurtosis:\n       GOOG      AMZN       MCD       DIS\n0 -0.751818 -0.856101 -0.602008 -0.892666\n\nInformation:\n   Allocation  Name\n0        0.25  GOOG\n1        0.25  AMZN\n2        0.25   MCD\n3        0.25   DIS\n----------------------------------------------------------------------\n```\n\n### Cumulative Return\n```\npf.comp_cumulative_returns().plot().axhline(y = 0, color = \"black\", lw = 3)\n```\nyields\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/fmilthaler/finquant/master/images/cumulative-return.svg?sanitize=true\" width=\"60%\"\u003e\n\u003c/p\u003e\n\n### Band Moving Average (Buy/Sell Signals)\n```\nfrom finquant.moving_average import compute_ma, ema\n# get stock data for disney\ndis = pf.get_stock(\"DIS\").data.copy(deep=True)\nspans = [10, 50, 100, 150, 200]\nma = compute_ma(dis, ema, spans, plot=True)\n```\nyields\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/fmilthaler/finquant/master/images/ma-band-buysell-signals.svg?sanitize=true\" width=\"60%\"\u003e\n\u003c/p\u003e\n\n### Bollinger Band\n```\nfrom finquant.moving_average import plot_bollinger_band, sma\n# get stock data for disney\ndis = pf.get_stock(\"DIS\").data.copy(deep=True)\nspan=20\nplot_bollinger_band(dis, sma, span)\n```\nyields\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/fmilthaler/finquant/master/images/bollinger-band.svg?sanitize=true\" width=\"60%\"\u003e\n\u003c/p\u003e\n\n### Portfolio Optimisation\n```\n# performs and plots results of Monte Carlo run (5000 iterations)\nopt_w, opt_res = pf.mc_optimisation(num_trials=5000)\n# plots the results of the Monte Carlo optimisation\npf.mc_plot_results()\n# plots the Efficient Frontier\npf.ef_plot_efrontier()\n# plots optimal portfolios based on Efficient Frontier\npf.ef.plot_optimal_portfolios()\n# plots individual plots of the portfolio\npf.plot_stocks()\n```\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/fmilthaler/finquant/master/images/ef-mc-overlay.svg?sanitize=true\" width=\"60%\"\u003e\n\u003c/p\u003e\n\n## Installation\nAs it is common for open-source projects, there are several ways to get hold of the code. Choose whichever suits you and your purposes best.\n\n### Dependencies\n*FinQuant* depends on the following Python packages:\n - python\u003e=3.10\n - numpy\u003e=1.15\n - pandas\u003e=2.0\n - matplotlib\u003e=3.0\n - quandl\u003e=3.4.5\n - yfinance\u003e=0.1.43\n - scipy\u003e=1.2.0\n - scikit-learn\u003e=1.3.0\n\n### From PyPI\n*FinQuant* can be obtained from PyPI\n\n```pip install FinQuant```\n\n### From GitHub\nGet the code from GitHub:\n\n```git clone https://github.com/fmilthaler/FinQuant.git```\n\nThen inside `FinQuant` run:\n\n```python setup.py install```\n\nAlternatively, if you do not wish to install *FinQuant*, you can also download/clone it as stated above, and then make sure to add it to your ``PYTHONPATH``.\n\n## Portfolio Management\nThis is the core of *FinQuant*. `finquant.portfolio.Portfolio` provides an object that holds prices of all stocks in your portfolio, and automatically computes the most common quantities for you. To make *FinQuant* an user-friendly program, that combines data analysis, visualisation and optimisation, the object provides interfaces to the main features that are provided in the modules in `./finquant/`.\n\nTo learn more about the object, please read through the [documentation](https://finquant.readthedocs.io/en/latest/ \"FinQuant Documentation\"), docstring of the module/class, and/or have a look at the examples.\n\n`finquant.portfolio.Portfolio` also provides a function `build_portfolio` which is designed to automatically generate an instance of `Portfolio` for the user's convenience. For more information on how to use `build_portfolio`, please refer to the [documentation](https://finquant.readthedocs.io/en/latest/ \"FinQuant Documentation\"), its `docstring` and/or have a look at the examples.\n\n## Returns\nDaily returns of stocks are often computed in different ways. *FinQuant* provides three different ways of computing the daily returns in `finquant.returns`:\n1. The cumulative return: \u003cimg src=\"https://raw.githubusercontent.com/fmilthaler/finquant/master/tex/738645698dc3073b4bb52a0c078ae829.svg?invert_in_darkmode\u0026sanitize=true\" align=middle width=194.52263655pt height=46.976899200000005pt/\u003e\n2. Percentage change of daily returns: \u003cimg src=\"https://raw.githubusercontent.com/fmilthaler/finquant/master/tex/27215e5f36fd0308b51ab510444edf0d.svg?invert_in_darkmode\u0026sanitize=true\" align=middle width=126.07712039999997pt height=48.84266309999997pt/\u003e\n3. Log Return: \u003cimg src=\"https://raw.githubusercontent.com/fmilthaler/finquant/master/tex/ef37c00ad58fe657a64041c3093e0640.svg?invert_in_darkmode\u0026sanitize=true\" align=middle width=208.3327686pt height=57.53473439999999pt/\u003e\n\nIn addition to those, the module provides the function `historical_mean_return(data, freq=252)`, which computes the historical mean of the daily returns over a time period `freq`.\n\n## Moving Averages\nThe module `finquant.moving_average` allows the computation and visualisation of Moving Averages of the stocks listed in the portfolio is also provided. It entails functions to compute and visualise the\n - `sma`: Simple Moving Average, and\n - `ema`: Exponential Moving Average.\n - `compute_ma`: a Band of Moving Averages (of different time windows/spans) including Buy/Sell signals\n - `plot_bollinger_band`: a Bollinger Band for\n   - `sma`,\n   - `ema`.\n\n## Portfolio Optimisation\n### Efficient Frontier\nAn implementation of the Efficient Frontier (`finquant.efficient_frontier.EfficientFrontier`) allows for the optimisation of the portfolio for\n - `minimum_volatility` Minimum Volatility,\n - `maximum_sharpe_ratio` Maximum Sharpe Ratio\n - `efficient_return` Minimum Volatility for a given expected return\n - `efficient_volatility` Maximum Sharpe Ratio for a given target volatility\n\nby performing a numerical solve to minimise/maximise an objective function.\n\nOften it is useful to visualise the *Efficient Frontier* as well as the optimal solution. This can be achieved with the following methods:\n - `plot_efrontier`: Plots the *Efficient Frontier*. If no minimum/maximum Return values are provided, the algorithm automatically chooses those limits for the *Efficient Frontier* based on the minimum/maximum Return values of all stocks within the given portfolio.\n - `plot_optimal_portfolios`: Plots markers of the portfolios with the Minimum Volatility and Maximum Sharpe Ratio.\n\nFor reasons of user-friendliness, interfaces to these functions are provided in `finquant.portfolio.Portfolio`. Please have a look at the [documentation](https://finquant.readthedocs.io \"FinQuant Documentation\").\n\n### Monte Carlo\nAlternatively a *Monte Carlo* run of `n` trials can be performed to find the optimal portfolios for\n - minimum volatility,\n - maximum Sharpe ratio\n\nThe approach branded as *Efficient Frontier* should be the preferred method for reasons of computational effort and accuracy. The latter approach is only included for the sake of completeness, and creation of beautiful plots.\n\n## Examples\nFor more information about the project and details on how to use it, please\nlook at the examples provided in `./example`.\n\n**Note**: In the below examples, `pf` refers to an instance of `finquant.portfolio.Portfolio`, the object that holds all stock prices and computes its most common quantities automatically. To make *FinQuant* a user-friendly program, that combines data analysis, visualisation and optimisation, the object also provides interfaces to the main features that are provided in the modules in `./finquant/` and are discussed throughout this README.\n\n### Building a portfolio with data from web\n`./example/Example-Build-Portfolio-from-web.py`: Shows how to use *FinQuant* to build a financial portfolio by downloading stock price data through the Python package `quandl`/`yfinance`.\n\n### Building a portfolio with preset data\n`./example/Example-Build-Portfolio-from-file.py`: Shows how to use *FinQuant* to build a financial portfolio by providing stock price data yourself, e.g. by reading data from disk/file.\n\n### Analysis of a portfolio\n`./example/Example-Analysis.py`: This example shows how to use an instance of `finquant.portfolio.Portfolio`, get the portfolio's quantities, such as\n - Expected Returns,\n - Volatility,\n - Downside Risk,\n - Value at Risk, \n - Sharpe Ratio,\n - Sortino Ratio,\n - Treynor Ratio,\n - Beta parameter,\n - R squared coefficient.\n\nIt also shows how to extract individual stocks from the given portfolio. Moreover it shows how to compute and visualise:\n - the different Returns provided by the module `finquant.returns`,\n - *Moving Averages*, a band of *Moving Averages*, and a *Bollinger Band*.\n\n### Optimisation of a portfolio\n`./example/Example-Optimisation.py`: This example focusses on the optimisation of a portfolio. To achieve this, the example shows the usage of `finquant.efficient_frontier.EfficientFrontier` for optimising the portfolio, for the\n - Minimum Volatility\n - Maximum Sharpe Ratio\n - Minimum Volatility for a given target Return\n - Maximum Sharpe Ratio for a given target Volatility.\n\nFurthermore, it is also shown how the entire *Efficient Frontier* and the optimal portfolios can be computed and visualised. If needed, it also gives an example of plotting the individual stocks of the given portfolio within the computed *Efficient Frontier*.\n\nAlso, the optimisation of a portfolio and its visualisation based on a *Monte Carlo* is shown.\n\nFinally, *FinQuant*'s visualisation methods allow for overlays, if this is desired. Thus, with only the following few lines of code, one can create an overlay of the *Monte Carlo* run, the *Efficient Frontier*, its optimised portfolios for *Minimum Volatility* and *Maximum Sharpe Ratio*, as well as the portfolio's individual stocks.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffmilthaler%2Ffinquant","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffmilthaler%2Ffinquant","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffmilthaler%2Ffinquant/lists"}