Skip to main content

​
Building models

Models can be edited by Admin users in the Model Editor using a YAML-based scripting language.
  • Open the Model Editor by clicking on Edit/Test besides the model name
The YAML script constructs carbon accounting models using a tree of interconnected nodes, where each node performs a calculation or holds a value. These nodes are organized in a hierarchical structure.
Example Model
nexus_nodes_attributes:
- name: Output Node
  operator: summation
  data_point_type: output-slug
  nexus_nodes_attributes:
  - name: Intermediate Calc A
    operator: summation
    nexus_nodes_attributes:
    - name: Data Input 1
      data_point_type: data-point-slug
    - name: Constant
      constant: 100
  - name: Intermediate Calc B
    operator: difference
    nexus_nodes_attributes:
    - name: Static Input
      order: 0
      data_point_type: static-input-slug
    - name: Data Input 2
      order: 1
      data_point_type: data-point-2-slug
This is the equivalent of writing the following equation: (Datapoint1+100)+(α−Datapoint2)=Output(Datapoint1 + 100) + (\alpha - Datapoint2) = Output As a best practice, Validate the model you have built, and check the results in the Console before saving the model.

​
Editing models

Saving the model updates its version. New model versions do not affect the calculations of past accounting batches, only new calculations run after the version has been created.

​
Defining new nodes

Nodes can be added to the model to represent specific variables in the accounting equations. Each node can:
  • Receive a value from a data source (data_point_type)
  • Use a constant/mapped value from a library, or
  • Have its value calculated from child nodes through the defined operator
    - name: Input Node
      data_point_type: {{input-data-point-slug}}
    - name: Static Input Node
      data_point_type: {{static-input-slug}}
    - name: Constant Node
      constant: {{value}}
See Reference below for the full list of parameters that can be defined on each node.

​
Units

Units are not always required to be defined on nodes, but are very helpful for legibility especially when data is run through operator expressions. Use output_unit to define the expected result unit:
Example with units
nexus_nodes_attributes:
- name: Calculated EF
  output_unit: tCO2e/tonne
  operator: quotient
  nexus_nodes_attributes:
  - name: Emissions
    order: 0
    output_unit: kgCO2e  // note that Mangrove supports unit conversion above
    data_point_type: emissions-datapoint-slug
  - name: Mass
    order: 1
    output_unit: U.S. ton  // note that Mangrove supports unit conversion above
    data_point_type: mass-datapoint-slug
See Reference below: units have to conform to the supported syntax from the Unitwise library. Mismatched units between inputs on the same tier of nodes can result in errors unless explicitly converted upstream.

​
Testing models

Models can be tested by running them with a set of inputs to confirm the calculations. How to test the models:
  • Open the Model Editor by clicking on Edit/Test besides the model name
  • Switch to Test Model
  • Define a time range (this is necessary for certain calculations that consider duration), enter values for the model’s required inputs, and Run Test
  • Review the output calculations in the Console

​
Reference

Below is the full list of fields that can be configured on nodes within a model.
​
name
required
Name of the variable
​
output_unit
Unit. We use the Unitwise library to interpret units. Here’s a list of library-supported units.
​
ghg
Specifies whether the values of that node represent a type of GHG calculation. Possible values: co2e
​
order
Specifies the node’s order in the parent node’s equation
​
nexus_nodes_attributes
Defines a new tier of child nodes.
​
data_point_type
Specifies the datapoint slug that the nodes is associated with, defining the node as either an input node that expects incoming data, or an input node tied to a Static Input.
​
operator
Operation performed on the child nodes.
OperatorFunction
Keisan expressionsExpressions supported by the Keisan Ruby library are acceptable. A list can be found here.
summationSums all child node values
differenceSubtracts subsequent values from the first. Child nodes have to be set in the right order.
productMultiplies all child node values
quotientDivides subsequent values from the first. Child nodes have to be set in the right order.
maxFinds the maximum value across all child node values
minFinds the minimum value across all child node values
averageFinds the average of all child node values
count
durationSpecial operator used to convert the time range of the incoming datapoint into a duration
mapMaps a value from an linked library
​
constant
Sets a constant value on the node.
​
should_aggregate
default:"true"
If set to false, the node’s computation behaviour will change such that it will always return an array in which the computation is applied to each element of the input. If the node is using data points as input, the array will have the same length as the number of data points found for that data flow. If the node is using multiple child nodes as input, the operator is applied piece-wise across each child’s output array to derive one output array.
⌘I