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

# Incremental contribution measures

> How the framework computes each trade's incremental contribution to its netting-set metric, and the hidden inframarginal exposure vectors this computation relies on.

Incremental contribution measures decompose netting-set-level or portfolio-level exposure into per-trade contributions. The visible incremental contribution metric is derived from three types of inframarginal exposure vectors, which are hidden intermediates.

Understanding [exposure measures](./exposure-measures) is a prerequisite for this page.

## What is the incremental contribution measure?

The incremental contribution expresses, as a signed scalar in the same unit as the underlying metric (for example, PFE or EE), how much a trade adds to its parent's metric. It is the difference between the parent metric and the corresponding metric computed on the [inframarginal exposure](#what-is-inframarginal-exposure), evaluated per the trade level and not aggregated above it:

$\text{IncrementalContribution}_{\text{trade}} = \text{Metric}_{\text{parent}} - \text{Metric}^{\,\text{inframarginal}}_{\text{trade}}$

where $\text{Metric}^{\,\text{inframarginal}}_{\text{trade}}$ is the metric computed on the inframarginal exposure (the parent aggregate excluding the current trade). Both terms of the difference honor the query filters: when the query restricts the trades in scope, the parent aggregate and the inframarginal value are both computed on the visible trades only, keeping the contribution consistent with the displayed totals. The result is a signed amount, not a ratio: positive when the trade increases the parent's exposure, negative when it provides a netting benefit. Unlike the inframarginal exposure it is derived from, the incremental contribution measure is visible to cube end-users. It is available through `IInframarginalExposureAndMetricsMeasures.incrementalContributions()`.

## What is inframarginal exposure?

Inframarginal exposure is the value of the aggregate excluding a single trade: it answers the question *"what would the netting-set exposure be if this trade were removed?"* It is an intermediate quantity that end-users do not query directly. The cube hides it and exposes the incremental contribution computed from it instead.

The framework provides three inframarginal approaches:

| Approach | Plugin key | Description |
| - | - | - |
| Linear inframarginal | `LinearInframarginal` | Subtracts the trade's own value from its parent. Applies where the aggregate is additive, which is the case for trades without a netting agreement (netting set `N/A`). |
| Netted inframarginal | `NettedInframarginal` | Routes to linear inframarginal for trades without a netting agreement, and to non-linear inframarginal for trades within a netting agreement. |
| Non-linear inframarginal | `NonLinearInframarginal` | Computes the inframarginal value by subtracting the exposure of the parent netting set excluding the current trade from the exposure of the parent netting set including the current trade. |

The netted inframarginal measure routes on the netting set of each trade: trades whose netting set ID is the default `N/A` use the linear formula, and all other trades use the non-linear one. Both yield the same quantity: the underlying evaluated on the parent excluding the trade.

## How is linear inframarginal computed?

Linear inframarginal subtracts the trade's own value from the value of its parent:

$\text{Inframarginal}_{\text{trade}} = E_{\text{nettingSet}} - E_{\text{trade}}$

The parent value honours the query filters, so both terms agree on which trades make up the parent. This is exact wherever the aggregate is additive, which is the case without a netting agreement: the no-netting branch floors each trade's exposure before summing, so the trades add up.

It also follows that where the linear form applies, the incremental contribution reduces to the trade's own value, since $E_{\text{nettingSet}} - (E_{\text{nettingSet}} - E_{\text{trade}}) = E_{\text{trade}}$.

## How is non-linear inframarginal computed?

For each trade at the trade-id level, non-linear inframarginal exposure is:

$\text{Inframarginal}_{\text{trade}} = E_{\text{nettingSet} \setminus \text{trade}}$

where $E_{\text{nettingSet} \setminus \text{trade}}$ is the exposure of the netting set with the current trade excluded from aggregation. This is exact because netting is non-linear, so the excluded value cannot be obtained by simply subtracting the trade's own value from the parent. It applies to both scalar and vector underlying measures.

## How do these measures relate to the public API?

The `IInframarginalExposureMeasures` interface gives access to the hidden inframarginal exposure vectors:

```java theme={"languages":{"custom":["/engine/python-sdk/6.2/languages/pycon.tmLanguage.json"]}}
public interface IInframarginalExposureMeasures {
  @Nullable IExposureVectorMeasures inframarginalExposureVectorsMeasures();
}
```

The `IInframarginalExposureAndMetricsMeasures` interface extends this with inframarginal metrics and the incremental contribution metric:

```java theme={"languages":{"custom":["/engine/python-sdk/6.2/languages/pycon.tmLanguage.json"]}}
public interface IInframarginalExposureAndMetricsMeasures extends IInframarginalExposureMeasures {
  @Nullable IExposureMetrics inframarginalExposureMetrics();
  @Nullable IExposureMetrics incrementalContributions();
}
```

Both `IGrossMeasures` and `INettedMeasures` extend `IInframarginalExposureMeasures`. `ICollateralizedExposureByAlgoMeasures` also extends `IInframarginalExposureMeasures`, so all three exposure families carry inframarginal measures.

## Related pages

* [Exposure measures](./exposure-measures)
* [Exposure metrics](./exposure-metrics)
* [Public API](../../reference/public-api)