OpenBB Routines - What are they?

If you’ve read about the launch of OpenBB Terminal 3.1.0, you may have noticed that one of the enhanced features is the OpenBB scripting language. This post will go into its history and discuss our future plans.

Allow us to dive in OpenBB Routines on OpenBB Terminal 3.1.0. Let's explore the history behind it and our vision for the future.

Single Commands

During the early stages of my investing journey, I devoted time to analyzing equities. This involved researching fundamentals, exploring insider trading, conducting charting analysis, comparing companies, evaluating company management, and even behavioral analysis.

As my knowledge expanded, I found myself spending not just evenings, but entire weekends conducting research on a single ticker. I delved into areas such as government trading, dark pool data, options, and alternative datasets. As a result, I needed more "compartments" in my brain to organize all the information. In practice, this translated into creating a bullet list in my notebook to keep track of the aspects I wanted to investigate for a particular ticker.

When I began developing the OpenBB Terminal (formerly known as Gamestonk Terminal), I aimed to replicate the organizational structure of my investment research workflow, mirroring the way it existed in my mind. Consequently, I dedicated significant time to establishing such a hierarchy. This is why the terminal now exhibits a hierarchical structure:

If my intention was to explore GME's dark pool data, I simply needed to navigate to the stocks section within the OpenBB Terminal and then proceed to the dps subsection (which stands for dark pool and short data). Upon reaching this point, the terminal would present me with several available commands that I could execute to retrieve the desired data.

Command pipelines

This organizational structure within the terminal significantly accelerated my investment research process, aligning with the way my brain categorized various aspects of investing. Nevertheless, there was still a limitation: I had to input commands one by one, which meant it took some time to gather all the data I wanted to analyze.

That’s why, we created the notion of pipeline of commands. This means that I could access a command (or more) in a single terminal input, like this:

stocks/load GME/dps/psi

But also that I could create full sequence of commands, e.g.

stocks/load GME/dps/psi/../fa/pt/income/../ins/stats

However, a new issue arose: the pipeline of commands became increasingly lengthy. This posed a challenge when sharing the commands with colleagues, as it became difficult for them to understand the purpose of the pipeline and what each step aimed to achieve.

Scripts (just parse commands)

At this point, the concept of scripts was introduced to address these challenges. However, the initial implementation of scripts was quite basic, focusing on two core ideas:

1. A script is a text file with the extension .openbb that contains a sequence of commands.
2. Empty lines or lines starting with "#" are ignored and serve as comments within the script.

This introduction of scripts brought a significant improvement in terms of readability. Users could now easily share these .openbb files, providing added clarity through comments about the intended actions. Below is an example of what one of these scripts could look like, which can be easily created in the OpenBB Hub.

External Variables

However, a new issue emerged: the scripts had hardcoded tickers, leading users to create separate routines for each specific ticker, such as my_due_diligence_AAPL.openbb or my_due_diligence_TSLA.openbb. This approach was suboptimal, considering that we had control over reading these scripts and they were meant to be used within our ecosystem.

To address this limitation, we introduced the concept of arguments, inspired by the Perl language. These arguments are variables referenced within the .openbb script as $ARGV or $ARGV[0], $ARGV[1], and so on. They are provided in the terminal by adding the --input flag, followed by the variables separated by commas.

For instance, if a routine file called script_with_input.openbb had the following format:

And we run it in the terminal with exe —file script_with_input.openbb —input MSFT, what would be run would be stocks/load MSFT --start 2015-01-01/ta/ema -l 20,50,100,200 and so you could use the same routine for multiple tickers - making it a more powerful automated workflow.

For instance, the example below shows how you can run the same script for MSFT but also TSLA ticker.

Support internal variables

In addition to enabling users to run scripts with external variables using the keyword ARGV, we also support the use of internal variables within the script. These variables are defined by starting with the $ character.

Which has the following output:

Note that the variable can have a single element or can be constituted by an array where elements are separated using a comma “,”.

Support relative keywords

In addition to the powerful variables discussed earlier, OpenBB also supports the usage of relative keywords, particularly for working with dates. These relative keywords provide flexibility when specifying dates in relation to the current day. There are four types of relative keywords:

1. AGO: Denotes a time in the past relative to the present day. Valid examples include $365DAYSAGO, $12MONTHSAGO, $1YEARSAGO.

2. FROMNOW: Denotes a time in the future relative to the present day. Valid examples include $365DAYSFROMNOW, $12MONTHSFROMNOW, $1YEARSFROMNOW.

3. LAST: Refers to the last specific day of the week or month that has occurred. Valid examples include $LASTMONDAY, $LASTJUNE.

4. NEXT: Refers to the next specific day of the week or month that will occur. Valid examples include $NEXTFRIDAY, $NEXTNOVEMBER.

The result will be a date with the conventional date associated with OpenBB, i.e. YYYY-MM-DD.

By picking on the previous example, we can add to the load --start argument the keyword $18MONTHSAGO.

This will result in the following output:

Loops

Finally, what scripting language would this be if there were no loops? For this, we were inspired by MatLab. The loops in OpenBB utilize the foreach and end convention, allowing for iteration through a list of variables or arguments to execute a sequence of commands.

To create a foreach loop, you need to follow these steps:

1. Create the loop header using the syntax: foreach $$VAR in X where X represents either an argument or a list of variables. It's worth noting that you can choose alternative names for the $$VAR variable, as long as the $$ convention is maintained.

2. Insert the commands you wish to repeat on the subsequent lines.

3. Conclude the loop with the keyword end.

Here's some examples illustrating the usage of a foreach loop:

# Iterates through ARGV elements from position 1 onwards
foreach $$VAR in $ARGV[1:]
   load $$VAR --start $DATES[0] --end $DATES[1]/dps/psi
end

# Loops through all $ARGV variables
FOREACH $$SOMETHING in $ARGV
   load $$SOMETHING --start $DATE[0]/ins/stats/..
end

# Iterates through ARGV elements in position 1,2
foreach $$VAR in $ARGV[1:3]
load $$VAR --start 2022-01-01
ba
regions
..
END

# Loops through PLTR and BB
foreach $$X in PLTR,BB
 load $$X --start $LASTJANUARY
 candle
END

Note that we allow users to slice an array by utilizing the 0-index based approach - which is characteristic of the Python language. So if a user declares $TICKERS = AAPL,MSFT,TSLA,NVDA, then $TICKERS[1:3], will return MSFT,TSLA.

Conclusion

OpenBB is quickly establishing itself as a frontrunner in automating investment research. With its robust features and powerful scripting capabilities, OpenBB is revolutionizing how investors approach their research workflows. If you're looking to delve deeper into OpenBB scripts, our comprehensive open-source documentation is readily available at: [Routines | OpenBB Docs](https://docs.openbb.co/terminal/usage/routines).

However, this is just the beginning of OpenBB routines.

In the near future, we have exciting plans to enable users to share and upvote these routines within the community. By fostering collaboration and knowledge-sharing, our aim is to empower investors to learn from one another, enhance their investment research skills, and optimize their workflows, ultimately saving valuable time.