What is a metric?

A metric in LUSID is a discrete piece of business information whose value you can retrieve and, potentially, perform operations on.

LUSID can report many hundreds of metrics about almost any aspect of the valuation process, from information about underlying instruments and transactions, portfolios and the holdings they contain, market data used, and headline statistics such as PV and PnL.

Note: You can include properties in valuation reports too.

To list every metric, call the GetQueryableKeys API. The following snippet from the response shows the definition of the PV metric:

{
     "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,Proportion,Average,Count,Min,Max,Value,SumOfPositiveValues,SumOfNegativeValues,SumOfAbsoluteValues,ProportionOfAbsoluteValues",
     "lifeCycleStatus": "Experimental"
}

Every metric:

• Has a multi-stage addressKey you can use to report the metric.
• Has a set of supportedOperations. You can always report a metric's Value; in addition, you can typically perform operations such as Sum, Proportion and Average on numeric values.

When you perform a valuation you must report at least one metric. Note it's often useful to report the Instrument/default/Name metric, to report the friendly names of underlying instruments. 

Note: You can call APIs to understand in advance which metrics are useful or valid for the types of instruments you wish to value. See how to do this.

Consider the following example, of a call to value this GBP-denominated portfolio containing a mix of US and UK equities and bonds on a single day, 7 March 2022:

• The metrics chosen to create a meaningful valuation report are highlighted (with summary explanations) in red.
• Results are grouped by the  Instrument/default/LusidInstrumentId metric (highlighted in yellow) to report one result per underlying instrument held. If the portfolio contains multiple holdings in the same underlying instrument (perhaps divided into tax lots or strategies), they are automatically aggregated.
• Non-numeric metrics report their Value.
• Numeric metrics use the Sum operation to total any holdings in the same underlying instrument divided into tax lots or strategies. Note this has no effect if holdings have not been so divided:

curl -X POST "https://<your-domain>.lusid.com/api/api/aggregation/$valuation"
   -H "Authorization: Bearer <your-API-access-token>"
   -H "Content-Type: application/json-patch+json"
   -d '{
     "portfolioEntityIds": [ {"scope": "FBNUniversity", "code": "Module-4-1", "portfolioEntityType": "SinglePortfolio"} ],
     "valuationSchedule": {"effectiveAt": "2022-03-07T00:00:00.0000000+00:00"},
     "recipeId": {"scope": "FBNUniversity", "code": "Module-4-1Recipe"},
     "groupBy": ["Instrument/default/LusidInstrumentId"],
     "metrics": [
       {"key": "Instrument/default/Name", "op": "Value"},             # Reports the friendly name of the underlying instrument
       {"key": "Valuation/EffectiveAt", "op": "Value"},               # Confirms the valuation date
       {"key": "Holding/default/Cost", "op": "Sum"},                  # Calculates cost in the transaction currency
       {"key": "Valuation/PV", "op": "Sum"},                          # Calculates PV in the transaction currency
       {"key": "Valuation/PnL/Unrealised", "op": "Sum"},              # Calculates PnL in the transaction currency (PV minus cost)
       {"key": "Holding/Cost/Pfolio", "op": "Sum"},                   # Calculates cost in GBP (the portfolio currency)
       {"key": "Valuation/PvInPortfolioCcy", "op": "Sum"},            # Calculates PV in GBP
       {"key": "Valuation/PnL/Unrealised/PfolioCcy", "op": "Sum"}     # Calculates PnL in GBP
     ]
   }'

The response might look like this (transformed to a Pandas dataframe and with columns renamed for simplicity):

For more on grouping results in a valuation report, and aggregating numeric values using mathematical operations, see this article.