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

# Custom Emission Factors

> Create and manage custom emission factors for your organization

# Custom Emission Factors

Custom emission factors allow you to define organization-specific emission factors when Dcycle's standard factors don't match your exact needs. This is an **advanced feature** for users with detailed LCA (Life Cycle Assessment) data from suppliers or custom calculations.

<Warning>
  Custom emission factors should only be used when you have verified, supplier-specific emission data. Using incorrect factors can significantly impact the accuracy of your carbon footprint calculations.
</Warning>

## Overview

### What are Custom Emission Factors?

Custom emission factors are user-defined emission values that override Dcycle's standard database factors for specific products, services, or processes. They are organized into **Custom Emission Groups** (categories) and can be applied to:

* **Purchases** - Supplier-specific product emission factors
* **Wastes** - Custom waste treatment emission factors
* **Energy** - Renewable energy with specific grid mix data

### When to Use Custom Factors

✅ **Use custom factors when:**

* You have supplier-provided LCA data with verified emission factors
* Your product/service has unique characteristics not captured by standard factors
* You need to track specific renewable energy contracts (PPAs)
* Regulatory requirements demand specific calculation methodologies

❌ **Don't use custom factors when:**

* Standard Dcycle factors are available and appropriate
* You're guessing or estimating without verified data
* You want to artificially lower your emissions (greenwashing)

## Workflow

<Steps>
  <Step title="Create Custom Emission Group">
    First, create a group (category) to organize your custom factors

    ```
    POST /api/v1/custom_emission_groups
    ```
  </Step>

  <Step title="Add Custom Emission Factors">
    Add individual emission factors to the group

    ```
    POST /api/v1/custom_emission_factors/{group_id}
    ```
  </Step>

  <Step title="Use in Purchases/Wastes">
    Reference your custom factor when creating purchases or wastes

    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "custom_emission_factor_id": "your-factor-uuid",
      ...
    }
    ```
  </Step>

  <Step title="Monitor & Update">
    Review and update factors annually or when supplier data changes

    ```
    PATCH /api/v1/custom_emission_factors/{id}
    ```
  </Step>
</Steps>

## Data Structure

### Custom Emission Group

A group organizes related custom emission factors:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "group-uuid",
  "name": "Supplier XYZ Products",
  "description": "LCA data from Supplier XYZ 2024",
  "category": "purchases",  // or "wastes", "energy"
  "ghg_type": 1,  // 1=fossil, 2=biogenic, 3=mixed
  "organization_id": "your-org-uuid"
}
```

### Custom Emission Factor

An individual factor within a group:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "factor-uuid",
  "ef_name": "Recycled Aluminum Sheets",
  "unit_id": "kg-unit-uuid",
  "factor_uploaded_by": "procurement_team",
  "tag": "advanced",  // "simple" or "advanced"
  "uncertainty_grade": 15.5,  // 0-100 percentage
  "factor_start_date": "2024-01-01",
  "factor_end_date": "2024-12-31",
  "emission_factor_values": [
    {
      "gas_type": "CO2",
      "value": 2.15  // kg CO2 per kg aluminum
    },
    {
      "gas_type": "CH4",
      "value": 0.008  // kg CH4 per kg aluminum
    },
    {
      "gas_type": "N2O",
      "value": 0.002  // kg N2O per kg aluminum
    }
  ],
  "recycled": true,  // For waste factors
  "renewable_percentage": null  // For energy factors
}
```

## Gas Types

Custom factors can include multiple greenhouse gases:

| Gas Type | Description          | GWP (100-year) |
| -------- | -------------------- | -------------- |
| `CO2`    | Carbon Dioxide       | 1              |
| `CH4`    | Methane              | 28             |
| `N2O`    | Nitrous Oxide        | 265            |
| `HFC`    | Hydrofluorocarbons   | Varies         |
| `PFC`    | Perfluorocarbons     | Varies         |
| `SF6`    | Sulfur Hexafluoride  | 23,500         |
| `NF3`    | Nitrogen Trifluoride | 16,100         |

<Info>
  Dcycle automatically converts all gases to CO2 equivalent (CO2e) using IPCC AR6 Global Warming Potential values.
</Info>

## Categories

Custom emission factors are organized by category:

### Purchases (`purchases`)

* Supplier-specific product emission factors
* Custom service emission calculations
* Industry-specific materials

**Example:** Recycled steel from certified supplier with EPD documentation

### Wastes (`wastes`)

* Custom waste treatment emission factors
* Specific disposal method emissions
* Regional waste processing differences

**Example:** Incineration with energy recovery at specific facility

### Energy (`energy`)

* Renewable energy contracts with specific grid mix
* Power Purchase Agreements (PPAs)
* On-site generation (solar, wind)

**Example:** 100% renewable energy from wind farm PPA

## Uncertainty Grades

Track the confidence level of your custom factors:

| Grade   | Description             | When to Use                              |
| ------- | ----------------------- | ---------------------------------------- |
| 0-20%   | **High confidence**     | Supplier-verified LCA, EPD, audited data |
| 21-40%  | **Medium confidence**   | Industry averages, peer-reviewed studies |
| 41-60%  | **Moderate confidence** | Estimated with reasonable assumptions    |
| 61-80%  | **Low confidence**      | Limited data, significant assumptions    |
| 81-100% | **Very low confidence** | Rough estimates, should be improved      |

<Tip>
  Document the source of your emission factors in the `additional_docs` field and aim to reduce uncertainty over time by obtaining better data.
</Tip>

## Best Practices

### 1. Document Everything

Always document the source and methodology:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "ef_name": "Recycled Plastic Granules - Supplier ABC",
  "additional_docs": "Based on EPD from ABC Plastics, dated 2024-01-15. Verified by third-party auditor. Includes recycling process emissions.",
  "factor_uploaded_by": "sustainability_team@company.com",
  "uncertainty_grade": 15
}
```

### 2. Set Validity Periods

Update factors regularly:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "factor_start_date": "2024-01-01",
  "factor_end_date": "2024-12-31"  // Review annually
}
```

### 3. Include All GHGs

Don't just use CO2 - include CH4, N2O when available:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
"emission_factor_values": [
  {"gas_type": "CO2", "value": 2.15},
  {"gas_type": "CH4", "value": 0.008},  // Often significant
  {"gas_type": "N2O", "value": 0.002}   // High GWP impact
]
```

### 4. Use Appropriate Units

Match units to your usage:

* **Mass-based:** kg, ton (for solid materials)
* **Volume-based:** L, m³ (for liquids, gases)
* **Energy-based:** kWh, MJ (for energy products)
* **Currency-based:** EUR, USD (as last resort)

### 5. Tag Complexity Appropriately

* **Simple tag:** Basic single-value factors
* **Advanced tag:** Multi-gas, time-variant, or complex calculations

## Validation Requirements

Dcycle validates custom factors to ensure data quality:

### Required Fields

* ✅ Emission factor name (`ef_name`)
* ✅ Unit ID (`unit_id`)
* ✅ At least one emission value (CO2 minimum)
* ✅ Uploaded by reference (`factor_uploaded_by`)
* ✅ Tag (`simple` or `advanced`)

### Optional but Recommended

* 📝 Uncertainty grade (0-100%)
* 📝 Validity period (start/end dates)
* 📝 Documentation reference (`additional_docs`)
* 📝 Additional gases (CH4, N2O)

### Automatic Checks

* ⚠️ Values must be non-negative
* ⚠️ Uncertainty grade must be 0-100%
* ⚠️ End date must be after start date
* ⚠️ Gas types must be valid (CO2, CH4, N2O, etc.)

## API Endpoints

<CardGroup cols={2}>
  <Card title="Create Factor" icon="plus" href="/api-docs/custom-emission-factors/create">
    Add new custom emission factor
  </Card>

  <Card title="List Factors" icon="list" href="/api-docs/custom-emission-factors/list">
    View factors in a group
  </Card>

  <Card title="Get Factor" icon="magnifying-glass" href="/api-docs/custom-emission-factors/get">
    Retrieve specific factor details
  </Card>

  <Card title="Update Factor" icon="pen" href="/api-docs/custom-emission-factors/update">
    Modify existing factor
  </Card>

  <Card title="Delete Factor" icon="trash" href="/api-docs/custom-emission-factors/delete">
    Remove custom factor
  </Card>

  <Card title="Manage Groups" icon="folder" href="/api-docs/custom-emission-groups/overview">
    Create and organize groups
  </Card>
</CardGroup>

## Common Use Cases

### Supplier-Specific Product Factors

When a supplier provides EPD (Environmental Product Declaration) data:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "ef_name": "Supplier ABC - Recycled Aluminum Sheet",
  "unit_id": "kg-unit-uuid",
  "factor_uploaded_by": "procurement@company.com",
  "tag": "advanced",
  "uncertainty_grade": 12,
  "factor_start_date": "2024-01-01",
  "factor_end_date": "2024-12-31",
  "additional_docs": "EPD No. ABC-2024-001, Third-party verified",
  "emission_factor_values": [
    {"gas_type": "CO2", "value": 2.15},
    {"gas_type": "CH4", "value": 0.008}
  ],
  "recycled": true
}
```

### Renewable Energy PPA

For Power Purchase Agreements with specific renewable sources:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "ef_name": "Wind Farm PPA - Northern Region",
  "unit_id": "kwh-unit-uuid",
  "factor_uploaded_by": "energy_manager@company.com",
  "tag": "advanced",
  "uncertainty_grade": 5,
  "factor_start_date": "2024-01-01",
  "factor_end_date": "2034-12-31",  // 10-year PPA
  "additional_docs": "PPA Contract #2024-WIND-001",
  "emission_factor_values": [
    {"gas_type": "CO2", "value": 0.0}  // Zero direct emissions
  ],
  "renewable_percentage": 100.0
}
```

### Custom Waste Treatment

For facility-specific waste treatment emissions:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "ef_name": "Local Incinerator with Energy Recovery",
  "unit_id": "kg-unit-uuid",
  "factor_uploaded_by": "waste_manager@company.com",
  "tag": "advanced",
  "uncertainty_grade": 25,
  "factor_start_date": "2024-01-01",
  "factor_end_date": "2024-12-31",
  "additional_docs": "Facility report Q4 2023, includes energy credit",
  "emission_factor_values": [
    {"gas_type": "CO2", "value": 0.45},  // Net after energy recovery
    {"gas_type": "CH4", "value": 0.002},
    {"gas_type": "N2O", "value": 0.015}  // Higher from incineration
  ],
  "hazardous": false,
  "low_code": "19 12 10",  // Combustible waste
  "rd_code": "R1"  // Energy recovery
}
```

## Related Documentation

<CardGroup cols={2}>
  <Card title="Custom Emission Groups" icon="folder-tree" href="/api-docs/custom-emission-groups/overview">
    Organize custom factors into groups
  </Card>

  <Card title="Purchases" icon="shopping-cart" href="/api-docs/purchases/list">
    Use custom factors in purchases
  </Card>

  <Card title="Wastes" icon="trash" href="/api-docs/wastes/codes">
    Apply to waste management
  </Card>

  <Card title="Units" icon="ruler" href="/api-docs/units/list">
    Available measurement units
  </Card>
</CardGroup>