Lean CLI

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

You can run the research environment with the regular version of the LEAN engine or a custom version.

Regular LEAN Engine

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

  1. Open a terminal in one of your workspaces.
  2. Run lean research "<projectName>" to start a local research environment for the project in ./<projectName> 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 you want to work on in the browser window that opens.

Custom LEAN Engine

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 you want to run.
  3. Open a terminal in one of your workspaces.
  4. Run lean research "<projectName>" --image quantconnect/research:<tagFromStep2> to start a local research environment for the project in ./<projectName>.
    $ 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 the 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 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 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 <projectName>/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 Discord.

Did you find this page helpful?

Contribute to the documentation: