How to design new reports?

[Max]

So, you decided to design a new report template. Let’s start with preparing a convenient workplace

First Steps

The best way to start is by creating a copy of one of the built-in templates, then edit it in a way you like. Please don’t edit default templates because they will be automatically replaced with their default content on the next product update. That’s why you should go with the copy.

Click Reports - Manage Report Templates menu item:

Create a copy of a file you want to edit.

Please note that template names have double extentions: Summary.html.twig
twig extention means that you can edit this file as a twig template;
html extention means that after you run this template, an output file will get “html” as its default extention.

You can edit these Twig files with any text editor but I would highly recommend you to download and install VS Code - a freeware code editor that will make it much easier. You should also install TWIG Pack extention that will highlight the code in a proper way.

Open the file in the editor. Now you can edit it and run reports immediately after you save changes you make. I recommend you to assign a shortcut to your new report so that you can run it without the need to go into the menu.

[Max]

Twig Language Reference

Twig is an easy template language. You can learn it in a few minutes, I guarantee it

There are just a few simple expressions you need to know:

Insert a variable

Just wrap a variable name into {{ }} like {{ stats.balance }} - it will be replaced with the actual account balance 10000.00. You can find the list of all available variables below.

Format a variable

Place a | sign after the variable name with a filter name after it: {{ stats.balance | usd }} will output account balance formatted as $10 000.00

You can also make a chain of such filters: {{ order.swap | emptyifzero | usd }} will first empty the output value if it’s zero, then format it as money. If you don’t place emptyifzero here, you will always get $0.00 in your reports even if you turned swaps off.

You can find the list of all available filters below.

Remove Extra Spaces

Whenever you design text reports, you don’t want extra lines and spaces that may occur because of you trying to prettify your code formatting. There is an easy way to do it: just add - at the beginning or at the end of a Twig tag to remove extra whitespaces in the corresponding locations:

{{- stats.balance | usd }} will remove all whitespaces before the balance;
{{ stats.balance | usd -}} will remove all whitespaces after the balance;
{{- stats.balance | usd -}} will remove whitespaces both before and after the balance.

Conditional Expressions

Everything you wrap into {{ if }} {{ else }} {{ end }} will be inserted into the report only if the condition is true.

For example:

{{ if stats.balance < 10000 }}
Balance is lower than $10000
{{ else }}
Balance is higher than $10000
{{ end }}

will output the correct balance value string.

You can also use || and && as logical OR and AND operators like:

{{ if stats.initial_balance <= 10000 && stats.balance >= 20000 }}
I have just doubled it!
{{ end }}

Enumerating Variables

You can go through array variables one-by-one, formatting their values:

{{ for order in orders }}
{{ order.profit | usd }}
{{ end }]

will output profits of each order, one after the other.

That’s it!

With the above expressions, you can design literally any type of report you need.

[Max]

Built-In Variables

So, you know how to insert variables, let’s find what variables are available for you.

Please note that if you need any variable I missed, don’t hesitate to request it in the Feature Requests section of this forum. It’s absolutely easy for me to add them and you don’t need to wait for a long time.

Orders and Trades

Let’s start with orders. There are two variables with the list of orders available:
orders - the complete list of orders including limit/stop orders that weren’t filled yet and those that were opened but haven’t yet closed.
trades - actual trades - all the orders that were closed after being opened.

Each of the orders you enumerate with {{ for order in orders }} or {{ for order in trades }} will provide you with the following variables:
order.id - order id
order.created - order creation date/time
order.opened - when this order was filled
order.was_open - if this order was opened?
order.is_open - if this order is open at the moment?
order.opened_long - when this order was opened, as a long value, for sorting
order.closed - when this order was closed
order.is_closed - if this order was closed?
order.closed_long - when this order was closed, as a long value, for sorting
order.closed_balance - account balance after the order was closed
order.closed_equity - account equity after the order was closed
order.type - order type
order.ticker - order ticker
order.size - order size in lots
order.size_units - order size in account currency
order.size_lots - order size in lots
order.target - target price for limit and stop orders
order.open - order open price
order.close - order close price
order.stop_loss - order stop loss price
order.stop_loss_hit - was this order closed because of the stop loss?
order.take_profit - order take profit price
order.take_profit_hit - was this order closed because of the take profit?
order.comission - order comission
order.swap - order swap
order.profit - order profit, in account currency
order.profit_pips - order profit, in pips
order.max_profit_pps - max order profit, in pps
order.max_loss_pps - max order loss, in pps
order.comment - your comment to the order
order.error - an error indicating why this order failed, something like NotEnoughMargin
order.has_error - did this order fail?

Stats

Here you can find summary simulation stats:
stats.initial_balance - initial account balance
stats.balance - account balance
stats.equity - account equity
stats.total_profit - total profit
stats.total_profit_rate - total profit as a rate to initial account balance
stats.released_profit - released profit
stats.unreleased_profit - unreleased profit
stats.margin - margin
stats.free_margin - free margin
stats.gross_profit - gross profit
stats.gross_loss - gross loss
stats.trades - total number of trades
stats.profit_factor - profit factor
stats.expected_payoff - expected payoff
stats.absolute_drawdown - absolute drawdown
stats.absolute_drawdown_ratio - absolute drawdown ratio
stats.max_drawdown - max drawdown
stats.max_drawdown_ratio - max drawdown ratio
stats.winning_trades - number of winning trades
stats.winning_trades_ratio - winning trades ratio
stats.losing_trades - number of losing trades
stats.losing_trades_ratio - losing trades ratio
stats.long_trades - total number of long trades
stats.long_trades_ratio - a ratio of long trades to total trades
stats.winning_long_trades - number of winning long trades
stats.winning_long_trades_ratio - ratio of winning long trades to total long trades
stats.losing_long_trades - number of losing long trades
stats.losing_long_trades_ratio - ratio of losing long trades to total long trades
stats.short_trades - total number of short trades
stats.short_trades_ratio - a ratio of short trades to total trades
stats.winning_short_trades - number of winning short trades
stats.winning_short_trades_ratio - ratio of winning short trades to total short trades
stats.losing_short_trades - number of losing short trades
stats.losing_short_trades_ratio - ratio of losing short trades to total short trades
stats.largest_winning_trade - largest winning trade profit
stats.average_winning_trade - average winning trade profit
stats.maximum_consecutive_wins - maximum consecutive wins in a row
stats.maximum_consecutive_wins_profit - total profit of the maximum consecutive winning series
stats.maximum_consecutive_proft - maximum profit of a consecutive wininning series
stats.maximum_consecutive_proft_trades - a length of the consecutive wininning series with a maximum profit
stats.average_consecutive_wins - average consecutive wins
stats.average_consecutive_wins_profit - average profit of consecutive winning series
stats.largest_losing_trade - largest losing trade
stats.average_losing_trade - average losing trade
stats.maximum_consecutive_losses - a length of the maximum consecutive losing series
stats.maximum_consecutive_losses_loss - total loss of the maximum consecutive losing series
stats.maximum_consecutive_loss - maximum loss of consecutive losing series
stats.maximum_consecutive_loss_trades - a length of the consecutive losing series with the maximum loss
stats.average_consecutive_losses - average length of consecutive losing series
stats.average_consecutive_losses_loss - average loss of consecutive losing series

Simulation
Here are general simulation parameters:
simulation.name - simulation name
simulation.start_date - start simulation date
simulation.end_date - end simulation date
simulation.leverage - simulation leverage
simulation.commission - simulation commission per 1,000,000 units

Personal Progress
Your personal learning progress can be easily accessed via a set of unified variables:
progress.summary - your summary trading stats since the very beginning
progress.today - your trading stats for today
progress.history - all your trading stats, day-by-day, you can iterate over it in the same way as you iterate over orders in simulation reports

Each of these variables provides you with a set of sub-variables. If you want to look at your summary stats, it will look in the following way:
progress.summary.id - id of a day
progress.summary.days - total number of days in case of summary stats
progress.summary.total_profit - total profit/loss
progress.summary.gross_profit - gross profit
progress.summary.gross_loss - gross loss
progress.summary.trades - total number of trades
progress.summary.profit_factor - profit factor
progress.summary.expected_payoff - expected payoff
progress.summary.winning_trades - number of winning trades
progress.summary.winning_trades_ratio - winning trades ratio to the total number of trades
progress.summary.losing_trades - number of losing trades
progress.summary.losing_trades_ratio - ratio of losing trades to the total number of trades
progress.summary.long_trades - number of long trades
progress.summary.long_trades_ratio - ratio of long trades to the total number of trades
progress.summary.winning_long_trades - number of winning long trades
progress.summary.winning_long_trades_ratio - ratio of winning long trades to the total number of long trades
progress.summary.losing_long_trades - number of losing long trades
progress.summary.losing_long_trades_ratio - ratio of losing long trades to the total number of long trades
progress.summary.short_trades - number of short trades
progress.summary.short_trades_ratio - ratio of short trades to the total number of trades
progress.summary.winning_short_trades - number of winning short trades
progress.summary.winning_short_trades_ratio - ratio of winning short trades to the total number of short trades
progress.summary.losing_short_trades - number of losing short trades
progress.summary.losing_short_trades_ratio - ratio of losing short trades to the total number of short trades
progress.summary.screen_time - total screen time in hours

[Max]

Filters

Here are filters you can apply to format variables:

usd - format a number in account currency, like $10 000.00

emptyifzero - makes a variable emtpy if it’s equal to zero. You should use it whenever you don’t want to get a lot of zeros in your reports

lpadding - add a padding to the left of the number: {{ variable | lpadding 5 }} will add extra spaces to the left of the variable so that its total length is equal to 5. It’s great for formatting text reports.

rpadding - add a padding to the right of the number: {{ variable | rpadding 5 }} will add extra spaces to the right of the variable so that its total length is equal to 5. It’s great for formatting text reports.

comma - replaces . with ,

count - format variable as a count with spaces 10000 will become 10 000

percents - formats variable as percents. Great for variables with names ending with ratio

precision - formats variable as a number with a given precision. If a variable value is 10.023142, {{ variable | precision 2 }} will output 10.02

If you need any filter I missed, don’t hesitate to request it in the Feature Requests section of this forum. It’s absolutely easy for me to add them and you don’t need to wait for a long time.

singleline - replaces line breaks in multi-line strings with spaces. Great for formatting multi-line comments in text reports, to avoid breaking csv formatting.

htmlline - replaces line breaks in multi-line strings with HTML line breaks. Great for formatting multi-line comments in HTML reports.

replace - replaces one string with another. If a variable equals to $123,{{ variable | replace $ € }} will output €123