Tutorials

Research

Introduction

Starting local Jupyter Lab environments is a powerful feature of the Lean CLI. Jupyter Lab environments allow you to work on research notebooks locally. These environments contain the same features as QuantConnect's research environment but run locally with your own data.

Running local research environment

Follow these steps to start a local research environment:

  1. Open a terminal in the directory you ran lean init in.
  2. Run lean research "My Project" to start a local research environment for the project in ./My Project on port 8888.
    $ lean research "My Project"
    Starting JupyterLab, access in your browser at localhost:8888
    You can run the environment on a different port by providing the --port <port> option.
  3. Open the research notebook that you want to work on in the browser window that opens.

Follow these steps to start a local research environment with a custom version of the LEAN engine:

  1. View the available versions on the quantconnect/research Docker Hub tags page.
  2. Copy the name of the tag that you want to run.
  3. Follow the "How to start a local research environment" steps above and append the --image quantconnect/research:<tag from step 2> option when running the lean research command.
    $ lean research "My Project" --image quantconnect/research:11154
    Pulling quantconnect/research:11154...
    20210322 17:27:46.658 TRACE:: Engine.Main(): LEAN ALGORITHMIC TRADING ENGINE v2.5.0.0 Mode: DEBUG (64bit)
    20210322 17:27:46.664 TRACE:: Engine.Main(): Started 5:27 PM

Opening research notebooks in PyCharm

Follow these steps to open a research notebook in PyCharm:

  1. Start a local research environment for the project containing the notebook.
  2. Open the project containing the notebook in PyCharm.
  3. Open PyCharm's settings and go to Build, Execution, Deployment > Jupyter > Jupyter Servers.
  4. Tick the radio box in front of Configured Server and enter "http://localhost:8888/?token=" as Jupyter Server URL.
  5. Click Apply in the bottom-right to save the changes and OK to exit settings window.
  6. Open the notebook file that you want to work in PyCharm's file tree.

Opening research notebooks in VS Code

Follow these steps to open a research notebook in VS Code:

  1. Start a local research environment for the project containing the notebook.
  2. Open the project containing the notebook in VS Code.
  3. Open VS Code's Command Palette by pressing Ctrl+Shift+P.
  4. Find and execute the "Jupyter: Specify local or remote Jupyter server for connections" command.
  5. Select Existing in the list of choices that pops up.
  6. Enter "http://localhost:8888/" when asked for the URI of the running Jupyter server.
  7. Restart VS Code.
  8. Open the notebook file that you want to work in VS Code's file tree.

Retrieving local backtests

Sometimes it might be useful to retrieve the results of a previously ran local backtest in the research environment. By default, backtests are saved in the <project>/backtests/<timestamp> directory, which is also available in the research environment. You can use the following code snippet to read the contents of a backtest's result file into a local variable and to print its statistics (make sure to replace the path to the backtest with your own):

using Newtonsoft.Json;
using QuantConnect.Packets;

var backtestPath = "backtests/2021-03-03_23-46-43/CSharpProject.json";

var json = File.ReadAllText(backtestPath);
var data = JsonConvert.DeserializeObject<BacktestResultParameters>(json);

foreach (var item in data.Statistics) {
    Console.WriteLine($"{item.Key}: {item.Value}");
}
import json

backtest_path = "backtests/2021-03-03_01-57-38/main.json"

with open(backtest_path) as file:
    data = json.load(file)

for key, value in data["Statistics"].items():
    print(f"{key}: {value}")

Retrieving cloud backtests

If you are logged in using lean login you can also retrieve cloud backtest results in your local research environment. If you know the name of the project and the backtest you can use the following code snippet to retrieve the backtest's results and to print its statistics:

var projectName = "Python Template";
var backtestName = "Adaptable Tan Frog";

var project = api.ListProjects().Projects.First(p => p.Name == projectName);
var partialBacktest = api.ListBacktests(project.ProjectId).Backtests.First(b => b.Name == backtestName);
var backtest = api.ReadBacktest(project.ProjectId, partialBacktest.BacktestId);

foreach (var item in backtest.Statistics) {
    Console.WriteLine($"{item.Key}: {item.Value}");
}
project_name = "Python Template"
backtest_name = "Adaptable Tan Frog"

project = next(p for p in api.ListProjects().Projects if p.Name == project_name)
partial_backtest = next(b for b in api.ListBacktests(project.ProjectId).Backtests if b.Name == backtest_name)
backtest = api.ReadBacktest(project.ProjectId, partial_backtest.BacktestId)

for key in backtest.Statistics.Keys:
    print(f"{key}: {backtest.Statistics[key]}")

You can also see our Videos. You can also get in touch with us via Chat.

Did you find this page helpful?

Contribute to the documentation: