Lean CLI

Reports

Introduction

The lean report command in the Lean CLI is a wrapper around the LEAN Report Creator. The LEAN Report Creator is a program included with LEAN which allows you to quickly generate polished, professional-grade reports of your backtests and live trading results. We hope that you can use these reports to share your strategy performance with prospective investors.

Generate Reports

Follow these steps to generate a report of a trading algorithm:

  1. Open a terminal in the organization workspace that contains the project.
  2. Run lean report to generate a report of the most recent backtest.
    $ lean report
    20210322 20:03:48.718 TRACE:: QuantConnect.Report.Main(): Parsing source files...backtest-data-source-file.json,
    20210322 20:03:51.602 TRACE:: QuantConnect.Report.Main(): Instantiating report...
    Successfully generated report to './report.html'
    
    By default, the generated report is saved to . / report.html, although you can change this by providing a custom path with the --report-destination <path> option. To generate a report of a backtest that is not the most recent one, you can use the --backtest-results <path> option to specify the path to the backtest results JSON file to generate a report for it. 
  3. Open the generated report in the browser and inspect its results.

You can also configure the following optional details:

DetailDescription
Strategy nameThis name is displayed in the top-right corner of each page and can be configured using --strategy-name <value>. This value defaults to the name of the project directory.
Strategy versionThis version is displayed next to the strategy name and can be configured using --strategy-version <value>.
Strategy descriptionThis description is displayed underneath the "Strategy Description" header on the first page and can be configured using --strategy-description. This value defaults to the description stored in the project's configuration.
Live resultsThese results are displayed over the backtest results and can be configured using --live-results <path>. The provided path must point to a JSON file containing live results. For example, --live-results "My Project/live/2022-03-17_10-53-12/L-3578882079.json".

Key Statistics

The top of the backtest report displays statistics to summarize your algorithm's performance. The following table describes the key statistics in the report:

StatisticDescription
Runtime DaysThe number of days in the backtest or live trading period.
TurnoverThe percentage of the algorithm's portfolio that was replaced in a given year.
CAGRThe annual percentage return that would be required to grow a portfolio from its starting value to its ending value.
MarketsThe asset classes that the algorithm trades.
Trades per dayThe total number of trades during the backtest divided by the number of days in the backtest. Trades per day is an approximation of the algorithm's trading frequency.
DrawdownThe largest peak to trough decline in an algorithm's equity curve.
Probabilistic SRThe probability that the estimated Sharpe ratio of an algorithm is greater than a benchmark (1).
Sharpe RatioA measure of the risk-adjusted return, developed by William Sharpe.
Information RatioThe amount of excess return from the risk-free rate per unit of systematic risk.
Strategy CapacityThe maximum amount of money an algorithm can trade before its performance degrades from market impact.

Returns

The backtest report displays charts to show the algorithm's returns per trade, per day, per month, per year, and the cumulative returns over the backtest.

Returns per Trade

Distribution curve of returns per trade

This chart displays a histogram that shows the distribution of returns per trade over the backtesting period.

Daily Returns

Daily return time series bar chart

This chart displays the returns of each day. Blue bars represent profitable days and gray bars represent unprofitable days.

Monthly Returns

Monthly return heat map

This chart displays the return of each month. We convert the original equity curve series into a monthly series and calculate the returns of each month. Green cells represent months with a positive return and red cells represent months with a negative return. Months that have a greater magnitude of returns are represented with darker cells. Yellow cells represent months with a relatively small gain or loss. White rectangles represent months that are not included in the backtest period. The values in the cells are percentages.

Annual Returns

Bar chart of annual return

This chart displays the return of each year. We calculate the total return within each year and represent each year with a blue bar. The red dotted line represents the average of the annual returns.

Cumulative Returns

Cumulative return equity curve

This chart displays the cumulative returns of your algorithm. The blue line represents your algorithm and the gray line represents the benchmark.

Asset Allocation

Asset allocation pie chart

This chart displays a time-weighted average of the absolute holdings value for each asset that entered your portfolio during the backtest. When an asset has a percentage that is too small to be shown in the pie chart, it is incorporated into an "Others" category.

Drawdown

Drawdown underwater line plot with analysis

This chart displays the peak-to-trough drawdown of your portfolio's equity throughout the backtest period. The drawdown of each day is defined as the percentage loss since the maximum equity value before the current day. The drawdowns are calculated based on daily data. The top 5 drawdown periods are marked in the chart with different colors.

Rolling Statistics

The backtest report displays time series for your portfolio's rolling beta and Sharpe ratio.

Rolling Portfolio Beta

Rolling beta line chart

