QuantConnect: Adding a Library

Anyone who has managed to get a little further than a simple “Hello World” tutorial in Python will have had some experience using a python library. Libraries offer us a suite of pre-made functions and features and save us from re-inventing the wheel. Without them, we would need to build everything from scratch each and every time we want to write something new. After all, if you were building a house, you wouldn’t want to go through the hassle of forging your own bricks. Instead, you would buy them ready-made so that you can get on with the much more enjoyable task of constructing something new. Note: Technically, the correct name is a module. However, Library is often used interchangeably. For the sake of this post, we will use the term library as that is the term used inside the QuantConnect online editor.

Libraries on QuantConnect

We are able to use two types of library on QuantConnect. The first is a series of white-listed official and 3rd party libraries. These are the type of library you would usually install with pipand importinto your script. The second type is a user-created library. In a pure python environment, there would be little difference between how you handle the two.  However, since QuantConnect is a cloud platform, there are some limitations as to what libraries we can use. Furthermore, there are some additional steps we need to go through in order to utilize our own library.

Official and 3rd Party Python Libraries

As just mentioned, QuantConnect is an online service. Therefore, it cannot offer every Python library you might like to use. For example, it would not be wise to allow users to import the oslibrary where they could accidentally cause damage to the servers that the platform runs on. Instead, packages are tested and white-listed for use. Once approved, they can be imported in your algorithm in the same fashion as any python package in your local environment. For example, using: import pandas As you might guess, this imports the popularpandaslibrary. You can find a full list of white-listed packages here: https://www.quantconnect.com/docs/key-concepts/supported-libraries Since importing and utilizing white-listed package is no different from regular python, this post will not discuss these any further.

User Created Libraries

Instead, the main focus of this post will be to take a look at user-created libraries. We do this via the option on the project pane that allows you to “Add New Library”. Some beginners might be confused into thinking this button allows you to add a library in a similar manner to using pipon the command line. It does not. This is the place to re-use your own code, save yourself some copy/paste time and, more importantly, ease maintenance of the same code snippets across projects! This post doesn’t end there though. The process of doing this is currently a little fiddly and is therefore ripe for a step by step guide.

Basic Template Library

Click on the “Add New Library” button shown above. When you do this for the first time you will be presented with a window which looks like this: No libraries are found because you have never created one! Click on the “Create a New Library” button in the bottom right and it will produce the following template code for you to use as an example.

### <summary>
### Basic Template Library Class
###
### Library classes are snippets of code/classes you can reuse between projects. They are
### added to projects on compile. This can be useful for reusing indicators, math functions,
### risk modules etc. Make sure you import the class in your algorithm. You need
### to name the file the module you'll be importing (not main.cs).
### importing.
### </summary>
class BasicTemplateLibrary:

    '''
    To use this library place this at the top:
    from BasicTemplateLibrary import BasicTemplateLibrary

    Then instantiate the function:
    x = BasicTemplateLibrary()
    x.Add(1,2)
    '''
    def Add(self, a, b):
        return a + b

    def Subtract(self, a, b):
        return a - b

The library provides two simple functions. Adding and subtracting. It is a purposefully basic example to show the general concept. You will also notice that the name of the file we are working on has changed. This is because we are now editing the library project and not your algorithm anymore. Next, close the Basic Library Template (Py) project. There is no need to edit it as we will just use this example code for now. Upon closing the library, you might notice that a new folder namedLibraryhas been automatically created inside your home folder. This folder will contain all of the libraries you create now and in the future.

Adding the Basic Template Library

Now that we have created a library, we can import it! Create a new classic algorithm (if you are unfamiliar how to do this, see here.) or load up one of your other projects. Once loaded, click on “Add New Library” again. This time, you will notice that our Basic Library Template is contained in the list. Click on it to import it.

Duplicate main.py files

The first thing you will notice now is that we have two files in the project both with the title main.py! This will cause an error with the compiler because we cannot have two main.py files. As such, we must rename the main.py of the library. When doing this, make sure you do not rename both of them. If you rename both, you will get another error. This is because the project must contain at least one main.py file. As it can be a bit confusing which of the two files to rename, the easiest way to rename the library is to close the project and then reloadBasicTemplate Library Template (Py). Remember it will be located inside the newly created Library folder. After it is loaded you can then hover over the main.pyfile on the left pane. Rename the file to something else. I chose BLT.py (An acronym, not a sandwich!). After renaming the file, you can reopen your main project and you will see that the file has been renamed. And now we are ready to rock and roll.

Using BLT.py in the Algorithm

Now that we have the environment nicely set up, we can import the package just like any other python module. If you have been paying attention to the example code above, you could easily be confused by these lines in the code comments:

# To use this library place this at the top:
# from BasicTemplateLibrary import BasicTemplateLibrary

If you do that, you will receive an import error. Instead, we will actually import using the filename we just edited. I.e. from BLT import BasicTemplateLibrary This means even if we didn’t edit the file name, you would still receive an error following the guidelines in the comment because the name of the file before was main.py. That point is moot though as we can’t even compile the code with two main.py files.

Example Code

The hard bit is over! Now we have the library imported, we can create a simple example algorithm to make use of the Subtract()function from the example library.

import numpy as np
from BLT import BasicTemplateLibrary
### <summary>
### Basic template algorithm simply initializes the date range and cash. This is a skeleton
### framework you can use for designing an algorithm.
### </summary>
class BasicTemplateAlgorithm(QCAlgorithm):
    '''Basic template algorithm simply initializes the date range and cash'''

    def Initialize(self):
        '''Initialise the data and resolution required, as well as the cash and start-end dates for your algorithm. All algorithms must initialized.'''

        self.SetStartDate(2013,10, 7)  #Set Start Date
        self.SetEndDate(2013,10,11)    #Set End Date
        self.SetCash(100000)           #Set Strategy Cash
        self.Ticker = "SPY"
        # Find more symbols here: http://quantconnect.com/data
        self.AddEquity(self.Ticker, Resolution.Daily)

    def OnData(self, data):
        '''OnData event is the primary entry point for your algorithm. Each new data point will be pumped in here.

        Arguments:
            data: Slice object keyed by symbol containing the stock data
        '''
        
        # Get OHLC
        if data.ContainsKey(self.Ticker) and data.HasData:
 
            O = data[self.Ticker].Open
            H = data[self.Ticker].High
            L = data[self.Ticker].Low
            C = data[self.Ticker].Close
            P = data[self.Ticker].Price
            
            x = BasicTemplateLibrary()
            HmL = x.Subtract(H,L)
            
            self.Log(">> High: {} Low: {} | High - Low: {}".format(H,L,HmL))
    
        if not self.Portfolio.Invested:
            self.SetHoldings(self.Ticker, 1)

In the example code above, we instantiate the library. I.e. We create a new object called x from the BasicTemplateLibrary class blueprints. After this, we can then use x to access the function Subtract()method. Finally, we log the results returned from this method just to ensure it is working correctly.

Another Way

If the thought of classes and the terminology around them have you twitching for the close button on your browser then there is another way! You can also import simple functions that are not part of a class using the same method. For example, we could have a Library/Basic Library Template (Py)file that contains the following:

### <summary>
### Basic Template Library Class
###
### Library classes are snippets of code/classes you can reuse between projects. They are
### added to projects on compile. This can be useful for reusing indicators, math functions,
### risk modules etc. Make sure you import the class in your algorithm. You need
### to name the file the module you'll be importing (not main.cs).
### importing.
### </summary>

def Subtract(a, b):
        return a - b

Then you would import and use it in a similar manner. However, this time around, you would import the function directly and there would be no need to instantiate a class first. (Notice we are now importing Subtractinstead of BasicTemplateLibrary)

import numpy as np
from BLT import BasicTemplateLibrary
from SimpFunc import Subtract
### <summary>
### Basic template algorithm simply initializes the date range and cash. This is a skeleton
### framework you can use for designing an algorithm.
### </summary>
class BasicTemplateAlgorithm(QCAlgorithm):
    '''Basic template algorithm simply initializes the date range and cash'''

    def Initialize(self):
        '''Initialise the data and resolution required, as well as the cash and start-end dates for your algorithm. All algorithms must initialized.'''

        self.SetStartDate(2013,10, 7)  #Set Start Date
        self.SetEndDate(2013,10,11)    #Set End Date
        self.SetCash(100000)           #Set Strategy Cash
        self.Ticker = "SPY"
        # Find more symbols here: http://quantconnect.com/data
        self.AddEquity(self.Ticker, Resolution.Daily)

    def OnData(self, data):
        '''OnData event is the primary entry point for your algorithm. Each new data point will be pumped in here.

        Arguments:
            data: Slice object keyed by symbol containing the stock data
        '''
        
        # Get OHLC
        if data.ContainsKey(self.Ticker) and data.HasData:
 
            O = data[self.Ticker].Open
            H = data[self.Ticker].High
            L = data[self.Ticker].Low
            C = data[self.Ticker].Close
            P = data[self.Ticker].Price
            
            HmL = Subtract(H,L)
            
            self.Log(">> High: {} Low: {} | High - Low: {}".format(H,L,HmL))
    
        if not self.Portfolio.Invested:
            self.SetHoldings(self.Ticker, 1)

Second note: In this example main.pyof library was renamed to SimpFunc.py instead of BLT.py.

Running the Script

Finally, now that we have everything in place, you can run the script and check the output. After doing this, you should be able to check the log file and see that we are subtracting the highfrom thelowon each bar.

2013-10-07 00:00:00 Launching analysis for 3e3d545143a85e32cefda07482710e53 with LEAN Engine v2.4.0.0.5335
2013-10-08 00:00:00 >> High: 152.5560687 Low: 151.4692935 | High - Low: 1.0867752000000053
2013-10-09 00:00:00 >> High: 151.80438252 Low: 149.75762256 | High - Low: 2.046759960000003
2013-10-10 00:00:00 >> High: 150.5183652 Low: 149.00593638 | High - Low: 1.5124288199999967
2013-10-11 00:00:00 >> High: 153.28964196 Low: 151.45118058 | High - Low: 1.8384613800000125
2013-10-12 00:00:00 >> High: 154.24962672 Low: 152.84587542 | High - Low: 1.4037513000000104
2013-10-12 00:00:00 Algorithm Id:(3e3d545143a85e32cefda07482710e53) completed in 0.49 seconds at 0k data points per second. Processing total of 6 data points.