# Metric Operations

In some scenarios results from supported data sources require further operations to obtain the tracked KPI options metric. Simple arithmetic operations allow to combine together multiple data sources or transform them to desired denomination currency. Full specification of metric operations is available in its [implementation document](https://github.com/UMAprotocol/UMIPs/blob/master/Implementations/metric-operations.md) to be referenced by verifiers.

In order to use metric operations `Operation` parameter should be set to string choice from the [supported operations](#supported-operations). `OperationParameters` should be set to JSON object with parameter key-value pairs to be used with the chosen `Operation`.

### Configuring Operand Data Sources

Depending on the chosen `Operation` one of `OperationParameters` keys should be set either to `metricParameters` or `metricParametersArray`. Value of `metricParameters` should be set to nested JSON object with key-value pairs configuring ancillary data parameters required for the operand data source. Similarly, `metricParametersArray` should be set to an array of JSON objects configuring multiple operand data sources. All of [supported data sources](https://docs.outcome.finance/kpi-options/common-ancillary-data-parameters#data-source-method) can be used as operands, including nested operations allowing to chain together multiple operations on metric data sources.

Alternatively, deployers of KPI options can opt to store operand data source configuration off-chain by using `metricParametersURL` instead of `metricParameters` or `metricParametersArrayURL` instead of `metricParametersArray` that would reference the URL where the required JSON object / array is stored. This would allow reducing on-chain storage size in ancillary data and reduce gas costs on contract deployment and KPI option expiration. Though this introduces certain level of centralization risk that can be mitigated by storing operand configuration on decentralized storage platforms (e.g. IPFS). Alternatively, there might be a use case to append additional configuration when part of contracts contributing to the tracked metric are deployed after the launch of KPI options, though this should be done by storing operand configuration on a hosting platform with full version control visibility so that verifiers could check that the referenced configuration is consistent with the measured `Metric` parameter.

### Supported Operations

#### Summation

Setting `Operation` string to `SUM` allows summation of metric data sources configured in `metricParametersArray` (or referenced in `metricParametersArrayURL`).

#### Averaging

Setting `Operation` string to `AVG` allows tracking average value of metric data sources configured in `metricParametersArray` (or referenced in `metricParametersArrayURL`).

#### Maximum

Setting `Operation` string to `MAX` allows picking the highest value among value of metric data sources configured in `metricParametersArray` (or referenced in `metricParametersArrayURL`).

#### Minimum

Setting `Operation` string to `MIN` allows picking the lowest value among value of metric data sources configured in `metricParametersArray` (or referenced in `metricParametersArrayURL`).

#### Difference

Setting `Operation` string to `DIFF` allows calculating the difference between the value of two metric data sources configured in `metricParametersArray` (or referenced in `metricParametersArrayURL`). This requires that exactly two data sources are provided where the value of the second metric would be subtracted from the value of the first metric.

#### Conversion

Setting `Operation` string to `CONV` allows converting the value of metric data source configured in `metricParameters` (or referenced in `metricParametersURL`) to other denomination currency set in `priceIdentifier` parameter. `priceIdentifier` parameter should be set to string choice among price identifiers [approved by UMA governance](https://docs.umaproject.org/resources/approved-price-identifiers) though only price identifiers with available base and quote currencies are supported.

By default value of metric data source would be multiplied with the value of resolved price identifier. If optional `inverse` parameter is set to `true` the value of metric data source would be divided by the value of resolved price identifier.

### Mode of operation

#### Single Timestamp Operation

If `AggregationMethod` and `AggregationPeriod` parameters were not provided in the ancillary data the operation on the operand metrics would be performed at single daily timestamp, though the operand metrics themselves still can be calculated as aggregated over required time period if provided in operand configuration.

#### Operation Over Time Series

If `AggregationMethod` and `AggregationPeriod` parameters were provided in the ancillary data at the operation level the operation on the operand metrics would be performed at every daily timestamp (24:00 UTC) over the configured time period before processing results with the chosen aggregation method. Note that `MAX`, `MIN` and `DIFF` methods do not support operation over time series aggregation.

In case of multiple operands they should be configured to target the same time period for each operand. If any operand data starts at a later timestamp the values of all other operands before that would be discarded. Though, if any of operand data ends at a later timestamp than others the values of all other operands before that would be filled up with their last available values.