From a4d1d071ca01404a3faa98c6117e3958df3cb3fe Mon Sep 17 00:00:00 2001 From: Jeroen Bouma Date: Sat, 2 Jul 2022 13:06:24 +0200 Subject: [PATCH] Add in guide to Scripts & Routines (#2027) * Small detail * Add in Scripts guide * Add template script * Add Scripts to menu * Update Scripts guide * Add section on Scripts & Routines in the Getting Started guide * Update _index.md * Get rid of images --- routines/example_with_inputs.openbb | 2 +- routines/template.openbb | 17 +++ website/content/_index.md | 9 ++ website/content/terminal/scripts/_index.md | 129 ++++++++++++++++++ .../content/terminal/scripts/exe/_index.md | 41 ++++++ website/data/menu/main.yml | 5 + 6 files changed, 202 insertions(+), 1 deletion(-) create mode 100644 routines/template.openbb create mode 100644 website/content/terminal/scripts/_index.md create mode 100644 website/content/terminal/scripts/exe/_index.md diff --git a/routines/example_with_inputs.openbb b/routines/example_with_inputs.openbb index e68a94609eb..20a6397a37f 100644 --- a/routines/example_with_inputs.openbb +++ b/routines/example_with_inputs.openbb @@ -1,5 +1,5 @@ # This script requires you to use arguments. This can be done with the following: -# exe routines/example_with_inputs.openbb -i TSLA,AAPL,MSFT +# exe example_with_inputs.openbb -i TSLA,AAPL,MSFT # Go to the stocks menu stocks diff --git a/routines/template.openbb b/routines/template.openbb new file mode 100644 index 00000000000..9e1eb14ea84 --- /dev/null +++ b/routines/template.openbb @@ -0,0 +1,17 @@ +# This is a comment, below you can find a command +stocks + +# This is another comment +# There can be multiple lines of comments if desired +load MSFT + +# You can also have multiple commands below each other +candle +fa + +# You have the ability to move around menus by using / +/portfolio/po +/economy + +# Returning to home is easily done with home +home \ No newline at end of file diff --git a/website/content/_index.md b/website/content/_index.md index d115c95065f..c8cfee3e4aa 100644 --- a/website/content/_index.md +++ b/website/content/_index.md @@ -291,6 +291,15 @@ As mentioned in the Explanation of Menus, so loaded market data from load. So, if you would visit the `ta` menu (which stands for Technical Analysis) you will see that, by running any command, the selected period above is depicted again. Return to the Stocks menu again by using `q` and use it again to return to the home screen which can be shown with `?`. + +### Explanation of Scripts +The `.openbb` scripts offer the ability to automatically run a set of commands in the form of a **routine**. Furthermore, +the scripts can be adapted, and documented, at any moment giving the user full control over the type of analysis you wish +to do (and repeat). This can fundamental research, understanding market movements, finding hidden gems and even +doing advanced statistical/econometric research. + +For a thorough guide on how to setup these files, please see the Scripts & Routines guide. + ## Accessing other sources of data via API keys Within this menu you can define your, often free, API key from various platforms like Alpha Vantage, FRED, IEX, Twitter, DeGiro, Binance and Coinglass. API keys are in essence a set of random characters that is unique to you. diff --git a/website/content/terminal/scripts/_index.md b/website/content/terminal/scripts/_index.md new file mode 100644 index 00000000000..a6d4569eafd --- /dev/null +++ b/website/content/terminal/scripts/_index.md @@ -0,0 +1,129 @@ +--- +title: Scripts & Routines +keywords: "scripts, openbb, routines, script, routine, .openbb, automation" +excerpt: "The Scripts & Routines explain how to use .openbb scripts in detail +for every part of the terminal" +geekdocCollapseSection: true +--- + +The `.openbb` scripts offer the ability to automatically run a set of commands in the form of a **routine**. Furthermore, +the scripts can be adapted, and documented, at any moment giving the user full control over the type of analysis you wish +to do (and repeat). This can fundamental research, understanding market movements, finding hidden gems and even +doing advanced statistical/econometric research. + +{{< toc >}} + +## Explanation of scripts +The script file below is titled *stocks_demo.openbb*. This file follows the following logic: + +- Comments: any text after a `#` is referred to as a comment. This is used to explain what is happening within the script +and is not taking into account when running terminal commands. +- Commands: any text **without** a `#` is being ran inside the OpenBB Terminal. E.g. on the second line it says `stocks` thus within the OpenBB Terminal +the script will enter `stocks` and run this for you. + +These scripts have a 1-to-1 relationship with how you would normally use the terminal. To get a better understanding of +how the terminal is used, please see Structure of the OpenBB Terminal. + +``` +# Go into the stocks context +stocks + +# Load a company ticker, e.g. Amazon +load AMZN + +# Show a simple plot of the ticker, adding in any basic indicator. +candle --ma 20,30 + +# Switch over to the due diligence menu +dd + +# Show the price targets of Amazon, both the graph as well as the table +pt +pt --raw + +# Show estimates of annual and quarterly earnings as well as quarterly revenue estimates +est + +# Open the comparison analysis menu (ca) +../ca + +# Pick stocks that are competitors to Amazon +add ebay,wmt,tgt,baba,jd + +# Determine the valuations of each company +valuation + +# Show correlations between each company +hcorr + +# Figure out the sentiment perceived of each company +sentiment + +# Return to home +/ +``` + +## Executing a script +By going to the main menu as depicted below (accessible with `home`), the exe +command can be used. With this command you can run any `.openbb` script. These scripts are located where the application is located inside the routines folder. + +![Routine Exe OpenBB Terminal](https://user-images.githubusercontent.com/46355364/174588513-5c52ea20-548a-4c2b-a4c1-6054e2d71786.png) + +Thus, using the earlier mentioned script, we can enter `exe stocks_demo.openbb` which automatically runs all commands within the script file. +Thus, it will return a candle chart with moving averages, price targets from Analysts, valuations of related companies, the correlation between these companies and the market sentiment. +This results in the following: + +![Script Stocks Demo OpenBB](https://user-images.githubusercontent.com/46355364/176903147-720eb2af-7e5d-40df-8ec6-7363cbc08430.png) + +### Custom arguments + +Next to that, it is also possible to add in custom arguments to your script making the script more interactive and allow +you to do the same analysis for multiple companies. This is done in the following script: + +``` +# This script requires you to use arguments. This can be done with the following: +# exe example_with_inputs.openbb -i TSLA,AAPL,MSFT + +# Go to the stocks menu +stocks + +# Load a ticker, given the argument used. E.g. -i TSLA +load $ARGV[0] + +# Enter the Technical Analysis (ta) menu +ta + +# Show the fibonacci retracement levels +fib + +# Enter the comparison analysis (ca) menu +../ca + +# Set two extra tickers based on the arguments used. E.g. -i TSLA,AAPL,MSFT +set $ARGV[1],$ARGV[2] + +# Plot the historical prices +historical + +# Return to home +/ +``` + +This script includes `$ARGV[0]`, `$ARGV[1]` and `$ARGV[2]`. This means that the script requires you to submit three +arguments. In this case, they refer to stock tickers. +Therefore, like the script also says, you can include these arguments with `-i` followed by three tickers (e.g. `exe example_with_inputs.openbb -i TSLA,AAPL,MSFT`). +This results in the following: + +![Example with Inputs OpenBB Script](https://user-images.githubusercontent.com/46355364/176903205-3cb55bf5-8710-4ad6-8eef-f9a99294ea3b.png) + +It is an incredibly simple script, but it gives an understanding what the possibilities are. + +## Create your own script +Scripts and routines reside in the `routines` folder and are automatically shown when you type `exe` from the +home screen (`home`). To create your own, you can use the `template.openbb` file as a basis but you are free to +duplicate one of the demo files. + +Within this template, some examples are given, and you are free to change the contents and rename the file. As long as +the file remains in the same folder, you will be able to find your file automatically as shown below: + +![Show Copy of Template OpenBB Script](https://user-images.githubusercontent.com/46355364/176903253-00a5b0f9-a6e7-49c7-a1d8-49ae819e28e3.png) diff --git a/website/content/terminal/scripts/exe/_index.md b/website/content/terminal/scripts/exe/_index.md new file mode 100644 index 00000000000..f2ceb3aa027 --- /dev/null +++ b/website/content/terminal/scripts/exe/_index.md @@ -0,0 +1,41 @@ +``` +usage: exe [-p PATH] [-i ROUTINE_ARGS] [-h] +``` + +The .openbb scripts offer the ability to automatically run a set of commands in the form of a **routine**. Furthermore, +the scripts can be adapted, and documented, at any moment giving the user full control over the type of analysis you wish +to do (and repeat). This can fundamental research, understanding market movements, finding hidden gems and even +doing advanced statistical/econometric research. + +``` +optional arguments: + -p PATH, --path PATH The path or .openbb file to run. (default: ) + -i ROUTINE_ARGS, --input ROUTINE_ARGS + Select multiple inputs to be replaced in the routine and separated by commas. E.g. GME,AMC,BTC-USD (default: None) + -h, --help show this help message (default: False) + +``` + +An example of a script can be the following (inside a `.openbb` file): + +``` +# Go into the econometrics context +econometrics + +# Load the wage_panel dataset and include an alias +load wage_panel -a wp + +# Set the MultiIndex, allowing for Panel regressions to be performed +index wp -i nr,year + +# Change the type of the year column so it can be included as time effects within the regressions +type wp.year -f category + +# Perform a Pooled OLS, Random Effects and Fixed Effects estimation +panel -d wp.lwage -i wp.black,wp.hisp,wp.exper,wp.expersq,wp.married,wp.educ,wp.union,wp.year +panel -d wp.lwage -i wp.black,wp.hisp,wp.exper,wp.expersq,wp.married,wp.educ,wp.union,wp.year -r re +panel -d wp.lwage -i wp.expersq,wp.union,wp.married,wp.year -r fe + +# Compare the results obtained from these regressions +compare +``` \ No newline at end of file diff --git a/website/data/menu/main.yml b/website/data/menu/main.yml index b30de9f56a9..02852db31f8 100755 --- a/website/data/menu/main.yml +++ b/website/data/menu/main.yml @@ -1649,6 +1649,11 @@ main: ref: "/terminal/common/prediction_techniques/conv1d" - name: mc ref: "/terminal/common/prediction_techniques/mc" + - name: scripts + ref: "/terminal/scripts" + sub: + - name: exe + ref: "/terminal/scripts/exe" - name: "OpenBB Python API" ref: "/api" - name: "OpenBB Bots"