From 593edf8a08052f79d43edc6df2359326cd5337d3 Mon Sep 17 00:00:00 2001 From: Danglewood <85772166+deeleeramone@users.noreply.github.com> Date: Thu, 16 Feb 2023 20:35:55 -0800 Subject: [PATCH] updates routines intro --- .../guides/advanced/scripts-and-routines.md | 172 +++++++++--------- 1 file changed, 88 insertions(+), 84 deletions(-) diff --git a/website/content/terminal/guides/advanced/scripts-and-routines.md b/website/content/terminal/guides/advanced/scripts-and-routines.md index fffb575a010..af0b2e7e4d9 100644 --- a/website/content/terminal/guides/advanced/scripts-and-routines.md +++ b/website/content/terminal/guides/advanced/scripts-and-routines.md @@ -1,113 +1,117 @@ --- sidebar_position: 5 title: Scripts & Routines -description: 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. +description: OpenBB Routine files, `.openbb`, are simple scripts for automating processes and repetitive tasks. They represent a 1:1 relationship with any command in the OpenBB Terminal; one line represents one function. A routine file can be created or modified in any basic text editor, the only difference between a plain-text file and an OpenBB Routine file is the `.openbb` file extension. Additionally, routine files can be captured with the macro recorder, controlled with global commands, `record` & `stop`. Upon `stop`, the script is automatically saved to the, `~/OpenBBUserData/routines/`, folder. Routine files stored there are callable from the main menu, using the `exe` function. By deploying variable arguments - `$ARGV[0]` - to any line in the script, dates, symbols, exported filenames, or any Terminal function argument, scripts become dynamic. keywords: [scripts, routines, .do file, stata, spss, r studio, python, automation, data collection, aggregation, script, routine, openbb terminal] --- -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. +## OpenBB Routine Files -The .openbb scripts offer a vast amount of capabilities to export data from the OpenBB Terminal directly into Excel files allowing students, professors, researchers and professionals to collect a a large dataset incredibly quick. For example, the GIF below demonstrates market data collection of all constituents of the S&P 500. Download the routine file [here](https://www.dropbox.com/s/3w8jgtzl0yoq9o9/sp500.openbb?dl=0) and place it in the `routines` folder as found in the `OpenBBUserData` folder and execute with `exe sp500.openbb`. Read on to understand in detail how to create and execute these type of files. +OpenBB Routine files, `.openbb`, are simple scripts for automating processes and repetitive tasks. They represent a 1:1 relationship with any command in the OpenBB Terminal; one line represents one function. A routine file can be created or modified in any basic text editor, the only difference between a plain-text file and an OpenBB Routine file is the `.openbb` file extension. Additionally, routine files can be captured with the macro recorder, controlled with global commands, `record` & `stop`. Upon `stop`, the script is automatically saved to the, `~/OpenBBUserData/routines/`, folder. Routine files stored there are callable from the main menu, using the `exe` function. By deploying variable arguments - `$ARGV[0]` - to any line in the script, dates, symbols, exported filenames, or any Terminal function argument, scripts become dynamic. - +Run a routine file from the main menu, with the `exe` command. Below, the `--help` dialogue is displayed. -### Create your own script +```console +usage: exe [--file PATH] [-i ROUTINE_ARGS] [-e] [-h] -Within the OpenBB Terminal, you have the option to record your own session with `record` which converts any commands you run in an .openbb script until you type `stop`. Find a short demonstration below. - - - -As shown in the video, scripts and routines reside in the `routines` folder within the `OpenBBUserData` folder (as found [here](https://docs.openbb.co/terminal/guides/advanced/data)) and are automatically shown when you type `exe` from the home screen (`home`). - -:::note To manually create your own .openbb script use the following: -1. Download the file that can be used as a template [here](https://www.dropbox.com/s/73g9qx9xgtbb2ec/routines_template.openbb?dl=0). -2. Move the file inside the `routines` folder within the [OpenBBUserData](https://docs.openbb.co/terminal/guides/advanced/data) folder and, optionally, adjust the name to your liking. -3. Open the file with a Text Editor (e.g. Notepad or TextEdit) and adjust the file accordingly. -4. Open up the OpenBB Terminal, and type `exe --file`. The file should then be one of the options. -5. Select the file to run the routine script. -::: - -As long as the file remains in the `routines` folder, you will be able to find your file automatically as shown below: - -![Script Showcase](https://user-images.githubusercontent.com/46355364/213746605-53cfeb46-13f2-4550-b0fd-9de8a6d06bf1.png) - -### Explanation of scripts - -The script file follows the following logic: - -- **Comments**: any text after a hashtag (`#`) 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 hashtag 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. The example below can be executed by running `exe --example`. +Execute automated routine script. For an example, please use `exe --example` and for documentation and to learn how create your own script type `about exe`. +options: + --file PATH The path or .openbb file to run. (default: None) + -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) + -e, --example Run an example script to understand how routines can be used. (default: False) + -h, --help show this help message (default: False) ``` -# Go into the stocks context + +## The Macro Recorder + +With the macro recorder, it is easy to get started; just enter `record`. To follow along, copy the block below into the Terminal at the main menu. + +```console +record/stocks/load qqq/forecast/expo QQQ/autoselect QQQ/stop +``` + +![Routines](routines1.png) + +![Routines](routines2.png) + +The routine has been successfully captured, and the next time the Terminal is opened, this routine will be visible when calling the `exe` function. + +![Routines](routines3.png) + +## Editing & Inserting Arguments + +Let's take a look at the routine file that was just generated. This is what was captured, the recorder interpreted each `/` as a new command: + +```console stocks -# Load a company ticker, e.g. Apple -load AAPL +load qqq -# Show a candle chart with a 20 day Moving Average -candle --ma 20 +forecast -# Switch over to the Due Diligence menu -dd +expo QQQ -# Show analyst ratings -analyst - -# Show price targets charts -pt - -# Show future estimations -est - -# Return to home -home +autoselect QQQ ``` -### Executing a script +A routine file that is locked to any single symbol will likely be less desirable than one which can be applied to any ticker. OpenBB routine files overcome this obstacle by allowing for an unlimited number of variable arguments - `$ARGV[0]` - to be assigned anywhere in the script. Let's go ahead and edit our Routine file to accommodate any symbol. -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 as found in the `OpenBBUserData` folder. - -Thus, using the earlier mentioned script, we can enter `exe --file routines_template.openbb` which automatically runs all commands within the script file. Thus, it will return a candle chart with a moving average of 20 days, expectations and price targets from analysts and estimated future performance before returning to the home window. - -![OpenBB Routine Script Execution](https://user-images.githubusercontent.com/46355364/213746495-6b38ab67-1d90-46b1-898f-9df1ce4063c0.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 (and can be downloaded [here](https://www.dropbox.com/s/usooz6y29r1xldb/routines_template_with_inputs.openbb?dl=0): - -``` -# This script requires you to use arguments. This can be done with the following: -# exe --file routines_template_with_inputs.openbb -i TSLA,AAPL,MSFT - -# Go to the stocks menu +```console stocks -# Load a ticker, given the argument used. E.g. -i TSLA load $ARGV[0] -# Enter the Technical Analysis (ta) menu -ta +forecast -# Show the fibonacci retracement levels -fib +expo $ARGV[0] -# Enter the comparison analysis (ca) menu -../ca - -# Set two extra tickers based on the arguments used. E.g. -i TSLA,AAPL,MSFT -add $ARGV[1],$ARGV[2] - -# Plot the historical prices -historical - -# Return to home -home +autoselect $ARGV[0] ``` -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: +Open the file with a text editor, make the changes, save the file, and then run the `exe` command again; except now, add the `--input` argument with a new ticker. For demonstration purposes, the routine file used in the example has been renamed to be `demo_routine.openbb`. Because the file name was changed, the Terminal will need to be restarted for the new name to be recognized. In subsequent edits, this will not be necessary because the file is read from start-to-finish with every execution. -![OpenBB Script with Input](https://user-images.githubusercontent.com/46355364/213747540-1907ffdb-1950-42a7-bb5b-8482777a9763.png) +```console +exe demo_routine.openbb --input SPY +``` -It is an incredibly simple script, but it gives an understanding what the possibilities are. Do make sure you saved this script in the `routines` folder else you are not able to execute it. +![Routines](routines4.png) + +Additional variables can be assigned to perform other functions, a date for example. Let's modify the routine file to include a start date as part of the `load` function. For those following along at home, modify the second command in the script to be: + +```console +load $ARGV[0] --start $ARGV[1] +``` + +The additional argument is added to the previous `exe` syntax as a comma-separated list. + +```console +exe demo_routine.openbb --input SPY,2022-01-01 +``` + +![Routines](routines5.png) + +This process is limited only to the imagination. Large, reptitive, tasks can be automated by extrapolating on the process above. + +## Commenting + +Commenting within an OpenBB routine file provides the creator to communicate with the end-user. Commented lines - beginning with, "#" - are passed over during execution of the routine. Let's update the example routine file with a few commments to illustrate. + +```console +# This routine is a demonstration of the OpenBB routine files. +# Read the docs here: https://docs.openbb.co/terminal/guides/advanced/scripts-and-routines + +# Start of routine +stocks + +load $ARGV[0] --start $ARGV[1] + +forecast + +expo $ARGV[0] + +autoselect $ARGV[0] + +# End of routine +# Please note that the outputs of this routine will be different than depicted, because, you are now in the future. +```