Reporting

Metrics

This table contains definitions for metrics to be reported in the output graphs. A metric is a special type of variable that does not influence the progress of the simulation, but instead depends exclusively on its results. Therefore, they can only be used for reporting purposes. For example, this could be the cumulative amount of fees earned by the protocol.

Metrics can be aggregates of the results of the simulation through time. For this reason, there are special methods available in the formulae to deal with these aggregations, described in the Formulae section.

To complete the table, add one new line per metric you want to include, with the following information in the corresponding column for each:

Reference (Alphanumerical): a unique identifier to this metric for use within the spreadsheet. It will not be displayed anywhere in the dashboard. It must start with a letter and contain only letters, underscores (_), or numbers. The reference must be unique and is not case sensitive. It is a good practice to start with "ME_..." for the reference.
Display Name (Text): Name of the metric, and how it will be displayed in the dashboard.
Formula (Formula): mathematical expression defining the value of the metric throughout the simulation.

Events

This table contains custom-defined "events" reported in the output graphs. An event is a situation that happens at a specific time in the simulation and, like Metrics, can only be used for reporting purposes. For example, an event could be defined as the moment that the treasury runs out of tokens, or as the time that monthly revenue reaches a certain milestone.

Like other parameters, events are defined as a formula. The event will be interpreted to happen at the first simulation step where the formula evaluates to "true". If the formula is always "false" for the whole simulation, it will interpreted as the event not taking place. For example, if there is an agent that represents the protocol treasury named "A_TREASURY", the event with formula A_TREASURY.total_tokens = 0 would trigger the first time step in the simulation when the treasury has run out of tokens.

Note that the Event formula does not just work with boolean "true" or "false" results. In general, any result value higher than 0 will be interpreted as "true", and any value of 0 or lower will be interpreted as "false".

In order to understand how to represent event in graphs, please refer to the Dashboard config section.

To complete the events table, add one new line per event you want to include, with the following information in the corresponding column for each:

Reference (Alphanumerical): a unique identifier to this event for use within the spreadsheet. It will not be displayed anywhere in the dashboard. It must start with a letter and contain only letters, underscores (_), or numbers. The reference must be unique and is not case sensitive. It is a good practice to start with "E_..." for the reference.
Display Name (Text): Name of the event, and how it will be displayed in the dashboard.
Formula (Formula): mathematical expression defining the moment that the event happens, as the first time that the formula evaluates to "true".

Graphs

This table is used to define custom graphs for the dashboard. Graphs plot variables and metrics in the Y axis against simulation time in the X axis.

There are some special graphs defined for every tokenomics simulation that you do not need to define, described in the Special Graphs subsection.

To complete the table, add one new line per graph you want to define, with the following information in the corresponding column for each:

Note that the display order of graphs on the dashboard will be specified in the sheet Dashboard Config, you do not need to worry about the order in this sheet.

Reference (Alphanumerical): a unique identifier to this metric for use within the spreadsheet. It will not be displayed anywhere in the dashboard. It must start with a letter and contain only letters, underscores (_), or numbers. The reference must be unique and is not case sensitive. It is a good practice to start with "G_..." for the reference.
Display Name (Text): name of the graph.
Type (one of “Line”, “Bar”, or “Area”): type of graph. See further examples in the Graph types subsection.
Axis Y1 (list of References): values to be plotted on the Y axis on the left. They must be references to either Variables, Flows, or Metrics. If multiple variables are to be plotted, they should be separated by ";", like Y1;Y2;Y3.
Axis Y1 name (Text): title of the Y axis on the left.
Axis Y2 (list of References, optional): values to be plotted on the Y axis on the right. They must be references to either Variables, Flows, or Metrics. If multiple variables are to be plotted, they should be separated by ";", like Y1;Y2;Y3.
Axis Y2 name (Text, optional): title of the Y axis on the right.
Legend (list of texts, optional): list of names for the values plotted on the left and right axes, separated by “;”. Mandatory for those cases where there are multiple variables. The first names will be assigned to the variables on the "Axis Y1", in the order specified in "Axis Y1"; after that, variables on the "Axis Y2" will be assigned.
Color (list of hex colors, optional): color hex codes to use for the plots. If left empty, colors will be assigned automatically. If introduced, there should be as many hex codes in the list as variables to be plotted in the Y axes. Example: #FFFFFF; #000000.
Sampling Frequency (one of "Time Step", "Day", "Week", "Month", "Year", optional): the distance between the points in the X axis. "Time Step" is the option by default, but if the graph plots a metric that has been grouped by a period of time, e.g. Y1.group(month, sum), then it is visually better to use that same sampling frequency in the graph. If left empty, the time step will be used, plotting one point per step in the simulation.
Axis X min (Number, Optional): leftmost limit for the X axis. If left empty, the starting time of the simulation will be used.
Axis X max (Number, Optional): rightmost limit for the X axis. If left empty, the final time of the simulation will be used.
Axis Y1 min (Number, Optional): lower limit for the Y1 axis. If left empty, it will be adjusted automatically depending on the values plotted.
Axis Y1 max (Number, Optional): upper limit for the Y1 axis. If left empty, it will be adjusted automatically depending on the values plotted.
Axis Y2 min (Number, Optional): lower limit for the Y2 axis. If left empty, it will be adjusted automatically depending on the values plotted.
Axis Y2 max (Number, Optional): upper limit for the Y2 axis. If left empty, it will be adjusted automatically depending on the values plotted.

Graph types

There are currently three graph types available:

Line plot

A standard plot of a variable against time. Can include multiple lines (variables) in the vertical axis, and can divide them between the left (Y1) and right (Y2) axes, as in the following example:

Bar plot

Useful for plotting time-aggregated quantities, such as the total amount of vesting per month.

Area plot

Useful for plotting any kind of additive variables, such as the different buying and selling pressures over the token, making it easy to follow trends and comparisons between different variables.

Predefined graphs

There are some special predefined graphs that are always available without need of defining them manually. These are graphs common and useful to most token economies.

Predefined Graph Reference

Predefined Graph	Reference
Token price and market cap	`token_value_and_market_cap`
Monthly vesting	`monthly_vesting`
Accumulated vesting	`accumulated_vesting`
Net buying pressure, in tokens	`monthly_buying_pressure`
Net buying pressure, in USD	`monthly_usd_buying_pressure`
Accumulated buying pressure, in tokens	`accumulated_buying_pressure`
Accumulated buying pressure, in USD	`accumulated_usd_buying_pressure`
Token supply	`token_supply`
Distribution of circulating supply	`distribution_of_circulating_supply`
Annualised inflation	`annualized_inflation`

Token price and market cap

token_value_and_market_cap

Monthly vesting

monthly_vesting

Accumulated vesting

accumulated_vesting

Net buying pressure, in tokens

monthly_buying_pressure

Net buying pressure, in USD

monthly_usd_buying_pressure

Accumulated buying pressure, in tokens

accumulated_buying_pressure

Accumulated buying pressure, in USD

accumulated_usd_buying_pressure

Token supply

token_supply

Distribution of circulating supply

distribution_of_circulating_supply

Annualised inflation

annualized_inflation

Token price and market cap

A line plot with the token price over time on the left axis and the Market Cap and Fully Diluted Valuation on the right axis.

Monthly vesting

A bar plot with monthly frequency, with all of the entities defined in the Vesting table and the amount of tokens unlocked from vesting each month.

Accumulated vesting

An area plot with monthly frequency, with all of the entities defined in the Vesting table and the total amount of tokens unlocked from vesting up until that month.

Net buying pressure, in tokens

An area plot with monthly frequency, showing the buying pressure and selling pressure over the token market originated from all of the various sources in the economy in that month, in terms of number of tokens.

Net buying pressure, in USD

Accumulated buying pressure, in tokens

An area plot with monthly frequency, showing the total buying pressure and selling pressure over the token market originated from all of the various sources in the economy up to that month, in terms of number of tokens.