Setting options on metrics

Some metrics let you fine-tune how LUSID calculates them by passing extra settings in the options field. With options, the same metric can report a P&L figure for a different window, a PV as at yesterday's close, or a portfolio total that leaves out holdings that failed to value. B

ecause each metric request carries its own options, you can put several versions of one metric side by side in a single valuation report.

Specifying options

Each metric in a valuation request has a key, an op and, optionally, an options object of name/value pairs. For example:

"metrics": [
  {"key": "Instrument/default/Name", "op": "Value"},
  {"key": "Valuation/PvInPortfolioCcy", "op": "Value"},                                                   # PV today
  {"key": "Valuation/PvInPortfolioCcy", "op": "Value", "options": {"DateTimeAgo": "P1BD"}},               # PV on the previous business day
  {"key": "ProfitAndLoss/Total/PortfolioCcy", "op": "Sum", "options": {"Window": "YTD"}},                 # P&L since the start of the year
  {"key": "Valuation/TotalPortfolioPvInPortfolioCcy", "op": "Value", "options": {"IgnoreErrors": true}}   # Continue if a holding fails to value
]

LUSID includes the options in the name of each result column, for example Valuation/PvInPortfolioCcy(DateTimeAgo="P1BD") or Sum(ProfitAndLoss/Total/PortfolioCcy(Window="YTD")). To use a shorter name, set the metric's returnAs field.

Finding out which options a metric supports

Call the GetAllQueryableKeys API. Each metric that takes options has an applicableOptions object, listing every option with its type, whether it's optional, its default and any allowed values. For example, the P&L metrics include:

"applicableOptions": {
  "Window": {
    "name": "Window",
    "type": "String",
    "description": "The Window for Profit and Loss calculations...",
    "optional": false,
    "allowedValueSet": ["YTD", "QTD", "MTD", "WTD", "Daily", "BusinessDaily", "Report"],
    "defaultValue": null
  },
  ...
}

Note the following:

• Most metrics take no options. A metric with no applicableOptions object accepts no options.

• If optional is false, you must supply the option. For example, every ProfitAndLoss metric requires a Window.

• Option names are case-sensitive: Window works and window doesn't. Allowed values aren't: LUSID accepts ytd and reports it as YTD.

• Options must have the right JSON type. For example, IgnoreErrors takes true, not "true".

• If you pass an option the metric doesn't support, or an invalid value, LUSID rejects the whole valuation request. The error names the problem, for example The following options were extra: [DateTimeAgo] or Option "Window" was not provided, but is required.

• You can only use metrics with options in metrics. You can't use them in groupBy, filters or sort.

Available options

You can't always combine options from different rows on one metric. For example, DateTimeAgo with PricingBasis is rejected. To get both, request the metric twice.

Using DateTimeAgo to report a metric at another point in time

DateTimeAgo lets you report start-of-day, end-of-day or T-1 versions of a metric alongside today's value in a single request. LUSID fully revalues the portfolio at the time you choose. It uses the holdings and market data at that time, while keeping your request's asAt.

You can use DateTimeAgo with these metrics:

• Valuation/PV, Valuation/PvInPortfolioCcy and Valuation/PvInReportCcy

• Valuation/CleanPV, Valuation/CleanPvInPortfolioCcy and Valuation/CleanPvInReportCcy

• Valuation/InstrumentPV, Valuation/InstrumentPvInPortfolioCcy and Valuation/InstrumentPvInReportCcy

• Valuation/CleanPriceKey and Valuation/DirtyPriceKey, and their *InPortfolioCcy and *InReportCcy versions

• Valuation/CurrentNotional and Valuation/Diagnostics/AssetBacked/PoolFactor

• Holding/Units and Holding/CurrentFace

• Quotes/Price

The value describes how far to move from the valuation date:

Note the following:

• Business days come from the holidayCalendars in your valuation schedule. If you don't specify any, LUSID skips only weekends.

• If a holding didn't exist at the earlier time, its column is empty. A holding that existed then but has since been sold gets its own row, containing the earlier value.

• Operations such as Sum work as usual. For example, grouping by Valuation/EffectiveAt and requesting Sum of Valuation/PvInPortfolioCcy with and without "DateTimeAgo": "P1BD" gives you today's and yesterday's portfolio PV side by side.

• If a holding fails to value at the earlier time, the whole request fails unless your recipe has the allowPartiallySuccessfulEvaluation recipe option set to allow partial success. In that case, only the affected cells are empty.

• You can't request DateTimeAgo in the same valuation request as benchmark metrics or RelatedPortfolio/Weight.

Using IgnoreErrors to calculate a total when some holdings fail

By default, if any holding fails to value, the Valuation/TotalPortfolio* and Valuation/TotalGroup* total metrics are empty, and the error appears in Aggregation/Errors. Set IgnoreErrors to true to calculate the total from the holdings that did value instead:

{"key": "Valuation/TotalPortfolioPvInPortfolioCcy", "op": "Value", "options": {"IgnoreErrors": true}}

Note the following:

• IgnoreErrors only has an effect if your recipe has the allowPartiallySuccessfulEvaluation recipe option set to allow partial success. Otherwise, a holding that fails to value fails the whole request.

• Valuation/Weight and the Aggregation weight metrics always divide by the total without IgnoreErrors. If any holding fails, they're empty.