Merge branch 'develop'

Author: JerBouma

.pre-commit-config.yaml

@@ -25,7 +25,7 @@ repos:
         entry: codespell
         args:
           [
-            "--ignore-words-list=VAI,MIS,shs,amplitud,gard,te,commun,ro,zar,vie,hel,jewl,zlot,ba,buil,coo,ether,hist,hsi,mape,navagation,operatio,pres,ser,yeld,shold,ist,varian,datas,ake,creat,statics,ket,toke,certi,buidl,ot",
+            "--ignore-words-list=VAI,nam,tha,MIS,shs,amplitud,gard,te,commun,ro,zar,vie,hel,jewl,zlot,ba,buil,coo,ether,hist,hsi,mape,navagation,operatio,pres,ser,yeld,shold,ist,varian,datas,ake,creat,statics,ket,toke,certi,buidl,ot",
             "--quiet-level=2",
             "--skip=./tests,.git,*.css,*.csv,*.html,*.ini,*.ipynb,*.js,*.json,*.lock,*.scss,*.txt,*.yaml,build/pyinstaller/*,pyproject.toml",
             "-x=.github/workflows/linting.yml"

README.md

@@ -13,7 +13,7 @@ While browsing a variety of websites, I kept finding that the same financial met
 
 For example, Microsoft's Price-to-Earnings (PE) ratio on the 6th of May, 2023 is reported to be 28.93 (Stockopedia), 32.05 (Morningstar), 32.66 (Macrotrends), 33.09 (Finance Charts), 33.66 (Y Charts), 33.67 (Wall Street Journal), 33.80 (Yahoo Finance) and 34.4 (Companies Market Cap). All of these calculations are correct, however the method applied varies leading to different results. Therefore, collecting data from multiple sources can lead to wrong interpretation of the results given that one source could be applying a different calculation method than another. And that is, if it is even freely available. Often the calculation is hidden behind a paid subscription.
 
-**This is why I designed the FinanceToolkit**, this is an open-source toolkit in which all relevant financial ratios ([130+](#available-metrics)), indicators and performance measurements are written down in the most simplistic way allowing for complete transparency of the calculation method ([proof](https://github.com/JerBouma/FinanceToolkit/blob/main/financetoolkit/ratios/valuation_model.py)). This allows you to not have to rely on metrics from other providers and, given a financial statement, allow for efficient manual calculations. This leads to one uniform method of calculation being applied that is available and understood by everyone.
+**This is why I designed the FinanceToolkit**, this is an open-source toolkit in which all relevant financial ratios ([150+](#available-metrics)), indicators and performance measurements are written down in the most simplistic way allowing for complete transparency of the calculation method ([proof](https://github.com/JerBouma/FinanceToolkit/blob/main/financetoolkit/ratios/valuation_model.py)). This allows you to not have to rely on metrics from other providers and, given a financial statement, allow for efficient manual calculations. This leads to one uniform method of calculation being applied that is available and understood by everyone.
 
 The Finance Toolkit not only supports Equities. Even for Currencies, Cryptocurrencies, ETFs, Mutual Funds, Indices, Money Markets, Commodities, Key Economic Indicators and more, the Finance Toolkit can be used to obtain historical data as well as important performance and risk measurements such as the Sharpe Ratio and Value at Risk.
 
@@ -70,10 +70,10 @@ Through the link you are able to subscribe for the free plan and also premium pl
 The Finance Toolkit features the following functionality, also see [Basic Usage](#basic-usage) to see some of these functions in action:
 
 - **Company profiles** (`get_profile`), including country, sector, ISIN and general characteristics (from FinancialModelingPrep)
-- **Company quotes** (`get_quote`), inclufding 52 week highs and lows, volume metrics and current shares outstanding (from FinancialModelingPrep)
+- **Company quotes** (`get_quote`), including 52 week highs and lows, volume metrics and current shares outstanding (from FinancialModelingPrep)
 - **Company ratings** (`get_rating`), based on key indicators like PE and DE ratios (from FinancialModelingPrep)
 - **Historical market data** (`get_historical_data`), which can be retrieved on a daily, weekly, monthly, quarterly and yearly basis. This includes OHLC, dividends, returns, cumulative returns and volatility calculations for each corresponding period. (from FinancialModelingPrep or Yahoo Finance)
-- **Treasury Rates** (`get_treasury_data`) for several months and several years over the last 3 months which allows yield curves to be constructed (from FinancialModelingPrep or Yahoo Finance)
+- **Treasury Rates** (`get_treasury_data`) for several months and several years that can serve as risk-free rate (from Yahoo Finance)
 - **Dividends Calendar** (`get_dividend_calendar`) which shows the (adjusted) dividend and the the related record, payment and declaration dates (from FinancialModelingPrep)
 - **Analyst Estimates** (`get_analyst_estimates`) that show the expected EPS and Revenue from the past and future from a range of analysts (from FinancialModelingPrep)
 - **Earnings Calendar**(`get_earnings_calendar`) which shows the exact dates earnings are released in the past and in the future including expectations (from FinancialModelingPrep)
@@ -85,6 +85,7 @@ The Finance Toolkit features the following functionality, also see [Basic Usage]
 - **Performance metrics** like Jensens Alpha (`performance.get_jensens_alpha`),  Capital Asset Pricing Model (CAPM) (`performance.get_capital_asset_pricing_model`) and (Rolling) Sharpe Ratio (`performance.get_sharpe_ratio`) that can be used to understand how each company is performing versus the benchmark and compared to each other.
 - **Risk metrics** like Value at Risk (`risk.get_value_at_risk`) and Conditional Value at Risk (`risk.get_conditional_value_at_risk`) that can be used to understand the risk profile of each company and how it compares to the benchmark.
 - **Technical indicators** like Relative Strength Index (`technicals.get_relative_strength_index`),  Exponential Moving Average (`technicals.get_exponential_moving_average`) and Bollinger Bands (`technicals.get_bollinger_bands`) that can be used to perform in-depth momentum and trend analysis. These functions allow for the calculation of technical indicators based on the historical market data.
+- **Key Economic Indicators** like Gross Domestic Product (GDP) (`economics.get_gross_domestic_product`), Consumer Price Index (CPI) (`economics.get_consumer_price_index`) and Federal Funds Rate (FED) (`economics.get_federal_reserve_rates`) that can be used to analyse over 60 different countries. Based on these indicators, it is possible to understand the economic landscape of each country and whether companies within these countries are a great fit for your portfolio.
 
 The dependencies of the package are on purpose *very slim* so that it will work well with any combination of packages and not result in conflicts.
 
@@ -127,15 +128,15 @@ value_at_risk = companies.risk.get_value_at_risk(period="weekly")
 # a Technical example
 ichimoku_cloud = companies.technicals.get_ichimoku_cloud()
 
-# a Economics example
+# an Economics example
 unemployment_rates = companies.economics.get_unemployment_rate()
 ````
 
-Generally, the functions return a DataFrame with a multi-index in which all tickers, in this case Apple and Microsoft, are presented. To keep things manageable for this README, I've selected just Apple in most cases but in essence it can be any list of tickers (no limit). The filtering is done through using `.loc['AAPL']` and `.xs('AAPL', level=1, axis=1)` based on whether it's fundamental data or historical data respectively.
+Generally, the functions return a DataFrame with a multi-index in which all tickers, in this case Apple and Microsoft, are presented. To keep things manageable for this README, I select just Apple but in essence the list of tickers can be endless as I've seen DataFrames with thousands of tickers. The filtering is done through `.loc['AAPL']` and `.xs('AAPL', level=1, axis=1)` based on whether it's fundamental data or historical data respectively.
 
 ### Obtaining Historical Data
 
-Obtain historical data on a daily, weekly, monthly or yearly basis. This includes OHLC, volumes, dividends, returns, cumulative returns and volatility calculations for each corresponding period. For example, the historical data for Apple is shown below.
+Obtain historical data on a daily, weekly, monthly or yearly basis. This includes OHLC, volumes, dividends, returns, cumulative returns and volatility calculations for each corresponding period. For example, the a portion of the historical data for Apple is shown below.
 
 | date       |    Open |    High |     Low |   Close |   Adj Close |      Volume |   Dividends |   Return |   Volatility |   Excess Return |   Excess Volatility |   Cumulative Return |
 |:-----------|--------:|--------:|--------:|--------:|------------:|------------:|------------:|---------:|-------------:|----------------:|--------------------:|--------------------:|
@@ -217,7 +218,7 @@ And below the correlations with each factor are plotted over time for both Apple
 
 ### Obtaining Risk Metrics
 
-Get the Value at Risk for each quarter. Here, the days within each quarter are considered for the Value at Risk. This makes it so that you can understand within each period what is the expected Value at Risk (VaR) which can again be any period but also based on distributions such as Historical, Gaussian, Student-t, Cornish-Fisher.
+Get the Value at Risk for each week. Here, the days within each week are considered for the Value at Risk. This makes it so that you can understand within each period what is the expected Value at Risk (VaR) which can again be any period but also based on distributions such as Historical, Gaussian, Student-t, Cornish-Fisher.
 
 |                       |    AAPL |    MSFT |   Benchmark |
 |:----------------------|--------:|--------:|------------:|
@@ -266,7 +267,7 @@ And below these Unemployment Rates are plotted over time:
 
 # Available Metrics
 
-The Finance Toolkit has the ability to calculate 100+ financial metrics. The following list shows all of the available metrics. Note that the Finance Toolkit is not limited to these ratios and indicators as it is possible to add custom ratios as well. See [this Notebook](https://www.jeroenbouma.com/projects/financetoolkit/custom-ratios) for more information.
+The Finance Toolkit has the ability to calculate 150+ financial metrics. The following list shows all of the available metrics. Note that the Finance Toolkit is not limited to these ratios and indicators as it is possible to add custom ratios as well. See [this Notebook](https://www.jeroenbouma.com/projects/financetoolkit/custom-ratios) for more information.
 
 Each ratio and indicator has a corresponding function that can be called directly for example `ratios.get_return_on_equity` or `technicals.get_relative_strength_index`.
 
@@ -281,7 +282,7 @@ The Ratios Module contains over 50+ ratios that can be used to analyse companies
 
 All of these ratios can be calculated based on (lagged) growth as well as trailing (e.g. TTM) metrics. This is embedded in all ratios as well as the financial statements themselves which means it is possible to calculate revenue growth and 12-month (TTM) Price-to-Earnings with the parameters `growth=True` and `trailing=4` respectively. Note that trailing is based on periods therefore TTM can only be calculated by setting `quarterly=True` in the Toolkit initialization.
 
-### Efficiency Ratios
+### Efficiency Ratios ⚙️
 - Asset Turnover Ratio
 - Inventory Turnover Ratio
 - Days of Inventory Outstanding
@@ -295,7 +296,7 @@ All of these ratios can be calculated based on (lagged) growth as well as traili
 - Fixed Asset Turnover
 - Operating Ratio
 
-### Liquidity Ratios
+### Liquidity Ratios 💧
 - Current Ratio
 - Quick Ratio
 - Cash Ratio
@@ -304,7 +305,7 @@ All of these ratios can be calculated based on (lagged) growth as well as traili
 - Operating Cash Flow Sales Ratio
 - Short Term Coverage Ratio
 
-### Profitability Ratios
+### Profitability Ratios 💰
 - Gross Margin
 - Operating Margin
 - Net Profit Margin
@@ -323,7 +324,7 @@ All of these ratios can be calculated based on (lagged) growth as well as traili
 - EBT to EBIT
 - EBIT to Revenue
 
-### Solvency Ratios
+### Solvency Ratios 🪨
 - Debt to Assets Ratio
 - Debt to Equity Ratio
 - Interest Coverage Ratio
@@ -335,7 +336,7 @@ All of these ratios can be calculated based on (lagged) growth as well as traili
 - CAPEX Coverage Ratio
 - CAPEX Dividend Coverage Ratio
 
-### Valuation Ratios
+### Valuation Ratios ⚖️
 - Earnings per Share (EPS)
 - Revenue per Share (RPS)
 - Price Earnings Ratio (PE)
@@ -408,14 +409,14 @@ The Risk module is meant to calculate important risk metrics such as Value at Ri
 
 The Technicals Module contains 30+ Technical Indicators that can be used to analyse companies. These ratios are divided into 4 categories which are breadth, momentum, overlap and volatility. Each indicator is calculated using the data from the Toolkit module. **Find the documentation [here](https://www.jeroenbouma.com/projects/financetoolkit/docs/technicals) which includes an explanation about the indicator, the parameters and an example.**
 
-### Breadth Indicators
+### Breadth Indicators 💨
 - McClellan Oscillator
 - Advancers/Decliners Ratio
 - On-Balance Volume (OBV)
 - Accumulation/Distribution Line (ADL)
 - Chaikin Oscillator
 
-### Momentum Indicators
+### Momentum Indicators ⏱️
 - Money Flow Index
 - Williams %R
 - Aroon Indicator
@@ -433,37 +434,80 @@ The Technicals Module contains 30+ Technical Indicators that can be used to anal
 - Relative Strength Index (RSI)
 - Balance of Power (BOP)
 
-### Overlap Indicators
+### Overlap Indicators 🌈
 - Simple Moving Average (SMA)
 - Exponential Moving Average (EMA)
 - Double Exponential Moving Average (DEMA)
 - Triple Exponential Moving Average (TRIX)
 - Triangular Moving Average (TMA)
 
-### Volatility Indicators
+### Volatility Indicators ⚠️
 - True Range (TR)
 - Average True Range (ATR)
 - Keltners Channels
 - Bollinger Bands
 
 ## Key Economic Indicators
 
-The Economics Module contains a variety of Key Economic Indicators that help in understanding the health and performance of more than 60 different countries. This module can be called directly via the Toolkit but also separately if desired. **Find the documentation [here](https://www.jeroenbouma.com/projects/financetoolkit/docs/economics) which includes an explanation about each indicator, the parameters and an example.**
+The Economics Module contains a variety of Key Economic Indicators that help in understanding the health and performance of more than 60 different countries. This module can be called directly via the Toolkit but also separately if desired through `from financetoolkit import Economics`. **Find the documentation [here](https://www.jeroenbouma.com/projects/financetoolkit/docs/economics) which includes an explanation about each indicator, the parameters and an example.**
 
+### Economy 💵
 - Gross Domestic Product (GDP) including Growth and Forecasts
 - Consumer Confidence Index (CCI)
 - Business Confidence Index (BCI)
 - Composite Leading Indicator (CLI)
 - Consumer Price Index (CPI)
 - Producer Price Index (PPI)
 - House and Rent Prices
-- Unemployment Rates
+- Share Prices
+
+### Finance 💹
 - Long Term Interest Rates (10 year)
 - Short Term Interest Rates (3 month)
+- Narrow Money (M1)
+- Broad Money (M3)
 - Purchasing Power Parity (PPP)
 - Exchange Rates
-- European Central Bank (ECB) Interest Rates
-- Federal Reserve (FED) Interest Rates
+
+### Central Banks 🏦
+- Main Refinancing Operations (ECB)
+- Marginal Lending Facility (ECB)
+- Deposit Facility (ECB)
+- Effective Federal Funds Rate (FED)
+- Overnight Bank Funding Rate (FED)
+- Tri-Party General Collateral Rate (FED)
+- Broad General Collateral Rate (FED)
+- Secured Overnight Financing Rate (FED)
+
+### Environment 💚
+- Renewable Energy as % of Total Energy
+- Environmental Tax as % of GDP
+- Greenhouse Gas Emissions
+- Crude Oil Production and Prices
+
+### Government 🏛️
+- Deficit as % of GDP
+- Revenue as % of GDP
+- Spending as % of GDP
+- Debt as % of GDP
+- Financial Wealth as % of GDP
+- Production Costs as % of GDP
+- Central Spending based on the System of National accounts (SNA)
+- Trust in Government
+
+### Jobs 🗂️
+- Unemployment Rates
+- Labour Productivity
+- Income Inequality
+
+### Society 👪
+- Population
+- Young Population
+- Working Age Population
+- Elderly Population
+- Fertility Rates
+- Old-Age Dependency Ratio
+- Poverty Rate
 
 # Contributing
 First off all, thank you for taking the time to contribute (or at least read the Contributing Guidelines)! 🚀