Open Source

Lean Report Creator

Lean Report Creator

Introduction

The LEAN Report Creator (LRC) is a report generated from backtesting-result objects and allows you to quickly create polished, professional-grade reports for each backtest (see a full example report generated by LRC). We hope that you can use these reports to share your strategy performance with prospective investors. The report was generated using the examples provided in this tutorial.

The algorithm used to generate the example report is provided below.

Users working through the QuantConnect.com IDE can have these reports generated automatically at the end of a backtest. To generate one, look at the “Report” tab below your backtest result charts and click "Request Report".

Creating a Report

The Lean Report Creator is a project located in the Report folder. It is a command line tool that takes the JSON backtest result object as its input. You can run it using command line arguments, or by filling in the config.json file.

./QuantConnect.Report.exe --backtest-data-source-file sample.json --report-destination Example.html

The program has a few options you should configure to your requirements:

Command SwitchDescription
--backtest-data-source-fileLocation of the source backtest JSON file.
--live-data-source-fileLocation of the source live JSON file.
--report-destinationResulting output HTML file location.
--strategy-nameName of the strategy. This will appear at the top-right corner of each page in the report.
--strategy-versionVersion number of the strategy. This will appear at the top-right corner next to the strategy name.
--strategy-descriptionDescription that describes what the strategy does. This will appear under the "Strategy Description" section of the report.

The program injects the images as base64 encoded objects into the HTML file to make it more portable and simpler to share with your partners.

Source Backtest

The --backtest-data-source-file switch refers to a JSON file created by the LEAN Engine. This holds all of the backtest data which is required for generating the report HTML. This data can be sourced from desktop or cloud backtests.

Desktop Backtesting Results

By default, LEAN saves the backtest result data to disk inside of your LEAN launcher folder: Lean/Launcher/bin/Debug/BasicTemplateAlgorithm.json. You can access it like this from the Report executable:

./QuantConnect.Report.exe --backtest-data-source-file ../../../Launcher/bin/Debug/BasicTemplateAlgorithm.json ...

Cloud Backtesting Results

Backtest processed reports can be downloaded via API. The following example imports the QuantConnect API class and uses it to download the final HTML report. To access the API you will need to know your API User ID and Token, which can be obtained in the Account page.

Downloading Cloud Generated Backtest JSON Files:
>>> from quantconnect.api import Api
>>> from json import dump
>>> api = Api(your-user-id, your-token)
>>> data = api.read_backtest(project-id, backtest-id)
>>> with open("./json/sample.json", 'w+') as fp:
>>>    json.dump(data['result'], fp, ensure_ascii=False)
Downloading Cloud Generated Backtest JSON Files (Manually):

You can manually download the backtest result file and place the file in the location configured in the config.json file.

You can update your report description by clicking on the Project Description button in your project panel.

Customizing Report Contents

The report can contain a description of the strategy. This is set either in the config.json file or via the command line argument --strategy-description. An example config.json configuration is provided below.

{
  "data-folder": "../../../Data",
  "strategy-name": "Example Algo (FX + Equity) Strategy",
  "strategy-version": "v1.2.0",
  "strategy-description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
  "live-data-source-file": "",
  "backtest-data-source-file": "example_algo_fx.json",
  "report-destination": "Report.html",

  ...
}

We recommend that you use the existing config.example.json and rename it to config.json once you have finished editing the file. Please rebuild the project on rename or if you make any changes to the configuration so that the file is copied into the binary output path.

Interpreting Report Charts

Cumulative Return

This chart shows the cumulative returns for your strategy in blue for backtesting, orange for live trading, and the benchmark in gray.

Returns per Trade

This chart shows a histogram showing the distribution of returns per trade over the algorithm's backtesting or live trading period.

Top 5 Drawdown Periods

This chart shows the drawdown of each day. A certain day's drawdown is defined as the percentage of loss compared to the maximum value before this day. The drawdowns are calculated based on daily data. The top 5 drawdown periods are marked in the chart with different colors.

Monthly Returns

This chart shows the return of each month. We convert original price series into monthly series and calculate the returns of each month. The green color indicates positive return, the red color indicates negative return, and the greater the loss is, the darker the color is; the yellow color means the gain or loss is rather small; the white color means the month is not included in the backtest period. The values in the cells are in percentage.

Annual Returns

This chart shows the return of each year. We calculate the total return within each year, shown by the blue bars. The red dotted line represents the average of the annual returns.

Crisis Events

This group of charts shows the behaviors of both your strategy and the benchmark during a certain historical period. We set the value of your strategy the same as the benchmark at the beginning of each crisis event, and the lines represent the cumulative returns of your strategy and benchmark from the beginning of this crisis event. The report only draws the crisis event charts whose periods are covered by your strategy.

Asset Allocations

The asset allocation charts show a time-weighted average of each asset to your portfolio. When a certain asset has a very small percentage and is too small to be shown in the pie chart, it will be incorporated into an "Others" category. The value of the percentage could be either positive or negative.

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

Did you find this page helpful?

Contribute to the tutorials: