# Causal analysis of impact

> How a causal model separates the effect of an intervention, such as clean stove adoption, from other factors, with illustrative model and verification code.

Causal analysis estimates how much of a measured change an intervention actually caused. It models
what would have happened without the intervention (the counterfactual) and controls for other
factors that also move the outcome (confounding variables). Use it in an impact measurement or
validation methodology when a raw before-and-after comparison would credit the intervention with
changes it did not cause.

This page uses clean stove adoption and household emissions as the example. It shows what a causal
model accounts for, the shape of a model and its attribution result, and how a causal claim is
verified.

<Note>
  Illustrative example. The Python, JSON and JavaScript on this page show the shape of each record
  and call. They are not a tested sequence you can run as written.
</Note>

## What the model accounts for

| Part | Examples |
| --- | --- |
| Counterfactual modelling | Baseline scenario simulation, alternative fuel pathways, seasonal variations, economic factors |
| Confounding variables | Changes in household size, income fluctuations, weather patterns, market prices |

## Model one household

```python
from emerging import CausalModel, Household

# Initialize causal model
model = CausalModel(
    treatment="clean_stove_adoption",
    outcome="emissions",
    confounders=[
        "household_size",
        "income_level",
        "seasonal_temp"
    ]
)

# Analyze household impact
household = Household.get("did:ixo:household/123")
impact = model.analyze(
    household=household,
    period_start="2024-01-01",
    period_end="2024-01-31",
    confidence_level=0.95
)

# Get causal effects
print(f"Average Treatment Effect: {impact.ate}")
print(f"Confidence Interval: {impact.confidence_interval}")
```

## Impact attribution

The result attributes the reduction in emissions to its causes, with a confidence level and the
contribution of each device.

```json
{
  "householdId": "did:ixo:household/123",
  "period": {
    "start": "2024-01-01",
    "end": "2024-01-31"
  },
  "analysis": {
    "baselineEmissions": 120,
    "actualEmissions": 45,
    "reductions": 75,
    "confidence": 0.95,
    "causalFactors": {
      "cleanStoveAdoption": 0.65,
      "seasonalEffect": 0.15,
      "incomeChange": 0.10,
      "unexplained": 0.10
    },
    "deviceContributions": [{
      "deviceId": "did:ixo:device/456",
      "reductionShare": 0.8,
      "evidence": {
        "usageHours": 120,
        "fuelSaved": 32,
        "causalStrength": 0.85
      }
    }],
    "confounders": {
      "householdSize": {
        "baseline": 4,
        "current": 4,
        "effect": "neutral"
      },
      "income": {
        "direction": "increased",
        "effect": "positive",
        "magnitude": 0.1
      }
    }
  }
}
```

## Verify a causal claim

An oracle checks the causal claim against the evidence. On IXO, a decision oracle produces facts and
the IXO decision engine applies the rules and signs the decision. See
[Decision oracle](/build-an-oracle/decision-oracle).

<CodeGroup>
  ```python Causal Verification
  from emerging import CausalOracle, Evidence

  # Initialize causal oracle
  oracle = CausalOracle(
      min_confidence=0.95,
      required_evidence=["telemetry", "surveys", "market_data"]
  )

  # Verify causal claims
  verification = oracle.verify_household(
      household_id="did:ixo:household/123",
      period_start="2024-01-01",
      period_end="2024-01-31",
      evidence={
          "telemetry": device_data,
          "surveys": survey_data,
          "market_data": market_prices
      }
  )

  # Generate verification report
  if verification.is_valid:
      report = verification.generate_report()
      print(f"Causal Strength: {report.causal_strength}")
      print(f"Confidence Level: {report.confidence}")

  ```

  ```javascript
  import { CausalOracle, Evidence } from '@emerging/sdk';

  // Initialize causal oracle
  const oracle = new CausalOracle({
    minConfidence: 0.95,
    requiredEvidence: ['telemetry', 'surveys', 'market_data']
  });

  // Verify causal claims
  const verification = await oracle.verifyHousehold({
    householdId: 'did:ixo:household/123',
    periodStart: '2024-01-01',
    periodEnd: '2024-01-31',
    evidence: {
      telemetry: deviceData,
      surveys: surveyData,
      marketData: marketPrices
    }
  });

  // Generate verification report
  if (verification.isValid) {
    const report = await verification.generateReport();
    console.log(`Causal Strength: ${report.causalStrength}`);
    console.log(`Confidence Level: ${report.confidence}`);
  }
  ```

</CodeGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Digital MRV: protocols, data and credentials" icon="chart-line" href="/guides/digital-mrv">
    The measurements a causal model starts from.
  </Card>
  <Card title="Decision oracle" icon="scale-balanced" href="/build-an-oracle/decision-oracle">
    The service that checks claims and records decisions.
  </Card>
</CardGroup>