Including properties and derived properties in valuation reports

You can include properties in a valuation report to supplement the many hundreds of LUSID metrics. These can be:

• Standard custom properties you have created yourself to extend the data model, belonging to either:

  • Instruments being valued, or to entities whose property domains are accessible to instruments; namely, transactions, holdings, portfolios and portfolio groups. More information.

  • Entities explicitly related to instruments being valued. Instruments can have relationships with legal entities, persons, portfolios, portfolio groups and custom entities. More information.

• Derived properties whose values are calculated on-the-fly from other properties or from entity fields or other data sources, belonging to either:

  • Instruments being valued or to holdings. More information.

  • The special DerivedValuation property domain, designed to enable you to create custom metrics. More information.

• System properties provided by LUSID. These properties can belong to instruments being valued, or to entities whose property domains are accessible to instruments; namely, transactions, holdings, portfolios and portfolio groups. More information.

* This is not a type of entity, but rather a standalone property domain.

Including standard properties in valuation reports

Belonging to instruments being valued, or to entities with accessible property domains

You can include these properties using the same syntax as metrics, for example:

"metrics": [
  {"key": "Valuation/EffectiveAt", "op": "Value"},             # Metric
  {"key": "Holding/Cost/Pfolio", "op": "Value"},               # Metric
  {"key": "Valuation/PvInPortfolioCcy", "op": "Value"},        # Metric
  {"key": "Instrument/BBG/Country", "op": "Value"}             # Property
  {"key": "Transaction/SHK/Strategy", "op": "Value"}           # Property
]

Belonging to entities related to instruments being valued

You can include properties from related entities using a special syntax. Note the following:

• You cannot include system properties from related entities.

• The relationship type must have the instrument as the sourceEntityType and the related entity as the targetEntityType.

For example, imagine instruments are related to legal entities representing issuing organisations, each of which has a LegalEntity/Scores/DEIScore custom property. To include the DEI scores of related legal entities in a valuation report, specify the 3-stage key in the normal way and additionally use the options field to specify the scope and code of the relationship type between instrument and legal entity as key/value pairs:

"metrics": [
  {"key": "Valuation/EffectiveAt", "op": "Value"},                       # Metric
  {"key": "Holding/Cost/Pfolio", "op": "Value"},                         # Metric
  {"key": "Valuation/PvInPortfolioCcy", "op": "Value"},                  # Metric
  {"key": "LegalEntity/Scores/DEIScore", "op": "Value", "options": {     # Property from related legal entities
    "RelationshipDefinitionIdScope": "InstrumentIssuer",
    "RelationshipDefinitionIdCode": "IssuerId",
    }
  }
]

Note for each instrument the response includes an array of DEI score property values, one per related legal entity:

"data": [
  {
    "Valuation/EffectiveAt": "2023-07-10T00:00:00.0000000+00:00",
    "Holding/Cost/Pfolio": 500,
    "Valuation/PvInPortfolioCcy": 1000,
    "LegalEntity/Scores/DEIScore(RelationshipDefinitionIdScope=\"InstrumentIssuer\", RelationshipDefinitionIdCode=\"IssuerId\")": [
      87, 79, 65
    ]
  },
...
]

Including derived properties in valuation reports

Belonging to instruments being valued or to holdings

You can include these derived properties using the same syntax as metrics, for example:

"metrics": [
  {"key": "Valuation/EffectiveAt", "op": "Value"},             # Metric
  {"key": "Holding/Cost/Pfolio", "op": "Value"},               # Metric
  {"key": "Valuation/PvInPortfolioCcy", "op": "Value"},        # Metric
  {"key": "Instrument/MyDerivedProps/Region", "op": "Value"}   # Derived property
  {"key": "Holding/MyDerivedProps/Lineage", "op": "Value"}     # Derived property
]

Belonging to the special DerivedValuation domain

A derived property in the DerivedValuation domain defines a custom metric.

For example, you could create a derived property type for a DerivedValuation/MyDerivedProps/AdjustedExposure custom metric with a derivation formula as follows:

{
  "domain": "DerivedValuation",
  "scope": "MyDerivedProps",
  "code": "AdjustedExposure",
  "displayName": "Adjusted Exposure",
  "dataTypeId": {"scope": "system", "code": "number"},
  "propertyDescription": "Exposure adjusted by a haircut factor stored as an instrument property",
  "derivationFormula": "AddressKeys[Valuation/InstrumentExposureInPortfolioCcy] * Properties[Instrument/MyStandardProps/Haircut]"
}

For more information on the LUSID metrics, properties and entity fields you can use in the derivation formula for a custom metric, see this table.

You can include a custom metric using the same syntax as a LUSID metric, for example:

"metrics": [
  {"key": "Valuation/EffectiveAt", "op": "Value"},                              # LUSID metric
  {"key": "Holding/Cost/Pfolio", "op": "Value"},                                # LUSID metric
  {"key": "Valuation/PvInPortfolioCcy", "op": "Value"},                         # LUSID metric
  {"key": "DerivedValuation/MyDerivedProps/AdjustedExposure", "op": "Value"}    # Custom metric
]

Including system properties in valuation reports

You can include system properties using the same syntax as metrics, for example:

"metrics": [
  {"key": "Valuation/EffectiveAt", "op": "Value"},             # Metric
  {"key": "Holding/Cost/Pfolio", "op": "Value"},               # Metric
  {"key": "Valuation/PvInPortfolioCcy", "op": "Value"},        # Metric
  {"key": "Instrument/default/Name", "op": "Value"}            # System property
  {"key": "Holding/default/TaxlotId", "op": "Value"}           # System property
]