Performing operations on metrics

Every metric has a supportedOperations list that you can see when you call the GetAllQueryableKeys API. For example, Valuation/PV is defined as follows:

{
  "addressKey": "Valuation/PV",
  "description": "The present value of a holding of an instrument, at a point in time, in the settlement currency if applicable, otherwise domestic currency. Includes accrued interest",
  "displayName": "PV",
  "type": "Result0D",
  "flattenedType": "Decimal",
  "scalesWithHoldingQuantity": true,
  "supportedOperations": "Sum,DefaultSum,Proportion,Average,Count,Min,Max,Value,Append,SumOfPositiveValues,SumOfNegativeValues,SumOfAbsoluteValues,ProportionOfAbsoluteValues,SumCumulativeInAdvance,SumCumulativeInArrears",
  "lifeCycleStatus": "Experimental"
}

When you request a metric in a valuation report, you pair its key with one operation in the op field. You can always request a metric's Value. Text, date and true/false metrics also support Count. Numeric metrics support the full set of operations below.

How operations work

Each operation is applied to a group of rows:

• If you specify groupBy in the valuation request, each group is the set of holdings that share the same values for your groupBy metrics. LUSID returns one row per group.

• If you omit groupBy, LUSID returns one row per holding. The whole report is treated as a single group: operations such as Sum calculate a grand total and repeat it on every row.

• If your valuation schedule spans several dates, the whole report covers every date. For example, with no groupBy, Sum adds up values across all the dates. To get one total per date, group by Valuation/EffectiveAt.

• Proportion operations always divide by the total for the whole report, not by the total for the row's own group.

• Filters are applied first. Operations only see the rows that pass any filters you specify in your valuation request.

Available operations

The examples come from a GBP portfolio holding five positions, valued without groupBy. In portfolio currency (Valuation/PvInPortfolioCcy), their values are 1000, 800, -200 (a short position), 1000 and 400, so the total is 3000.

LUSID names each result column after the operation and metric, for example Sum(Valuation/PvInPortfolioCcy). The exception is Value, which uses the metric key on its own.

Summing values in different currencies

LUSID cannot sum amounts in different currencies. If you request Sum, Average, Min or Max for a metric such as Valuation/PV and a group contains both GBP and USD amounts, LUSID leaves the cell empty. It also adds a message to the row's Aggregation/Errors metric, for example:

metadata mismatch Dim:0,Units:(USD) != Dim:0,Units:(GBP).

To total amounts across currencies, use a version of the metric that LUSID converts to a single currency:

• …InPortfolioCcy metrics, such as Valuation/PvInPortfolioCcy and Valuation/ExposureInPortfolioCcy, are safe to total within one portfolio. They're also safe across portfolios that share a base currency.

• …InReportCcy metrics, such as Valuation/PvInReportCcy, are always safe to total, including across portfolios with different base currencies. To use them, set reportCurrency in your valuation request.

Note: LUSID only checks currencies. Plain numbers have no unit, so LUSID adds them without warning. For example, Sum of Holding/default/Units across a whole portfolio returns a number that mixes shares of different equities with units of cash. Only sum units when you've grouped by instrument.

Calculating totals, proportions and weights

There are three ways to report portfolio totals, and the percentage each holding contributes, in a valuation report:

• Operations (Sum, Proportion and so on): flexible, and they follow your grouping and filters.

• Total metrics (Valuation/TotalPortfolio… and Valuation/TotalGroup…): one whole-portfolio or whole-group total on every row, unaffected by filters.

• Weight metrics (Valuation/Weight and the Aggregation/…Weight metrics): a holding's or group's exposure as a share of the whole portfolio.

Which approach to use

Total metrics

LUSID calculates each total metric from every holding in the portfolio before it applies your filters or groupBy. It then reports the same figure on every row for that portfolio and date. This makes the total useful for showing the whole portfolio's value next to a filtered selection of holdings, or as the denominator in a derived property.

Note the following:

• Request total metrics with Value. Because every row already carries the full total, Sum multiplies it by the number of rows. For example, in a group of three holdings, Sum of a 3000 total returns 9000.

• "Group" means a portfolio group, not a groupBy group. TotalGroup… metrics are only populated when you value a portfolio group. If you value single portfolios, they're empty.

• For group totals in portfolio currency, every portfolio in the group must share a base currency. Otherwise the cell is empty and Aggregation/Errors reports Mixed currencies in total. If base currencies differ, use the …InReportCcy metric and set reportCurrency.

• …InReportCcy metrics need a report currency. If you don't set reportCurrency, they come back empty.

• One failure empties the total. If any holding fails to value, the total is empty. To leave failed holdings out of the total instead, set the IgnoreErrors option to true, for example {"key": "Valuation/TotalPortfolioPvInPortfolioCcy", "op": "Value", "options": {"IgnoreErrors": true}}.

For example, valuing a GBP portfolio worth 3000 with a filter that keeps only its GBP holdings returns:

Proportion measures each holding against the 1800 that passed the filter. The total metric still reports the whole portfolio.

Weight metrics

Valuation/Weight reports each holding's exposure in portfolio currency divided by the total PV of the whole portfolio. For a reference portfolio, it's the holding's units divided by the portfolio's total units.

The Aggregation weight metrics apply the same calculation to each row of your report. If you group your report, they add up each group first:

Note the following:

• Request these metrics with Value. LUSID calculates them for each group itself.

• Matching operations. Aggregation/NetExposureWeight gives the same result as Sum of Valuation/Weight, and Aggregation/GrossExposureWeight as SumOfAbsoluteValues of Valuation/Weight.

• The Benchmark option. Set it to true to calculate the weight using the portfolio's benchmark instead.

Other Aggregation metrics