Lean CLI

You can run the Research Environment with your current configuration or an old configuration from QuantConnect.

Current Configuration

The default Research Environment configuration is the latest master branch of LEAN. If you set a different research image, the image you set is your current configuration. To start a local research environment with your current configuration, open a terminal in one of your organization workspaces and then 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

JupyterLab automatically opens in your default browser. If you intend to use PyCharm or VS Code instead of JupyterLab, include the --no-open option to not open JupyterLab. To run the environment on a different port by providing the --port <port> option.

If your configuration is set to the master branch of LEAN, the CLI automatically checks if your image is behind master every seven days. If your image falls behind master, the CLI automatically updates your image to the lastest version. To force an update before the automatic check, add the --update option. To avoid updates, add the --no-update option.

Old Configurations from QuantConnect

Follow these steps to start a local Research Environment with an old research configuration from QuantConnect:

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 organization 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

The following sections explain how to operate the Research Environment with JupyterLab, the default IDE.

Open Notebooks

Follow these steps to open a research notebook in JupyterLab:

1. Start a local research environment for the project that contains the notebook.
2. In the left navigation menu, click the File Browser icon.
3. In the File Browser panel, double-click the notebook file you want to open.

The default notebook is research.ipynb.

For more information about opening files in JupyterLab, see Opening Files in the JupyterLab documentation.

Run Notebook Cells

Notebooks are a collection of cells where you can write code snippets or MarkDown. To execute a cell, press Shift+Enter.

The following describes some helpful keyboard shortcuts to speed up your research:

For more information about keyboard shortcuts in JupyterLab, see Keyboard Shortcuts in the JupyterLab documentation.

Stop Nodes

Follow these steps to stop a research node in JupyterLab:

1. In the left navigation menu, click the Running Terminals and Kernels icon.
2. In the Kernals section of the Running Terminals and Kernels panel, right-click the name of the notebook file and then click Shut Down Kernel from the drop-down menu.

For more information about the Running Terminals and Kernels panel in JupyterLab, see Managing Kernels and Terminals in the JupyterLab documentation.

Add Notebooks

Follow these steps to add notebook files to a project in JupyterLab:

1. Start a local research environment for the project.
2. In the top navigation menu, click File > New > Notebook.
3. In the Select Kernel window, click Select.

For more information about the creating files in JupyterLab, see Creating Files and Activities in the JupyterLab documentation.

Rename Notebooks

Follow these steps to rename notebook files in JupyterLab:

1. Start a local research environment for the project that contains the notebook.
2. In the left navigation menu, click the File Browser icon.
3. In the File Browser panel, right-click the notebook file you want to rename and then click Rename from the drop-down menu.
4. Enter the new name.
5. Press Enter.

Delete Notebooks

Follow these steps to delete notebook files in JupyterLab:

1. Start a local research environment for the project that contains the notebook.
2. In the left navigation menu, click the File Browser icon.
3. In the File Browser panel, right-click the notebook file you want to delete and then click Delete from the drop-down menu.
4. In the Delete window, click Delete.

The following sections explain how to operate the Research Environment with PyCharm.

Open Notebooks

Follow these steps to open a research notebook in PyCharm:

1. Start a local research environment for the project that contains the notebook.
2. Open the same project in PyCharm.
3. In the top navigation menu of PyCharm, click File > Settings.
4. In the Settings window, click Language & Frameworks > Jupyter > Jupyter Servers.
5. Click Configured Server.
6. Enter http://localhost:8888/?token= into the field.
7. Click Apply to save the changes.
8. Click OK to exit the window.
9. In the left navigation menu, click the Project icon.
10. In the Project panel, double-click the notebook file you want to open.

The default notebook is research.ipynb.

Run Notebook Cells

Notebooks are a collection of cells where you can write code snippets or MarkDown. To execute a cell, press Shift+Enter.

The following describes some helpful keyboard shortcuts to speed up your research:

For more information about keyboard shortcuts in PyCharm, see Keyboard Shortcuts in the PyCharm documentation.

Stop Nodes

Follow these steps to stop a research node in PyCharm:

1. In the left navigation menu, click the Project icon.
2. In the Project panel, right-click the name of the notebook file and then click Shutdown Kernel from the drop-down menu.

For more information about the Jupyter notebook servers in PyCharm, see Manage Jupyter notebook servers in the PyCharm documentation.

Add Notebooks

To add notebook files to a project in PyCharm, see Create a notebook file in the PyCharm documentation.

Rename Notebooks

Follow these steps to rename notebook files in PyCharm:

1. Start a local research environment for the project in PyCharm.
2. In the left navigation menu, click the Project icon.
3. In the Project panel, right-click the notebook file you want to rename and then click Refactor > Rename from the drop-down menu.
4. Enter the new name.
5. Press Enter.

Delete Notebooks

Follow these steps to delete notebook files in PyCharm:

1. Start a local research environment for the project in PyCharm.
2. In the left navigation menu, click the Project icon.
3. In the Project panel, right-click the notebook file you want to rename and then click Delete from the drop-down menu.
4. In the Delete window, click OK.

The following sections explain how to operate the Research Environment with VS Code.

Open Notebooks

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

1. Start a local research environment for the project that contains the notebook.
2. Open the same project VS Code.
3. In the Explore panel, click the notebook file you want to open.

The default notebook is research.ipynb.

4. In the top-right corner of the notebook, click Select Kernel.
5. In the Select Another Kernel window, click Existing Jypter Server....
6. Enter http://localhost:8888/ into the field.
7. Press Enter.
8. (Optional) Enter a display name for the server and then press Enter.
9. Click Foundation-Py-DefaultFoundation-C#-Default.

Run Notebook Cells

Notebooks are a collection of cells where you can write code snippets or MarkDown. To execute a cell, press Shift+Enter.

The following describes some helpful keyboard shortcuts to speed up your research:

For more information about keyboard shortcuts in VS Code, see Key Bindings for Visual Studio Code in the VS Code documentation.

Add Notebooks

Follow these steps to add notebook files to a project in VS Code:

1. Open the project.
2. In the right navigation menu, click the Explorer icon.
3. In the Explorer panel, expand the QC (Workspace) section.
4. Click the New File icon.
5. Enter fileName.ipynb.
6. Press Enter.

Rename Notebooks

Follow these steps to rename notebook files in VS Code:

1. Start a local research environment for the project that contains the notebook.
2. In the right navigation menu, click the Explorer icon.
3. In the Explorer panel, expand the QC (Workspace) section.
4. Click the New File icon.
5. Enter fileName.ipynb.
6. Press Enter.

Delete Notebooks

Follow these steps to delete notebook files in VS Code:

1. Start a local research environment for the project that contains the notebook.
2. In the right navigation menu, click the Explorer icon.
3. In the Explorer panel, right-click the notebook you want to rename and then click Rename.
4. Enter the new name and then press Enter.

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}")

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.list_projects().projects if p.name == project_name)
partial_backtest = next(b for b in api.list_backtests(project.project_id).backtests if b.name == backtest_name)
backtest = api.read_backtest(project.project_id, partial_backtest.backtest_id)

for key in backtest.statistics.keys:
    print(f"{key}: {backtest.statistics[key]}")