> ## 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.

# Exposure measures

> Exposure measures in the netting-set analytics framework, covering the gross, netted, and collateralized vector families, bank and counterparty sides, scenario-level expansion, and the netting set parameter measures that the collateral algorithms read.

The netting-set analytics framework provides three families of exposure measures: gross, netted, and collateralized. Each family produces exposure vectors (one double per scenario, per time point) for the bank side and the counterparty side. Within each family, a scenario-level expansion variant exposes the vector elements individually for scenario-level drill-down.

Understanding [exposure concepts](../../introduction/exposure-concepts) and the [data model](../database/database-model) is a prerequisite for this page.

## What is an exposure vector measure?

An exposure vector measure is a measure whose value at a given cell is a `double[]` vector of length `scenariosCount`. Each element corresponds to one Monte-Carlo scenario. The exposure vector is computed at query time by aggregating the raw MtF vectors across all trades and time points in scope.

The `IExposureVectorMeasures` interface provides typed access to a family's vector measures:

```java theme={"languages":{"custom":["/engine/python-sdk/6.2/languages/pycon.tmLanguage.json"]}}
public interface IExposureVectorMeasures {
  NamedCopperMeasure getExposureVectors(Side side);
  NamedCopperMeasure getExposureVectorsScenarioLevel(Side side);
  @MeasureMetadata(
      "Exposure vector seen from the bank side, as a single vector value before scenario"
          + " expansion.")
  default NamedCopperMeasure getBankExposureVector() {
    return getExposureVectors(Side.BANK);
  }
  @MeasureMetadata(
      "Exposure vector seen from the cpty side, as a single vector value before scenario"
          + " expansion.")
  default NamedCopperMeasure getCptyExposureVector() {
    return getExposureVectors(Side.CPTY);
  }
  @MeasureMetadata(
      "Exposure vector seen from the bank side, expanded into individual scenario values along"
          + " the Scenarios dimension.")
  default NamedCopperMeasure getBankExposureVectorScenarioLevel() {
    return getExposureVectorsScenarioLevel(Side.BANK);
  }
  @MeasureMetadata(
      "Exposure vector seen from the cpty side, expanded into individual scenario values along"
          + " the Scenarios dimension.")
  default NamedCopperMeasure getCptyExposureVectorScenarioLevel() {
    return getExposureVectorsScenarioLevel(Side.CPTY);
  }
}
```

The `Side` enum has two values: `BANK` (label `"Bank"`) and `CPTY` (label `"Cpty"`). Convenience defaults `getBankExposureVector()` and `getCptyExposureVector()` delegate to the `Side`-parameterized methods.

## What are the gross exposure measures?

Gross exposure measures operate on the raw MtF vectors without any netting or collateral adjustment. They form the foundation on which the other families are built.

### Base gross exposure measures (`IBaseGrossExposureMeasures`)

These measures are the building blocks for gross and collateralized exposure.

| Measure | Description |
| - | - |
| `initialMtm` | The MtF value of a trade at time point zero (the as-of date), representing the initial mark-to-market. |
| `mtmSum` | The element-wise sum of MtF vectors across all trades in scope, aggregated up to the current query context. |
| `cumulativeCashflow` | The cumulative cashflow vector up to the current time point. Reads zero in the PFE cube. See [Cashflow measures](./cashflows). |
| `mtmSumScenarioLevel` | Scenario-level expansion of `mtmSum`. One row per scenario when the Scenarios dimension is in the query context. |
| `cumulativeCashflowScenarioLevel` | Scenario-level expansion of `cumulativeCashflow`. |

### Gross exposure vector family

Built from `mtmSum` and `cumulativeCashflow`, the gross exposure vectors represent the exposure of each trade or group of trades without netting. Two variants exist:

* **Gross** (standard): aggregates all time points.
* **Gross with break dates**: aggregates only time points before each trade's break date.

| Measure accessor | Description |
| - | - |
| `getExposureVectors(BANK)` | Bank-side gross exposure vector: element-wise `max(0, mtmSum + cumulativeCashflow)`. |
| `getExposureVectors(CPTY)` | Counterparty-side gross exposure vector: element-wise `min(0, mtmSum + cumulativeCashflow)`. |
| `getExposureVectorsScenarioLevel(BANK)` | Scenario-level bank exposure. One element per scenario in the Scenarios dimension. |
| `getExposureVectorsScenarioLevel(CPTY)` | Scenario-level counterparty exposure. |

The full `IGrossMeasures` interface extends both `IExposureMeasures` (for exposure vectors) and `IInframarginalExposureMeasures` (for inframarginal vectors). It also exposes `baseGrossExposureMeasures()`.

## What are the netted exposure measures?

Netted exposure measures aggregate MtF vectors within a netting set before taking the positive or negative part. This reduces gross exposure by the netting benefit when trades have offsetting values.

The netted exposure is computed by the `NettedExposure` measure (plugin key `NettedExposure`) from the `MarkToFuture` values of each netting set, for the selected side, with an optional break-date restriction.

Two variants exist:

* **Netted**: standard aggregation.
* **Netted with break dates**: aggregation limited to time points before each trade's break date.

| Measure accessor | Description |
| - | - |
| `getExposureVectors(BANK)` | Bank-side netted exposure vector: `max(0, sum of MtF within netting set)`. |
| `getExposureVectors(CPTY)` | Counterparty-side netted exposure vector: `min(0, sum of MtF within netting set)`. |
| `getExposureVectorsScenarioLevel(BANK)` | Scenario-level bank netted exposure. |
| `getExposureVectorsScenarioLevel(CPTY)` | Scenario-level counterparty netted exposure. |

The `INettedMeasures` interface extends both `IExposureMeasures` and `IInframarginalExposureMeasures`.

## What are the collateralized exposure measures?

Collateralized exposure measures subtract a CSA-based collateral balance from the netted MtF sum before taking the positive or negative part. The collateral balance is computed per netting set per time point by a collateral algorithm.

The measures are organized by collateral algorithm. Each algorithm that a cube provides has its own named set of measures.

