From bbfdf67b5a9336a93afc2286ea040a9ae0827368 Mon Sep 17 00:00:00 2001 From: Theodore Aptekarev Date: Mon, 15 May 2023 18:55:42 +0200 Subject: [PATCH] Retire old doc pages (#5012) Co-authored-by: James Maslek --- TROUBLESHOOT.md | 147 ----------- openbb_terminal/SDK_README.md | 448 ---------------------------------- openbb_terminal/reporting.md | 71 ------ 3 files changed, 666 deletions(-) delete mode 100644 TROUBLESHOOT.md delete mode 100644 openbb_terminal/SDK_README.md delete mode 100644 openbb_terminal/reporting.md diff --git a/TROUBLESHOOT.md b/TROUBLESHOOT.md deleted file mode 100644 index 43e21b65721..00000000000 --- a/TROUBLESHOOT.md +++ /dev/null @@ -1,147 +0,0 @@ -# TROUBLESHOOT - - - -If you are visiting this page it means that you're having issues installing. We deeply apologize for that. - -Since the start of the project we've come across different types of issues experienced by the users. This page tries to combine issues, and their solutions. -This will allow to give the best install experience to everyone regardless of any programming skills. - -
    -
  1. - Standard Install Troubles - -
    2. -
  2. - ModuleNotFoundError Trouble - -
    3. -
  3. - Machine Learning Troubles -
    4. -
  4. - -
    5. -
- -## Standard Install Troubles - -### Microsoft Visual C++ - -If you are on Windows and your terminal has too many red error lines, it is likely that -this is the issue. Go to this page and install the 2019 Build Tools (not the latest): - - -### Wheel - -`conda install -c conda-forge wheel` or `pip install wheel` - -### Poetry - -If you get errors about .whl files not existing (usually on Windows) you have to reinitialize the following folder. -Just removing the 'artifacts' folder could also be enough: - -| Platform | Location | -| -------- | ------------------------------- | -| Linux | "~/.cache/pypoetry" | -| Mac | "~/Library/Caches/pypoetry" | -| Windows | "%localappdata%/pypoetry/cache" | - -When you try to add a package to Poetry it is possible that it causes a similar issue. Here you can remove the -'artifacts' folder again to reinitialize Poetry. - -If you run into trouble with Poetry, and the advice above did not help, your best bet is to try - -1. `poetry update --lock` - -2. `conda deactivate` -> `conda activate obb`, then try again - -3. Track down the offensive package and purge it from your anaconda `` folder, then try again - (removing through conda can sometimes leave locks behind) - - | Platform | Location | - | --------- | -------------------------------------------- | - | Linux/Mac | "~/anaconda3/envs" or "~/opt/anaconda3/envs" | - | Windows | "%userprofile%/anaconda3/envs" | - -4. Completely nuke your conda environment folder and make a new environment from scratch - -5. Reboot your computer and try again - -6. Submit a ticket on GitHub - -#### JSONDecodeError during `poetry install` - -Sometimes poetry can throw a `JSONDecodeError` on random packages while running `poetry install`. -This can be observed on macOS 10.14+ running python 3.8+. -This is because of the use of an experimental installer that can be switched off to avoid the mentioned error. -Run - -```bash -poetry config experimental.new-installer false -``` - -as advised [here](https://github.com/python-poetry/poetry/issues/4210) and it should fix the installation process. - -## ModuleNotFoundError Trouble - -### General - -In the case when you run into an error of the form `ModuleNotFoundError: No module named '_______'` before you start installing these modules that have not been found please check that you have most followed the recommended installation instructions. -These errors often can occur when you have not activated the virtual environment where you have installed the terminal, or you have not used the `poetry install` command to install the dependencies. - -In case you wish to proceed with an alternative way to install the terminal feel free to install the missing packages via pip. For example if you get the error that `yfinance` is not found, you would run `pip install yfinance` - -### Machine Learning Troubles - -If you run into issues installing or `Cannot convert a symbolic Tensor...` at runtime, try this: - -```bash -poetry install -poetry install -E forecast -``` - -_Commands that may help you in case of an error:_ - -- `python -m pip install --upgrade pip` -- `poetry update --lock` -- `poetry install` - -### CRLF versus LF - -When trying to commit code changes, pylint will prevent you from doing so if your line break settings are set to -CRLF (default for Windows). -This is because the entire package uses LF (default for Linux/Mac), and it is therefore -important that you change this setting to LF _before_ you make any changes to the code. - -It is possible that CRLF automatically turns back on, you can correct this with: - -```bash -git config --global core.autocrlf false -``` - -In case you already made coding adjustments, you have to reset your cache, and the changes you made to the code with -the following: - -```bash -git rm --cached -r . -git reset --hard -``` - -### Unable to run openbb from VS Code integrated terminal - -Occurs when vscode terminal python version/path is different from the terminal version. - -To fix it add this to vscode JSON settings ([ref](https://stackoverflow.com/questions/54582361/vscode-terminal-shows-incorrect-python-version-and-path-launching-terminal-from)): - -```bash - "terminal.integrated.inheritEnv": false, -``` diff --git a/openbb_terminal/SDK_README.md b/openbb_terminal/SDK_README.md deleted file mode 100644 index dc4617963f1..00000000000 --- a/openbb_terminal/SDK_README.md +++ /dev/null @@ -1,448 +0,0 @@ - -# OpenBB SDK - -OpenBB SDK gives you direct and programmatic access to all capabilities of the OpenBB Terminal. -You will have the necessary building blocks to create your own financial tools and applications, -whether that be a visualization dashboard or a custom report in a Jupyter Notebook. - -With OpenBB SDK, you can access normalized financial data from dozens of data providers, -without having to develop your own integrations from scratch. -On top of financial data feeds, OpenBB SDK also provides you with a toolbox to perform financial analysis -on a variety of asset classes, including stocks, crypto, ETFs, funds; the economy as well as your portfolios. - -OpenBB SDK is created and maintained by OpenBB team together with the contributions from hundreds of community members. -This gives us an unrivaled speed of development and the ability to maintain stable integrations with numerous third-party data providers. -Developing and maintaining an full-blown investment research infrastructure from the ground up takes a lot of time and effort. -However, it does not have to be. Take advantage of OpenBB SDK with its out-of-the-box data connectors and financial analysis toolkit. -So that you can focus on designing and building your financial reports and applications. - -## SDK structure - -The OpenBB SDK consists of the core package and extension toolkits. -The core package includes all necessary functionality for you to start researching or developing your dashboards and applications. - -The toolkits that you can extend the OpenBB SDK with are: - -- Portfolio Optimization Toolkit. -- Forecasting Toolkit. - -## System and Platform Requirements - -The SDK core package is expected to work in any officially supported python version 3.8 and higher (3.9 recommended). - -Optimization and Forecasting toolkits installation requires specific settings on computers powered by Apple Silicon, the newer Windows ARM and Raspberry Pi. - -### Minimal and Recommended System Requirements - -- A computer with a modern CPU (released in the past 5 years) -- At least 8GB of RAM, 16+ recommended -- SSD drive with at least 12GB of storage space available -- Internet connection - -**NOTES ON THE INTERNET CONNECTIVITY:** Installation of the SDK with all the toolkits would require downloading around 4GB of data. -Querying data does not require a lot of bandwidth but you will certainly have a more pleasant experience if you will be on a fast internet line. 4G networks provide a good enough experience so if you're traveling your personal hot-spot will do. -While it's technically possible to use a subset of the functionality in off-line mode, you will not be able to use any data that is queried from the APIs of data providers and services. - -### Platform Specific Requirements - -**Portfolio Optimization Toolkit and Forecasting Toolkit on Apple Silicon:** To install the Forecasting toolkit on M1/M2 macs you need to use the x86_64 version of conda and install certain dependencies from conda-forge. Follow the [instructions in this section](https://github.com/OpenBB-finance/OpenBBTerminal/blob/main/openbb_terminal/README.md#1-install-miniconda) - -**Base Linux Docker containers:** To have the package work in base linux containers like python's `slim-buster` you need to install a C anc C++ compiler that's not bundled with the distribution. -Run `sudo apt update && sudo apt install gcc cmake` - -## Installation - -We provide a simple installation method in order to utilize the OpenBB SDK. You must first create an environment, -which allows you to isolate the SDK from the rest of your system. It is our recommendation that you utilize a -`conda` environment because there are optional features, such as `forecast`, that utilize libraries that are -specifically sourced from `conda-forge`. Due to this, if you do not use a conda environment, you will not be -able to use some of these features. As such, the installation steps will be written under the assumption that -you are using conda. - -### Steps - -#### 1. **Install [Miniconda](https://docs.conda.io/en/latest/miniconda.html)** - -Download the `x86_64` Miniconda for your respective system and follow along with it's installation instructions. The Miniconda architecture MUST be `x86_64` in order to use the forecasting toolkit. Follow the [instructions in this section](https://github.com/OpenBB-finance/OpenBBTerminal/blob/main/openbb_terminal/README.md#1-install-miniconda) - -#### 2. **Create the virtual environment** - -```bash -conda create -n obb python=3.9.6 -y -``` - -#### 3. **Activate the virtual environment** - -```bash -conda activate obb -``` - -#### 4. **Install OpenBB SDK Core package** - -```bash -pip install openbb -``` - -#### 5. **(Optional) Install the Toolkits** - -##### 5.1 **If you would like to use the Portfolio Optimization features** - -On Apple Silicon Macs (M1/M2) install dependency from conda-forge - -```bash -conda install -c conda-forge cvxpy=1.2.2 -y -``` - -And install the Portfolio Optimization Toolkit - -```bash -pip install "openbb[optimization]" -``` - -##### 5.2 **If you would like ML Forecasting features** - -On Apple Silicon Macs (M1/M2) install dependency from conda-forge - -```bash -conda install -c conda-forge lightgbm=3.3.3 -y -``` - -And install the Forecasting Toolkit - -```bash -pip install "openbb[forecast]" -``` - -##### 5.2 **If you would like to use both Portfolio Optimization and ML forecast features** - -On Apple Silicon Macs (M1/M2) install dependencies from conda-forge - -```bash -conda install -c conda-forge lightgbm=3.3.3 cvxpy=1.2.2 -y -``` - -And install the Both Toolkits - -```bash -pip install "openbbterminal[all]" -``` - -Congratulations! You have successfully installed `openbbterminal` on an environment and are now able to begin using it. However, it is important to note that if you close out of your CLI you must re-activate your environment in order begin using it again. - -## Setup - -### 1. Import OpenBB SDK - -First off, import OpenBB SDK into your python script or Jupyter Notebook with: - -```python -from openbb_terminal.sdk import openbb -``` - -This imports all Terminal commands at once. To see all the available commands, you can press `tab` in jupyter notebook. -Another approach is to check out [OpenBB SDK Documentation](https://openbb-finance.github.io/OpenBBTerminal/sdk/), where you can explore its capabilities - -### 2. Customize chart style - -With OpenBB SDK, you can customize your chart style. You can switch between `dark` and `light` easily using this block of code: - -```python -from openbb_terminal.sdk import TerminalStyle -theme = TerminalStyle("light", "light", "light") -``` - -Screenshot 2022-10-03 at 23 56 52 - -OR - -```python -from openbb_terminal.sdk import TerminalStyle -theme = TerminalStyle("dark", "dark", "dark") -``` - -Screenshot 2022-10-03 at 23 46 33 - -### 3. Access Documentation - -Each and every command of OpenBB SDK has detailed documentation about input parameters and returned outputs. You can access them in multiple ways: - -**Approach 1: Press `shift + tab`.** -This will work out of the box if you're using Jupyter Notebook. In case your IDE is VSCode, you will need to install the [Jupyter PowerToys -extension](https://marketplace.visualstudio.com/items?itemName=ms-toolsai.vscode-jupyter-powertoys). - -Screenshot 2022-10-03 at 23 31 55 - -**Approach 2: Type `help(command)`.** - -You can also type `help(command)`, see example below, to see the command' docstring. - -Screenshot 2022-10-03 at 23 33 05 - -**Approach 3: Use OpenBB SDK Documentation page.** - -Finally, if you prefer to check documentation on a web browser, [OpenBB SDK Documentation](https://openbb-finance.github.io/OpenBBTerminal/sdk/) will be your best friend. You can browse available commands and search for any specific one that you need. - -Screenshot 2022-10-03 at 18 41 48 - -### 4. Set API Keys - -You can set your external API keys through OpenBB SDK. - -- Single API setup - -```python -openbb.keys.fmp(key="example") - -openbb.keys.reddit( - client_id="example", - client_secret="example", - password="example", - username="example", - useragent="example") -``` - -![image](https://user-images.githubusercontent.com/79287829/194706829-dd720d06-9027-4da6-87f1-f39c7d2d725a.png) - -- API key setup with persistence: `persist=True` means that your key will be saved and can be reused after, otherwise it will be lost when you restart the kernel. - -```python -openbb.keys.fmp(key="example", persist=True) -``` - -![image](https://user-images.githubusercontent.com/79287829/194706848-80302ffa-6e75-4f7a-b8ce-788e083977d4.png) - -- Set multiple keys from dictionary - -```python -d = { - "fed": { - "key":"XXXXX" - }, - "binance": { - "key":"YYYYY", - "secret":"example" - }, -} - -openbb.keys.set_keys(d) -``` - -![image](https://user-images.githubusercontent.com/79287829/194706945-f1e6937f-74e2-4702-9e5e-c463287d61bd.png) - -- Get info about API setup arguments - -```python -openbb.keys.get_keys_info() -``` - -![image](https://user-images.githubusercontent.com/79287829/194706740-54bcc166-460a-410d-b34d-23e8b6c7aaf2.png) - -- Get your defined keys - -```python -openbb.keys.mykeys() -openbb.keys.mykeys(show=True) -``` - -![image](https://user-images.githubusercontent.com/79287829/194706907-239fe861-31c3-47c0-9051-7717cd026b76.png) - -## Usage - -Now, let's explore what OpenBB SDK can do. At a high level, you can break down OpenBB SDK's functionalities into two main buckets: (1) Data layer and (2) Toolbox layer. - -### 1. Data Layer - -### **Getting financial data from multiple data sources using one single SDK** - -OpenBB SDK provides you access to normalized financial data from dozens of data sources, without having to built your own integration or relying on multiple third-party packages. Let's explore how we can do that. - -First, you will need to load in the desired ticker. If it's not on the top of your mind, make use of our search functionality. - -```python -openbb.stocks.search("apple") -``` - -Screenshot 2022-10-04 at 00 00 14 - -We want to load `Apple Inc.` listed on US exchange, so our ticker should be `AAPL`. If you want to load `Apple Inc.` from Brazilian exchange, you should load in `AAPL34.SA`. - -```python -df = openbb.stocks.load("AAPL") -``` - -What's extremely powerful about OpenBB SDK is that you can specify the data source. Depending on the asset class, we have a list of available data sources and it's only getting bigger with contributions from our open-source community. - -```python -## From YahooFinance -df_yf = openbb.stocks.load("AAPL", source='YahooFinance') - -## From AlphaVantage -df_av = openbb.stocks.load("AAPL", source='AlphaVantage') - -## From Polygon -df_pol = openbb.stocks.load("AAPL", source='Polygon') -``` - -### **Easy option to switch between obtaining underlying data and charts** - -Depending on your needs, you can get the outputs in form of data (e.g. `pandas dataframe`) or charts. If the latter is what you want, simple add `chart=True` as the last parameter. - -### 1. Getting underlying data - -```python -openbb.economy.index(indices = ['sp500', 'nyse_ny', 'russell1000'], start_date = '2010-01-01') -``` - -Screenshot 2022-10-04 at 00 02 23 - -You might be wondering how to find all the available indices. This type of information should be available in the docstring. Let's give it a try. - -Screenshot 2022-10-04 at 13 20 58 - -As mentioned in the docstring, you can access it with the following helper function. - -```python -openbb.economy.available_indices() -``` - -Screenshot 2022-10-04 at 00 16 36 - -### 2. Getting charts - -```python -openbb.economy.index(indices = ['sp500', 'nyse_ny', 'russell1000'], start_date = '2010-01-01', chart=True) -``` - -Screenshot 2022-10-04 at 00 03 57 - -## 2. Toolbox Layer - -In addition to financial data, you can also get access to a robust and powerful toolbox to perform analysis on different asset classes and on your portfolio. - -Imagine that you would like to leverage existing financial calculations from OpenBB and apply them on your own data. This can be done easily - OpenBB SDK's commands usually accept a `dataframe` as an input. Here you can load it your data, either via a `csv`, `excel` file, or connecting directly with an `API` or a `database`. The possibilities are endless. - -Let's go through an example to see how we can do it in a few simple steps. Here we shall see how to use `portfolio optimization` functionalities from OpenBB SDK. - -### Step 1. Loading order book - -Here we will use an example orderbook for illustration purposes. You can choose to upload your own orderbook instead. - -```python -order_book_path = "portfolio/allocation/60_40_Portfolio.xlsx" -tickers, categories = openbb.portfolio.po.load(excel_file = order_book_path) -``` - -### Step 2. Optimizing portfolio - -We provide multiple portfolio optimization techniques. You can utilize basic mean-variance techniques, such as optimizing for the maximum Sharpe ratio, or minimum variance, as well as advanced optimization techniques including Hierarchical Risk Parity and Nested Clustered Optimization. - -```python -## Max Sharpe optimization -weights_max_sharpe, data_returns_max_sharpe = openbb.portfolio.po.maxsharpe(tickers) - -print("Max Sharpe") -weights_max_sharpe -``` - -Screenshot 2022-10-04 at 13 23 45 - -```python -## Minimum risk optimization -weights_min_risk, data_returns_min_risk = openbb.portfolio.po.minrisk(tickers) - -print("Min Risk") -weights_min_risk -``` - -Screenshot 2022-10-04 at 13 24 45 - -```python -## Hierarchical Risk Parity optimization - -weights_hrp, data_returns_hrp = openbb.portfolio.po.hrp(tickers) - -print("Hierarchical Risk Parity") -weights_hrp -``` - -Screenshot 2022-10-04 at 13 34 39 - -After having obtained the asset allocation outcomes, you can plot a correlation heatmap across tickers, as well as their individual risk contribution. - -```python -openbb.portfolio.po.plot(data=data_returns_hrp,weights=weights_hrp,heat=True) -``` - -Screenshot 2022-10-04 at 13 35 14 - -```python -openbb.portfolio.po.plot(data=data_returns_hrp,weights=weights_hrp,rc_chart=True) -``` - -Screenshot 2022-10-04 at 13 36 10 - -These techniques have an extensive list of parameters and thus the optimization outcome is highly dependent on the chosen parameters. For instance, you can refer to the documentation below. -Screenshot 2022-10-04 at 00 35 00 - -This allows us to alter certain assumption which also modify the asset allocation. - -```python -weights_hrp_2, data_returns_hrp_2 = openbb.portfolio.po.hrp( - tickers, - interval="5y", - risk_measure="cVaR", - risk_aversion=0.8 -) - -pd.DataFrame([weights_hrp, weights_hrp_2], index=["Basic", "Extended"]).T -``` - -Screenshot 2022-10-04 at 00 37 18 - -The basic method was optimized for *variance*. The extended method increases the period of historical data, optimizes for conditional Value at Risk and has a lower risk aversion. - -```python -openbb.portfolio.po.plot(data=data_returns_hrp,weights=weights_hrp,pie=True) -``` - -Screenshot 2022-10-04 at 13 38 12 - -```python -openbb.portfolio.po.plot(data=data_returns_hrp_2,weights=weights_hrp_2,pie=True) -``` - -Screenshot 2022-10-04 at 13 38 30 - -## Useful tips - -### 1. Display matplotlib charts in Jupyter Notebook - -To display matplotlib charts inside the Jupyter notebook output cells, you can use the block of code below, and initialize it at the top of the Notebook. - -```python -import matplotlib.pyplot as plt -import matplotlib_inline.backend_inline -from openbb_terminal.sdk import openbb -%matplotlib inline -matplotlib_inline.backend_inline.set_matplotlib_formats("svg") -``` - -### 2. Take advantage of `external_axes` - -The code below utilizes the `external_axes` parameter to get two axis in one chart. - -```python -import matplotlib.pyplot as plt -from openbb_terminal.sdk import openbb -fig, (ax1, ax2) = plt.subplots(nrows=2, ncols=1, figsize=(11, 5), dpi=150) -openbb.stocks.dps.dpotc( - "aapl", - external_axes=[ax1, ax2], - chart=True, -) -fig.tight_layout() -``` - -You can also do this to save output charts in a variable for later uses. - -### For more examples, we'd recommend checking out our [curated Jupyter Notebook reports](https://github.com/OpenBB-finance/OpenBBTerminal/tree/main/openbb_terminal/reports). They are excellent demonstration on how to use the SDK to its fullest extent diff --git a/openbb_terminal/reporting.md b/openbb_terminal/reporting.md deleted file mode 100644 index 011b06705d9..00000000000 --- a/openbb_terminal/reporting.md +++ /dev/null @@ -1,71 +0,0 @@ -# `Reporting` - -This document explains `OpenBBTerminal` `Reporting` feature. - -## 1. Purpose - -**CONTRIBUTE** - -Code is not the only way you can contribute to improve `OpenBBTerminal`. - -You can help the `OpenBBTerminal` Community by enabling sending logs about the usage of the terminal and errors. - -If you are concerned about privacy, be assured, we do **not** collect any: - -- Personal Identifiable Information (PII). -- Credentials. - -This means that you will stay anonymous at all time. - -**REASONS** - -With your these reports, we can: - -1. See what your favorite features are, understand why and further improve them. -2. Have a look at the most common errors and improve on the ease of use of the terminal. -3. Check for incompatibilities of different operating systems and python versions. - -This helps to resolve bugs faster and focus the attention of the developers on what is important to you. - -`OpenBBTerminal` is an on-site application: you install it on your computer. - -On a contrary of a web application that can track the usage of every button and page, we need logs to be sent to us to understand where to spend our time and effort. - -## 2. Disable/Enable `Reporting` ? - -By default Reporting is enabled. - -You can disable it running the command: `/settings/logcollection` - -The key `logcollection` should appear in red in the `/settings/help` table when disabled. - -You can do the same operation to re-enable it : `logcollection` will appear in green. - -## 3. What is and is not collected ? - -**NOT COLLECTED** - -We have a filter in place, to prevent any Personal Identifiable information saved in the reports. - -Credentials are not reported at all. - -Here is a list of data we are not collecting : - -|**Data**|**Description**|**Collected ?**| -|:-|:-|:-| -|User IP Address|User IP address.|NO| -|User API KEYS|API Keys to connect to third parties API, like :
- ALPHAVANTAGE
- COINBASE,
- COINPAPRIKA
- DEGIRO
- REDDIT|NO| -|User information|Other information that can let identify the users, like :
- E-mail
- LastName
- Firstname|NO| -|File/Folder paths|When errors occurs usually computers paths are shown : we filter those.|NO| - -**COLLECTED** - -Here is an exhaustive list of what can be collected : - -|**Data**|**Description**|**Examples**|**Collected ?**| -|:-|:-|:-|:-| -|Python version|Python version on which `OpenBBTerminal`|
- 3.8.12
- 3.9|YES| -|OS|Platform on which `OpenBBTerminal`, is running like|
- Linux
- Darwin
- Windows|YES| -|Exception/Error|When there is a crash of a command.||YES| -|Timestamp|Timestamp associated with logged information.|
- Launch
- Start of command
- End of command
- Exit
- Exception/Error|YES| -|Command|Commands and arguments run during a session|
- /help
- /crypto/disc/cpsearch -q eth
- /crypto/ov/cpinfo --help
- /stocks/load TSLA
- /stocks/candle --trend|YES|