This chart displays the rolling portfolio beta over trailing 6 and 12 month periods. The light blue line represents the 6 month period and the dark blue line represents the 12 month period.

Rolling Sharpe Ratio

Rolling Sharpe ratio line chart

This chart displays the rolling portfolio Sharpe ratio over trailing 6 and 12 month periods. The light blue line represents the 6 month period and the dark blue line represents the 12 month period.

Exposure

The backtest report displays time series for your portfolio's overall leverage and your portfolio's long-short exposure by asset class.

Leverage

Leverage level chart over algorithm running period

This chart displays your algorithm's utilization of leverage over time.

Long-Short Exposure By Asset Class

Long-short exposure level chart over algorithm running period

This chart displays your algorithm's long-short exposure by asset class over time.

Crisis Events

Charts of performance under crisis events

This set of charts displays the cumulative returns of your algorithm and the benchmark during various historical periods. The blue line represents the cumulative returns of your algorithm and the grey line represents the cumulative return of the benchmark. The report only contains the crisis event that occurred during your algorithm's backtest period. The following table shows the crisis events that may be included in your backtest report:

Crisis NameStart DateEnd Date
DotCom Bubble 20002/26/20009/10/2000
September 11, 20019/5/200110/10/2001
U.S. Housing Bubble 20031/1/2003
2/20/2003
Global Financial Crisis 200710/1/2007
12/1/2011
Flash Crash 20105/1/2010
5/22/2010
Fukushima Meltdown 20113/1/2011
4/22/2011
U.S. Credit Downgrade 20118/5/2011
9/1/2011
ECB IR Event 20129/5/2012
10/12/2012
European Debt Crisis 201410/1/2014
10/29/2014
Market Sell-Off 20158/10/2015
10/10/2015
Recovery 2010-20121/1/2010
10/1/2012
New Normal 2014-20191/1/2014
1/1/2019
COVID-19 Pandemic 20202/10/2020
9/20/2020
Post-COVID Run-up 2020-20214/1/2020
1/1/2022
Meme Season 20211/1/2021
5/15/2021
Russia Invades Ukraine 2022-20232/1/2022
1/1/2024
AI Boom 2022-Present11/30/2022
Present

Parameters

This section of the report shows the name and value of all the parameters in your project.

Customize Reports

To create custom reports, customize the HTML and CSS.

Customize the Report HTML

The Report / template.html file in the LEAN GitHub repository defines the stucture of the reports you generate. To override the HTML file, add a new HTML file to your local machine. If you add it to your organization workspace, don't name it report.html because that's the default name and location of the reports you generate. To include some of the information and charts that are in the default report, use the report keys in the Report / ReportKey.cs file in the LEAN GitHub repository. For example, to add the Sharpe ratio of your backtest to the custom HTML file, use {{$KPI-SHARPE}}.

To include the crisis event plots in your report, add the {{$HTML-CRISIS-PLOTS}} key and then define the structure of the individual plots inside of <!--crisis and crisis-->. Inside of this comment, you can utilize the {{$TEXT-CRISIS-TITLE}} and {{$PLOT-CRISIS-CONTENT}} keys. For example, the following HTML is the default format for each crisis plot:

<!--crisis
<div class="col-xs-4">
    <table class="crisis-chart table compact">
        <thead>
        <tr>
            <th style="display: block; height: 75px;">{{$TEXT-CRISIS-TITLE}}</th>
        </tr>
        </thead>
        <tbody>
        <tr>
            <td style="padding:0;">
                <img src="{{$PLOT-CRISIS-CONTENT}}">
            </td>
        </tr>
        </tbody>
    </table>
</div>
crisis-->

To include the algorithm parameters in your report, add the {{$PARAMETERS}} key and then define the HTML element inside of <!--parameters and parameters-->. Inside of this comment, you can use special keys {{$KEY<parameterIndex>}} and {{$VALUE<parameterIndex>}}, which represent the key and value of a single parameter. For example, the following HTML is the default format for the parameters element:

<!--parameters
<tr>
    <td class = "title"> {{$KEY0}} </td><td> {{$VALUE0}} </td>
    <td class = "title"> {{$KEY1}} </td><td> {{$VALUE1}} </td>
</tr>
parameters-->

In the preceding example, {{$KEY0}} is the name of the first parameter in the algorithm and {{$VALUE0}} is its value.

To generate the report with your custom HTML file, run lean report --html <pathToCustomHTMLFile>.

Customize the Report CSS

The Report / css / report.css file in the LEAN GitHub repository defines the style of the reports you generate. To override the stylesheet, add a new CSS file to your local machine.

To generate the report with your custom CSS file, run lean report --css <pathToCustomCSSFile>.

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: