diff --git a/website/content/_index.md b/website/content/_index.md
index dfd41d486df..779616ac886 100644
--- a/website/content/_index.md
+++ b/website/content/_index.md
@@ -1,6 +1,6 @@
---
title: Getting Started
-keywords: "getting started, openbb, bots, api, beginner guide, how to use openbb, openbb keys, openbb terminal, openbb"
+keywords: "getting started, openbb, bots, api, beginner guide, how to use openbb, openbb keys, openbb terminal, openbb, terminal"
excerpt: "This page guides you how to use the OpenBB terminal, developed by OpenBB."
description: "The OpenBB Documentation provides guidance on how to use the OpenBB Terminal, a free, custom built
financial terminal that will help you make more informed decisions, faster."
@@ -8,9 +8,9 @@ geekdocCollapseSection: true
---
## Introduction
-OpenBB is a leading open source investment analysis company. We represent millions of investors who want to leverage
-state-of-the-art data science and machine learning technologies to make sense of raw unrefined data. Our mission
-is to make investment research effective, powerful and accessible to everyone.
+OpenBB is a leading open source investment research software platform for accessing and analyzing financial market data.
+We represent millions of investors who want to leverage state-of-the-art data science and machine learning technologies
+to make sense of raw unrefined data. Our mission is to make investment research effective, powerful and accessible to everyone.
**All our products are Free and Open-Source (FOSS).**
@@ -57,17 +57,22 @@ needs or even build proprietary features on top of our infrastructure - which ul
<--->
-### Importing and Exporting data
+### Why Free?
+
+We believe that the tools used to do investment research should be democratized for all for free or at a very low
+cost. We believe there is no point in re-inventing the wheel for financial theory that has been around for decades. Being
+an open source product combats exactly this issue as any type of calculation or method used is directly visible for
+anyone and can be fully customized. Of course, data comes at a price but by leveraging free-tiers from a large selection of
+APIs we can provide users with plentiful sources of information at little to no cost.
-The terminal allows for users to import their own proprietary datasets to use on our econometrics menu. In addition, users are allowed to export any type of data to any type of format whether that is raw data in Excel or an image in PNG. This is also ideal for finance content creation.
{{< /columns >}}
{{< columns >}}
-### Automatic notebook reports
+### Importing and Exporting data
-Create notebook templates (through papermill) which can be run on different tickers. This level of automation allows speeding up the development of your investment thesis and reduce human error.
+The terminal allows for users to import their own proprietary datasets to use on our econometrics menu. In addition, users are allowed to export any type of data to any type of format whether that is raw data in Excel or an image in PNG. This is also ideal for finance content creation.
<--->
@@ -95,7 +100,7 @@ or visit our contact pageOpenBB website.
+1. Go to the OpenBB website.
2. Click on the `Download` button in the Windows Installer section.
When the file is downloaded, use the following steps to run the OpenBB Terminal:
@@ -131,7 +136,7 @@ The first time this takes a bit longer to load, this can take up to a few minute
The process starts off by downloading the installer, see below for how to download the most recent release:
-1. Go to OpenBB website.
+1. Go to the OpenBB website.
2. Click on the `Download` button in the macOS Installer section.
When the DMG file is downloaded, use the following steps to run the OpenBB Terminal:
@@ -273,7 +278,7 @@ decide to change these default values by calling the argument and inputting a di
Whenever you wish to apply an optional argument, you use the related shortcode, e.g. `-s` or `--start`. Then, if there
is an additional word behind the argument (in this case there is, which is `START`) it implies the argument expects you
-to define a value. Within the documentation you can read that the format must b `YYYY-MM-DD` implying that `2010-01-01`
+to define a value. Within the documentation you can read that the format must be `YYYY-MM-DD` implying that `2010-01-01`
will be valid. If there is not an additional word behind it, it is enough to write down `load AMZN -p` (which refers to
the prepost optional argument)
diff --git a/website/content/terminal/portfolio/_index.md b/website/content/terminal/portfolio/_index.md
index 7d4c5562bc6..c8de566d335 100644
--- a/website/content/terminal/portfolio/_index.md
+++ b/website/content/terminal/portfolio/_index.md
@@ -1,12 +1,265 @@
---
+title: Introduction to Portfolio
+keywords: "portfolio, attribution, optimization, pnl, benchmark, return, volatility, metrics, broker, integration, report"
+excerpt: "The Introduction to Portfolio explains how to use the
+menu and provides a brief description of its sub-menus"
geekdocCollapseSection: true
---
+The Portfolio menu, and its sub-menus, are dedicated to properly explaining and optimizing your own portfolio. With
+features to load your own orderbook (transactions) it is possible to compare your results to that of a benchmark.
+For example, you are able to load both your portfolio and a benchmark (load and bench),
+then have the option to look into the performance compared to the benchmark asking the question "_What if I invested all my money in the benchmark instead?_" (perf)
+as well as see a wide variety of statistics and metrics (rsharpe, distr, var and metric).
+Next to that, with these findings you can apply optimization techniques to your portfolio through the Portfolio Optimization menu.
-A **Portfolio** is a collection of financial assets such as stocks, bonds, commodities, cash, and cash equivalents, as well as closed-end funds and exchange-traded funds (ETFs). Stocks, bonds, and cash are commonly seen to be the foundation of a portfolio. This isn't always the case, but it doesn't have to be. Real estate, art, and private investments are all examples of assets that can be found in a portfolio.
+## How to use
-**Portfolio Attribution** is a complex way for evaluating a portfolio or fund manager's performance. It aims to objectively assess components of an active fund manager's investment selections and decisions—and to discover sources of excess returns, especially when contrasted to an index or other benchmark. It is also known as "return attribution" or "performance attribution." This can be a useful technique for portfolio managers and investment firms to evaluate strategies. For investors, attribution analysis is a useful tool for evaluating fund or money manager performance.
+The Portfolio menu is called upon by typing `portfolio` which opens the following menu:
-**Portfolio optimization** is usually referred to as Modern Portfolio Theory (MPT). This is started by the famous paper from Harry Markowitz that shows “that the performance of an individual stock is not as important as the performance and composition of an investor's entire portfolio.” The biggest criticism of the MPT that if two portfolios have equal variance and equal return, the MPT is indifferent what portfolio you choose even though the downside risk of one portfolio could be much higher than that of the other, meaning significant losses can be sporadic (but large) for one portfolio while frequent (but of smaller size) for the other while having the same variance. This is where Post-Modern Portfolio Theory (PMPT) makes proper adjustments for. The main difference: “The differences in risk, as defined by the standard deviation of returns, between the PMPT and the MPT is the key factor in portfolio construction. The MPT assumes symmetrical risk whereas the PMPT assumes asymmetrical risk. Downside risk is measured by target semi-deviation, termed downside deviation, and captures what investors fear most: having negative returns.” This goes deeper into the concept of Utility and Risk Aversion where the perceived negative impact of -10% is larger than the perceived positive impact of 10%.
+
-**Available commands**
-{{< toc-tree >}}
\ No newline at end of file
+The first step in using this menu is loading a portfolio with load.
+Here, we provide an example titled "Public_Equity_Orderbook.xlsx" which can be loaded in. This file also serves as a template when you wish to fill in your own orders. This results
+in the following:
+
+```
+2022 Jul 19, 10:03 (🦋) /portfolio/ $ load Public_Equity_Orderbook.xlsx
+ Preprocessing orderbook: ..........
+ Loading price data: .
+ Calculating returns: .
+
+
+Portfolio: Public_Equity_Orderbook.xlsx
+Risk Free Rate: 0
+```
+
+Note that the Excel sheet requires the following columns:
+- **Date** - The date the trade occurred
+- **Name** - The name of the security
+- **Type** - The type of the security. Use Cash/Stock/Crypto/ETF as appropriate
+- **Price** - The price the security was added or removed at, on a per-unit basis
+- **Quantity** - How much of the security in question was added or removed
+- **Side** - Whether you bought or sold. Use Buy/Deposit/1 to add to the portfolio or Sell/Withdrawal/0 to remove from the portfolio
+a search criteria, country, sector or industry.
+
+Furthermore, the chosen Excel sheet above also has additional columns but these are _optional_. The OpenBB Terminal
+can figure out by itself what industry, sector, country and region belongs to the loaded in equity. You can see this in
+action by loading in the "Public_Equity_Orderbook_No_Categorization.xlsx" Excel sheet.
+
+With the show command
+we can show how the data has been loaded in:
+
+````
+2022 Jul 19, 10:03 (🦋) /portfolio/ $ show
+
+┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━┳━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━┳━━━━━━━━━━┓
+┃ Date ┃ Ticker ┃ Type ┃ Sector ┃ Industry ┃ Country ┃ Region ┃ Price ┃ Quantity ┃ Fees ┃ Premium ┃ Investment ┃ Side ┃ Currency ┃
+┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━╇━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━╇━━━━━━━━━━┩
+│ 2010-05-03 00:00:00 │ GOOGL │ STOCK │ Communication Services │ Internet Content & Information │ United States │ North America │ 13.27 │ 2 │ 5 │ 6 │ 21.54 │ 1 │ USD │
+├─────────────────────┼────────┼───────┼────────────────────────┼─────────────────────────────────────┼───────────────┼───────────────┼────────┼──────────┼──────┼─────────┼────────────┼──────┼──────────┤
+│ 2010-07-06 00:00:00 │ AMZN │ STOCK │ Technology │ Internet Retail │ United States │ North America │ 5.50 │ 5 │ 3 │ 3 │ 24.50 │ 1 │ USD │
+├─────────────────────┼────────┼───────┼────────────────────────┼─────────────────────────────────────┼───────────────┼───────────────┼────────┼──────────┼──────┼─────────┼────────────┼──────┼──────────┤
+│ 2011-08-06 00:00:00 │ AAPL │ STOCK │ Technology │ Consumer Electronics │ United States │ North America │ 12.61 │ 3 │ 1 │ 0 │ 36.83 │ 1 │ USD │
+├─────────────────────┼────────┼───────┼────────────────────────┼─────────────────────────────────────┼───────────────┼───────────────┼────────┼──────────┼──────┼─────────┼────────────┼──────┼──────────┤
+│ 2011-12-12 00:00:00 │ APTV │ STOCK │ Consumer Cyclical │ Auto Parts │ United States │ North America │ 18.02 │ 5 │ 0 │ 2 │ 90.10 │ 1 │ USD │
+├─────────────────────┼────────┼───────┼────────────────────────┼─────────────────────────────────────┼───────────────┼───────────────┼────────┼──────────┼──────┼─────────┼────────────┼──────┼──────────┤
+│ 2012-02-03 00:00:00 │ ASML │ STOCK │ Technology │ Semiconductor Equipment & Materials │ Netherlands │ Europe │ 59.17 │ 7 │ 0 │ 4 │ 414.19 │ 1 │ USD │
+├─────────────────────┼────────┼───────┼────────────────────────┼─────────────────────────────────────┼───────────────┼───────────────┼────────┼──────────┼──────┼─────────┼────────────┼──────┼──────────┤
+│ 2012-05-04 00:00:00 │ NKE │ STOCK │ Consumer Cyclical │ Footwear & Accessories │ Germany │ Europe │ 27.95 │ 3 │ 0 │ 0 │ 83.85 │ 1 │ USD │
+├─────────────────────┼────────┼───────┼────────────────────────┼─────────────────────────────────────┼───────────────┼───────────────┼────────┼──────────┼──────┼─────────┼────────────┼──────┼──────────┤
+│ 2012-08-04 00:00:00 │ TSM │ STOCK │ Technology │ Semiconductors │ Taiwan │ Asia │ 14.24 │ 50 │ 0 │ 0 │ 712.00 │ 1 │ USD │
+├─────────────────────┼────────┼───────┼────────────────────────┼─────────────────────────────────────┼───────────────┼───────────────┼────────┼──────────┼──────┼─────────┼────────────┼──────┼──────────┤
+│ 2012-10-12 00:00:00 │ DGX │ STOCK │ Healthcare │ Diagnostics & Research │ United States │ North America │ 63.39 │ 6 │ 10 │ 0 │ 370.34 │ 1 │ USD │
+├─────────────────────┼────────┼───────┼────────────────────────┼─────────────────────────────────────┼───────────────┼───────────────┼────────┼──────────┼──────┼─────────┼────────────┼──────┼──────────┤
+
+````
+
+After loading in the portfolio, it is time to select a benchmark. This is important to be able to properly compare if your decision to trade actively or deviate from an index have actually been fruitful.
+For example, let's load in the SPDR S&P 500 ETF Trust (SPY) with the bench
+command as follows:
+
+```
+2022 Jul 19, 10:14 (🦋) /portfolio/ $ bench SPDR S&P 500 ETF Trust (SPY)
+
+Benchmark: SPDR S&P 500 ETF Trust (SPY) (SPY)
+
+2022 Jul 19, 10:16 (🦋) /portfolio/ $
+```
+
+Note that the `bench` command has a large selection of products you can choose from. Instead of taking the index directly, an ETF product is used to represent something
+that you could have actually invested in. By using the `DOWN` (⌄) arrow and pressing `ENTER` (⏎) you can select a different benchmark.
+
+
+
+After defining both the portfolio and the benchmark, a lot more options become available:
+
+
+
+For example, with `perf`, we can see how the portfolio performed compared to if you invested the same amount of money into the
+benchmark instead. This reflects the capabilities of you, as an investor, to outperform a passive strategy.
+
+```
+2022 Jul 20, 08:26 (🦋) /portfolio/ $ perf
+
+ Portfolio vs. Benchmark - Totals in period: all
+┏━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━┓
+┃ ┃ Portfolio ┃ Benchmark ┃ Difference ┃
+┡━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━┩
+│ Total Investment │ 47665.95 │ 47665.95 │ - │
+├──────────────────┼───────────┼───────────┼────────────┤
+│ Total Value │ 59961.16 │ 60038.37 │ -77.21 │
+├──────────────────┼───────────┼───────────┼────────────┤
+│ Total % Return │ 25.79% │ 25.96% │ -0.16% │
+├──────────────────┼───────────┼───────────┼────────────┤
+│ Total Abs Return │ 12295.21 │ 12372.42 │ -77.21 │
+└──────────────────┴───────────┴───────────┴────────────┘
+```
+
+Compliment this by showing the volatility of the portfolio for different time periods with `metric` as follows:
+
+```
+2022 Jul 20, 08:27 (🦋) /portfolio/ $ metric volatility
+
+Volatility for Portfolio and Benchmark
+┏━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┓
+┃ ┃ Portfolio [%] ┃ Benchmark [%] ┃
+┡━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━┩
+│ mtd │ 8.185 │ 4.210 │
+├─────┼───────────────┼───────────────┤
+│ qtd │ 8.185 │ 4.210 │
+├─────┼───────────────┼───────────────┤
+│ ytd │ 31.497 │ 18.220 │
+├─────┼───────────────┼───────────────┤
+│ 3m │ 22.340 │ 14.436 │
+├─────┼───────────────┼───────────────┤
+│ 6m │ 30.879 │ 17.912 │
+├─────┼───────────────┼───────────────┤
+│ 1y │ 35.816 │ 20.128 │
+├─────┼───────────────┼───────────────┤
+│ 3y │ 54.981 │ 41.174 │
+├─────┼───────────────┼───────────────┤
+│ 5y │ 64.408 │ 45.647 │
+├─────┼───────────────┼───────────────┤
+│ 10y │ 78.014 │ 53.200 │
+├─────┼───────────────┼───────────────┤
+│ all │ 93.956 │ 60.885 │
+└─────┴───────────────┴───────────────┘
+```
+
+## Examples
+
+Instead of loading the "Public_Equity_Orderbook.xlsx" file, we now load in
+"Public_Equity_Orderbook_No_Categorization.xlsx" which does not include categorization of the stocks
+by industry, sector, country and region. Therefore, we let the OpenBB Terminal figure this out. This
+takes a bit longer to load.
+
+```
+2022 Jul 21, 04:43 (🦋) /portfolio/ $ load Public_Equity_Orderbook_No_Categorization.xlsx
+ Preprocessing orderbook: ..........
+ Loading company data: ..........
+ Loading price data: .
+ Calculating returns: .
+
+
+Portfolio: Public_Equity_Orderbook_No_Categorization.xlsx
+Risk Free Rate: 0
+```
+
+Then we load in a benchmark again with `bench` where we select the Vanguard Total Stock Market ETF (VTI).
+
+```
+2022 Jul 21, 04:44 (🦋) /portfolio/ $ bench Vanguard Total Stock Market ETF (VTI)
+
+Benchmark: Vanguard Total Stock Market ETF (VTI) (VTI)
+```
+
+Then, we can show our performance compared to that of the benchmark with `perf` as well as show the rolling
+beta with `rbeta`.
+
+```
+2022 Jul 21, 04:45 (🦋) /portfolio/ $ perf
+
+ Portfolio vs. Benchmark - Totals in period: all
+┏━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━┓
+┃ ┃ Portfolio ┃ Benchmark ┃ Difference ┃
+┡━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━┩
+│ Total Investment │ 47665.95 │ 47665.95 │ - │
+├──────────────────┼───────────┼───────────┼────────────┤
+│ Total Value │ 60815.22 │ 58901.42 │ 1913.79 │
+├──────────────────┼───────────┼───────────┼────────────┤
+│ Total % Return │ 27.59% │ 23.57% │ 4.02% │
+├──────────────────┼───────────┼───────────┼────────────┤
+│ Total Abs Return │ 13149.27 │ 11235.47 │ 1913.79 │
+└──────────────────┴───────────┴───────────┴────────────┘
+
+2022 Jul 21, 04:46 (🦋) /portfolio/ $ rbeta
+```
+
+
+
+This helps in understanding that, even though you achieved a superior return, this also came at a
+greater risk compared to that of the benchmark. With the available functionalities you can further look
+into these results, e.g. by looking at the `summary` statistics:
+
+```
+2022 Jul 21, 04:46 (🦋) /portfolio/ $ summary
+
+Summary of Portfolio vs Benchmark for all period
+┏━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━┓
+┃ ┃ Portfolio ┃ Benchmark ┃
+┡━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━┩
+│ Volatility │ 0.02 │ 0.01 │
+├───────────────────┼───────────┼───────────┤
+│ Skew │ -1.65 │ -0.58 │
+├───────────────────┼───────────┼───────────┤
+│ Kurtosis │ 32.89 │ 12.12 │
+├───────────────────┼───────────┼───────────┤
+│ Maximum Drawdowwn │ -0.42 │ -0.35 │
+├───────────────────┼───────────┼───────────┤
+│ Sharpe ratio │ 0.04 │ 0.05 │
+├───────────────────┼───────────┼───────────┤
+│ Sortino ratio │ 0.05 │ 0.06 │
+├───────────────────┼───────────┼───────────┤
+│ R2 Score │ 0.50 │ 0.50 │
+└───────────────────┴───────────┴───────────┘
+```
+
+As well as look into how the allocations differ per sector and country with `alloc`. This shows that
+there is a clear difference in how the benchmark and the portfolio are constructed implying the Total Market ETF might
+not be the best benchmark for your portfolio.
+
+```
+2022 Jul 21, 04:52 (🦋) /portfolio/ $ alloc sectors
+
+
+ Portfolio vs. Benchmark - Top 4 Sectors Allocation
+┏━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━┓
+┃ Sectors ┃ Portfolio ┃ Benchmark ┃ Difference ┃
+┡━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━┩
+│ Technology │ 58.26% │ 23.37% │ 34.89% │
+├────────────────────────┼───────────┼───────────┼────────────┤
+│ Consumer Cyclical │ 30.26% │ 10.30% │ 19.96% │
+├────────────────────────┼───────────┼───────────┼────────────┤
+│ Healthcare │ 9.98% │ 14.85% │ -4.87% │
+├────────────────────────┼───────────┼───────────┼────────────┤
+│ Communication Services │ 1.50% │ 7.98% │ -6.48% │
+└────────────────────────┴───────────┴───────────┴────────────┘
+
+2022 Jul 21, 04:52 (🦋) /portfolio/ $ alloc countries
+
+
+ Portfolio vs. Benchmark - Top 5 Countries Allocation
+┏━━━━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━┓
+┃ Countries ┃ Portfolio ┃ Benchmark ┃ Difference ┃
+┡━━━━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━┩
+│ Netherlands │ 38.06% │ - │ 38.06% │
+├───────────────┼───────────┼───────────┼────────────┤
+│ United States │ 29.69% │ 99.10% │ -69.41% │
+├───────────────┼───────────┼───────────┼────────────┤
+│ Taiwan │ 14.66% │ 0.01% │ 14.65% │
+├───────────────┼───────────┼───────────┼────────────┤
+│ China │ 11.11% │ - │ 11.11% │
+├───────────────┼───────────┼───────────┼────────────┤
+│ Ireland │ 6.47% │ - │ 6.47% │
+└───────────────┴───────────┴───────────┴────────────┘
+```