> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mangrovesystems.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 2.2: Expanding Your Data Model

> Add new event types to capture more operational data, connect multiple event types in a single model, and handle unit conversions and validation.

<Panel>
  <Card title="Accounting Academy" className="accounting-academy-card">
    <div className="accounting-academy-content">
      <Steps className="my-0">
        <Step title="MODULE 1: Fundamentals" icon="bookmark" iconType="solid" stepNumber={1} titleSize="p">
          * [1.1: Core Concepts & the Data Lifecycle](/accounting-academy/module-1/1-1-core-concepts-data-lifecycle)
          * [1.2: Translating Methodologies to Mangrove](/accounting-academy/module-1/1-2-translating-methodologies-to-mangrove)
          * [1.3: Events and Datapoints](/accounting-academy/module-1/1-3-events-and-datapoints)
          * [Exercise: Design and Build](/accounting-academy/module-1/1-exercise-design-and-build)
        </Step>

        <Step title="MODULE 2: Calculations" icon="bookmark" iconType="solid" stepNumber={2} titleSize="p">
          * [2.1: Calculation Architecture](/accounting-academy/module-2/2-1-calculation-architecture)
          * [2.2: Expanding Your Data Model](/accounting-academy/module-2/2-2-expanding-your-data-model)
          * [Exercise: Multi-Step Calculations](/accounting-academy/module-2/2-exercise-multi-step-calculations)
        </Step>

        <Step title="MODULE 3: Batch Partitioning & LCA" icon="bookmark" iconType="solid" stepNumber={3} titleSize="p">
          * [3.1: What Is a Batch?](/accounting-academy/module-3/3-1-what-is-a-batch)
          * [3.2: Batch Partitioning Strategies](/accounting-academy/module-3/3-2-batch-partitioning)
          * [3.3: Life Cycle Assessment & Emissions](/accounting-academy/module-3/3-3-lca-and-emissions)
          * [3.4: Allocating Emissions to Batches](/accounting-academy/module-3/3-4-allocating-emissions-to-batches)
          * [Exercise: Batch Partitioning & LCA](/accounting-academy/module-3/3-exercise-batch-partitioning-and-lca)
        </Step>

        <Step title="MODULE 4: Mass Balance with Ledgers" icon="bookmark" iconType="solid" stepNumber={4} titleSize="p">
          * [4.1: Introduction to Mass Balance](/accounting-academy/module-4/4-1-intro-to-mass-balance)
          * [4.2: Designing the Ledger Structure](/accounting-academy/module-4/4-2-designing-the-ledger-structure)
          * [4.3: Multiple Batch Types for Different Stages](/accounting-academy/module-4/4-3-multiple-batch-types)
          * [Exercise: Design & Build Mass Balance](/accounting-academy/module-4/4-exercise-design-and-build-mass-balance)
        </Step>

        <Step title="MODULE 5: Integration Testing" icon="bookmark" iconType="solid" stepNumber={5} titleSize="p">
          * [5.1: The Complete Model Assembly](/accounting-academy/module-5/5-1-the-complete-model-assembly)
          * [5.2: Testing Patterns](/accounting-academy/module-5/5-2-testing-patterns)
          * [5.3: Common Integration Pitfalls](/accounting-academy/module-5/5-3-common-integration-pitfalls)
          * [Exercise: Integration Testing](/accounting-academy/module-5/5-exercise-integration-testing)
        </Step>

        <Step title="MODULE 6: Advanced Patterns & Production" icon="bookmark" iconType="solid" stepNumber={6} titleSize="p">
          * [6.1: Model Design Best Practices](/accounting-academy/module-6/6-1-model-design-best-practices)
          * [6.2: Advanced Techniques](/accounting-academy/module-6/6-2-advanced-techniques)
          * [6.3: Production Readiness](/accounting-academy/module-6/6-3-production-readiness)
          * [Exercise: Production Deployment](/accounting-academy/module-6/6-exercise-production-deployment)
        </Step>
      </Steps>
    </div>
  </Card>
</Panel>

<Check>
  **What you'll learn in this lesson:**

  * Decide when to add new event types vs. extend existing ones
  * Connect multiple event types in a single model
  * Handle unit conversions and standardization
  * Build validation checks that prevent bad data propagation
</Check>

In Module 1 you worked with a single event type (Biochar Delivery). Real projects capture data from multiple activities — feedstock receipts, lab analyses, energy consumption. This lesson teaches you how to expand your data model to handle these additional inputs.

```mermaid theme={null}
flowchart LR
    subgraph Events["Multiple Event Types"]
        FR["Feedstock<br/>Receipt"]
        LA["Lab<br/>Analysis"]
        BD["Biochar<br/>Delivery"]
    end

    subgraph Model["Unified Model"]
        CALC["Multi-Step<br/>Calculation"]
    end

    FR --> CALC
    LA --> CALC
    BD --> CALC
    CALC --> OUT["Net Carbon<br/>(tCO2e)"]

    style FR fill:#42a5f5,stroke:#1976d2,stroke-width:2px,color:#000
    style LA fill:#42a5f5,stroke:#1976d2,stroke-width:2px,color:#000
    style BD fill:#42a5f5,stroke:#1976d2,stroke-width:2px,color:#000
    style CALC fill:#66bb6a,stroke:#388e3c,stroke-width:2px,color:#000
    style OUT fill:#ef5350,stroke:#c62828,stroke-width:2px,color:#000
```

## When to create a new event type

Not every piece of data needs its own event type. Use these guidelines to decide:

<Tabs>
  <Tab title="Create a new event type when...">
    * The data comes from a **different operational activity** (e.g., receiving feedstock vs. delivering biochar)
    * The data has a **different cadence** (e.g., lab tests happen weekly, deliveries happen daily)
    * The data has a **different source** (e.g., weighbridge system vs. lab instrument)
    * The data needs **separate evidence** (e.g., a delivery ticket vs. a lab certificate)
  </Tab>

  <Tab title="Extend an existing event type when...">
    * The data is captured **at the same time** as other datapoints in the event
    * The data comes from the **same operational step**
    * Adding a datapoint is simpler than managing a separate event type
    * The data is **always** present when the event occurs
  </Tab>
</Tabs>

<Tip>
  When in doubt, start with a new event type. It's easier to merge event types later than to split one into two. Separate event types give you cleaner data and more flexible models.
</Tip>

## New event types for Mangrove Biochar

To build a complete carbon accounting model, Mangrove Biochar needs at least two additional event types beyond Biochar Delivery:

<CardGroup cols={2}>
  <Card icon="truck-loading" title="Feedstock Receipt">
    Captures raw material entering the system.

    | Datapoint            | Value Type |
    | -------------------- | ---------- |
    | Feedstock type       | text       |
    | Wet mass (tonnes)    | number     |
    | Moisture content (%) | number     |
    | Receipt date         | date       |
    | Supplier ID          | text       |
  </Card>

  <Card icon="flask" title="Lab Analysis">
    Captures lab test results for biochar quality.

    | Datapoint          | Value Type |
    | ------------------ | ---------- |
    | Sample ID          | text       |
    | Carbon content (%) | number     |
    | H:C molar ratio    | number     |
    | Ash content (%)    | number     |
    | Analysis date      | date       |
  </Card>
</CardGroup>

Configure these in <a href="/production-accounting/data-inputs" target="_blank" rel="noopener noreferrer">Data Inputs > Input Settings</a>

, just as you did for Biochar Delivery in Module 1. Define each datapoint with a clear slug so the model can reference it.

## Connecting multiple event types in a model

A single <a href="/production-accounting/models" target="_blank" rel="noopener noreferrer">model</a>

can reference datapoints from **any event type** in the project. The model's input nodes specify which datapoint slug to pull from — Mangrove matches them to events within the accounting period.

```mermaid theme={null}
flowchart TB
    subgraph FR["Feedstock Receipt Events"]
        WM["wet_mass"]
        MC["moisture_content"]
    end

    subgraph LA["Lab Analysis Events"]
        CC["carbon_content"]
        HC["hc_ratio"]
    end

    subgraph Model["Model Nodes"]
        DRY["Dry Mass<br/>product: wet_mass × (1 - moisture/100)"]
        CCARB["Carbon Mass<br/>product: dry_mass × carbon_pct"]
        PERM["Permanence Factor<br/>keisan: based on hc_ratio"]
        NET["Net Carbon<br/>product: carbon × 3.67 × permanence"]
    end

    WM --> DRY
    MC --> DRY
    DRY --> CCARB
    CC --> CCARB
    HC --> PERM
    CCARB --> NET
    PERM --> NET

    style WM fill:#42a5f5,stroke:#1976d2,stroke-width:2px,color:#000
    style MC fill:#42a5f5,stroke:#1976d2,stroke-width:2px,color:#000
    style CC fill:#42a5f5,stroke:#1976d2,stroke-width:2px,color:#000
    style HC fill:#42a5f5,stroke:#1976d2,stroke-width:2px,color:#000
    style DRY fill:#66bb6a,stroke:#388e3c,stroke-width:2px,color:#000
    style CCARB fill:#66bb6a,stroke:#388e3c,stroke-width:2px,color:#000
    style PERM fill:#66bb6a,stroke:#388e3c,stroke-width:2px,color:#000
    style NET fill:#ef5350,stroke:#c62828,stroke-width:2px,color:#000
```

<Note>
  **Event matching:** When generating batches, Mangrove pulls datapoints from events whose date range falls within the accounting period. If a model references datapoints from multiple event types, all referenced events must exist for that period — otherwise validation will flag missing data.
</Note>

## Unit conversions and standardization

Different event types may record values in different units. Your model must handle conversions explicitly.

**Common conversions in carbon accounting:**

| From                   | To                     | Conversion                      |
| ---------------------- | ---------------------- | ------------------------------- |
| Wet mass (tonnes)      | Dry mass (tonnes)      | `wet_mass × (1 - moisture/100)` |
| Carbon content (%)     | Carbon fraction        | `carbon_pct / 100`              |
| Carbon mass (tonnes C) | CO2 equivalent (tCO2e) | `carbon_mass × 3.67`            |
| Distance (miles)       | Distance (km)          | `miles × 1.609`                 |

<Tip>
  Handle unit conversions as **explicit intermediate nodes** in your model rather than embedding them in complex Keisan expressions. This makes conversions visible and auditable.
</Tip>

The Model Editor supports the <a href="/production-accounting/models" target="_blank" rel="noopener noreferrer">Unitwise library</a>

for automatic unit tracking. Define units on each node to help Mangrove validate dimensional consistency.

## Building validation checks

Bad data in → bad results out. Validation helps catch problems before they propagate through calculations.

### What to validate

* **Range checks** — Is the value within a reasonable range? (e.g., moisture content between 0-100%)
* **Presence checks** — Are all required datapoints present for the accounting period?
* **Consistency checks** — Do related values make sense together? (e.g., dry mass should be less than wet mass)

### Where validation happens

<Steps>
  <Step title="At data entry">
    When <a href="/data-collection/add-data" target="_blank" rel="noopener noreferrer">adding events</a>

    , Mangrove validates required fields and data types. Configure datapoints as required in the event type to enforce this.
  </Step>

  <Step title="In the model">
    Use Keisan expressions to add runtime validation — for example, flagging negative values or out-of-range inputs. The model's test Console helps you verify these.
  </Step>

  <Step title="At batch generation">
    When you <a href="/production-accounting/generate-batches" target="_blank" rel="noopener noreferrer">generate batches</a>

    , Mangrove validates that all required datapoints are present. Missing data shows as validation messages you must resolve before submitting.
  </Step>
</Steps>

<Warning>
  If a model references a datapoint slug that doesn't exist in any event type, the model will silently produce no output for that node. Always verify that datapoint slugs in the model exactly match those configured in the event type.
</Warning>

***

### Check your understanding

<Accordion icon="circle-question" title="When should you create a new event type instead of adding a datapoint to an existing one?">
  Create a new event type when the data comes from a **different operational activity**, has a **different cadence**, comes from a **different source**, or needs **separate evidence**. Extend an existing event type when the data is captured at the same time and comes from the same operational step.
</Accordion>

<Accordion icon="circle-question" title="What role do static inputs play in models?">
  **Static inputs** are values that don't change from batch to batch — emission factors, conversion constants, or methodology-defined parameters. They come from the project's <a href="/production-accounting/data-inputs" target="_blank" rel="noopener noreferrer">resource library</a>

  and are referenced by model nodes just like event datapoints. Unlike constants hardcoded in the model, static inputs can be updated without modifying the model itself.
</Accordion>

<Accordion icon="circle-question" title="How does Mangrove handle data from multiple event types in a single model?">
  A model can reference datapoints from **any event type** in the project using the datapoint's slug. When generating batches, Mangrove pulls values from all events whose date range falls within the accounting period. If a referenced datapoint is missing for the period, validation will flag it before batch submission.
</Accordion>

***

You're now ready to put this into practice in the [Module 2 Exercise: Build a Multi-Step Calculation Pipeline](/accounting-academy/module-2/2-exercise-multi-step-calculations).