The CSA and ISDA netting-agreement parameters are provided by a separate measures bundle. See [What are the netting set parameter measures?](#what-are-the-netting-set-parameter-measures).

### Independent amount measures (`IIndependentAmountMeasures`)

| Measure accessor | Description |
| - | - |
| `independentAmount()` | The independent amount vector per trade, aggregated by the `IndependentAmounts` table join. |

### Technical collateral measures (`ITechCollateralMeasures`)

These measures are produced by the collateral algorithm.

| Measure accessor | Description |
| - | - |
| `collateralBalance()` | The collateral balance vector at each time point, computed by the collateral algorithm. |
| `collateralBalanceScenarioLevel()` | Scenario-level expansion of the collateral balance. |
| `collateralDataPoints()` | The MtF and independent amount values per time point that the algorithm reads for the holding-period look-back and interpolation. |

### Collateralized exposure vectors (`ICollateralizedExposureByAlgoMeasures`)

| Measure accessor | Description |
| - | - |
| `getExposureVectors(BANK)` | Bank-side collateralized exposure: `max(0, nettedMtF - collateralBalance)`. |
| `getExposureVectors(CPTY)` | Counterparty-side collateralized exposure: `min(0, nettedMtF - collateralBalance)`. |
| `getExposureVectorsScenarioLevel(BANK)` | Scenario-level bank collateralized exposure. |
| `getExposureVectorsScenarioLevel(CPTY)` | Scenario-level counterparty collateralized exposure. |

The `ICollateralizedMeasures` interface groups all collateral-related measures:

```java theme={"languages":{"custom":["/engine/python-sdk/6.2/languages/pycon.tmLanguage.json"]}}
public interface ICollateralizedMeasures<A extends ICollateralizedExposureByAlgoMeasures> {
  @Nullable IIndependentAmountMeasures independentAmountMeasures();
  /** Returns all collateralized exposure measures keyed by algorithm name. */
  Map<String, A> collateralizedExposuresByAlgoMeasures();
  /** Returns collateralized exposure measures for the given algorithm name. */
  default @Nullable A exposureMeasuresByAlgo(final String algo) {
    return collateralizedExposuresByAlgoMeasures().get(algo);
  }
}
```

## What are the netting set parameter measures?

Netting set parameter measures expose the ISDA and CSA fields from the `NettingAgreements` table as cube measures. See the [data model](../database/database-model) for the field definitions. The cube combines these fields into a single object measure that the collateral algorithms read.

### Per-field parameter measures (`INettingSetParametersMeasures`)

For each netting-agreement field, the cube publishes a per-field measure in the "Netting Set Parameters" folder. Each measure is a `SINGLE_VALUE` aggregation read at the netting set level. It does not aggregate above that level.

| Measure accessor | Description |
| - | - |
| `initialCollateral()` | The initial collateral balance, used when the holding-period look-back date is before the business date. |
| `bankThreshold()` | The exposure threshold below which the bank does not call collateral. |
| `cptyThreshold()` | The exposure threshold below which the counterparty does not call collateral. |
| `bankMinTransferAmount()` | The smallest collateral transfer the bank will request. |
| `cptyMinTransferAmount()` | The smallest collateral transfer the counterparty will request. |
| `bankHoldingPeriod()` | The margin period of risk for the bank side, in days. |
| `cptyHoldingPeriod()` | The margin period of risk for the counterparty side, in days. |
| `bankIndependentAmount()` | The fixed independent amount posted by the bank. |
| `bankScaleFactor()` | The scale factor applied to the bank independent amount. |
| `bankFloor()` | The floor on the bank independent amount. |
| `cptyIndependentAmount()` | The fixed independent amount posted by the counterparty. |
| `cptyScaleFactor()` | The scale factor applied to the counterparty independent amount. |
| `cptyFloor()` | The floor on the counterparty independent amount. |
| `hairCut()` | The haircut multiplier applied to exposure values. |
| `parametersCurrency()` | The currency of the CSA threshold and minimum-transfer-amount parameters. |
| `hasNettingAgreement()` | Whether the netting set has an actual agreement. `false` for the default `N/A` netting set id. |
| `additionalParameters(name)` | The measure for a configured, non-default parameter, by its field name. Throws `IllegalArgumentException` for a default or unconfigured name. |

### The netting set parameters object

The `"Netting Set Parameters"` object measure (plugin key `NettingSetParameters`) holds one value per netting set. It is built from the per-field measures listed above and is not read from a table.

An override applied to one per-field measure is therefore reflected in the object and flows into the collateral balance computed from it.

### How to add custom netting set parameters

The built-in parameter list can be extended through the `additional-netting-set-parameters` cube property, a list of entries that each pair a `field-name` with a data `type`. The property sits under the cube prefix, for example `atoti.solution.model.cubes.pfe`. For each configured parameter, the cube:

* Adds a field to the `NettingAgreements` table.
* Publishes a per-field measure for it, alongside the built-in ones, in the "Netting Set Parameters" folder.
* Includes its value in the netting set parameters object, keyed by field name.

`INettingSetParametersMeasures.additionalParameters(name)` resolves the measure for a configured parameter by its field name. It throws `IllegalArgumentException` for a name that is not configured. Default parameters are already reachable through their own accessors.

## How does the scenario expansion work?

Scenario-level measures are produced by the `ScenarioExpansion` measure (plugin key: `ScenarioExpansion`). They expose individual scenario values when the Scenarios dimension is included in the query context. Without the Scenarios dimension, these measures are not meaningful and typically return null.

## Related pages

* [Exposure metrics](./exposure-metrics)
* [Collateral algorithms](./collateral-evaluator-framework)
* [Incremental contribution measures](./incremental-contribution-measures)
* [Cashflow measures](./cashflows)
* [Public API](../../reference/public-api)