What you’ll learn in this lesson:
- Break methodology formulas into discrete calculation steps
- Understand the Model Editor’s node tree architecture
- Use operators (summation, product, quotient, Keisan) to build calculations
- Distinguish intermediate calculations from final outputs
mass × carbon_content × 3.67. Real-world methodologies require multi-step calculations — chains of intermediate values that feed into a final output. This lesson teaches you how to structure those calculations in Mangrove’s Model Editor.
How calculations work in Mangrove
Mangrove’s Model Editor represents calculations as a node tree. Each node is either an input (data from events, static values, or constants) or a calculated node that combines its children using an operator.A node tree is hierarchical — each node can have child nodes, and the calculation flows from the leaves (inputs) up to the root (final output). The Model Editor uses a YAML-based scripting interface to define this tree.
Node types
There are three categories of nodes in the Model Editor:Input Nodes
- Datapoint references — values from events
- Static inputs — fixed values from the resource library
- Constants — hardcoded values (e.g., 3.67 for CO2-to-carbon ratio)
Calculated Nodes
- Combine child nodes using an operator
- Can be intermediate (feed into other calculations)
- Or final output (produce the batch result)
Output Nodes
- A calculated node with a
data_point_typeassigned - Its value becomes a batch output datapoint
- Must match the slug expected by the batch type
Operators
Operators define how a node combines its children. The most common operators are:- Simple operators
- Keisan expressions
For straightforward math, use
summation, difference, product, or quotient. Each operates on the node’s children in order.Example — product operator: A node with operator product and three children (mass, carbon_pct, factor) computes: mass × carbon_pct × factor.Breaking formulas into steps
Real-world methodology formulas are often written as a single equation, but in Mangrove you break them into discrete steps. This makes models easier to test, debug, and audit.1
Identify the final output
What is the batch’s primary output? For Mangrove Biochar, it’s net carbon delivered (tCO2e). This becomes the root of your node tree.
2
Work backwards to find intermediate values
What calculations feed into the final output? Each intermediate value becomes its own node. For example,
net_carbon = gross_carbon - total_emissions has two intermediate inputs.3
Map inputs to the leaves
Each leaf node is either an event datapoint, a static input, or a constant. These are the raw data that enters the calculation.
4
Choose operators for each step
Select the appropriate operator for each calculated node. Prefer simple operators over Keisan when possible — they’re easier to read and debug.
Execution order and dependencies
The Model Editor evaluates nodes bottom-up — leaf nodes (inputs) are resolved first, then their parents, up to the root (output). You don’t need to specify execution order; the tree structure defines it.Circular dependencies are not allowed. If node A depends on node B, and node B depends on node A, the model will fail validation. The Model Editor catches this when you save.
Testing your model
After building a model, use the Console in the Model Editor to test it:- Select a time range that includes test events
- Review the calculated values at each node
- Verify intermediate outputs match your expectations
- Confirm the final output produces the correct result
Check your understanding
What is the difference between an intermediate calculation and a final output?
What is the difference between an intermediate calculation and a final output?
An intermediate calculation is a node whose value feeds into another calculation — it exists to break complex formulas into manageable steps. A final output is a calculated node with a
data_point_type assigned — its value becomes a batch output datapoint visible in the batch record.When should you use a Keisan expression instead of a simple operator?
When should you use a Keisan expression instead of a simple operator?
Use Keisan when the calculation requires logic that simple operators can’t express — such as conditionals (if/else), min/max comparisons, rounding, or complex multi-variable formulas. For straightforward arithmetic (add, subtract, multiply, divide), prefer the built-in operators for clarity.
Why should you break a single methodology formula into multiple calculation steps?
Why should you break a single methodology formula into multiple calculation steps?
Breaking formulas into steps makes models easier to test (you can verify each intermediate value), easier to debug (you can identify exactly where a calculation goes wrong), and easier to audit (verifiers can trace each step back to source data). It also enables reuse — intermediate values can feed into multiple downstream calculations.
Next, you’ll learn how to expand your data model with additional event types in Lesson 2.2: Expanding Your Data Model.