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:

• Custom properties and/or system properties belonging to either:

  • Instruments being valued, or to entities whose property domains are accessible to instruments; see the table below. 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 help you create custom metrics. More information.

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

Including properties in valuation reports

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

You can include properties using the syntax <entity>/Properties[<domain>/<scope>/<code>], for example:

"metrics": [
  {"key": "Valuation/EffectiveAt", "op": "Value"},                              # Metric
  {"key": "Holding/Cost/Pfolio", "op": "Value"},                                # Metric
  {"key": "Valuation/PvInPortfolioCcy", "op": "Value"},                         # Metric
  {"key": "Instrument/Properties[Instrument/BBG/Country]", "op": "Value"}       # Custom property
  {"key": "Transaction/Properties[Transaction/SHK/Strategy]", "op": "Value"}    # Custom property
  {"key": "Holding/Properties[Holding/default/TaxlotId]", "op": "Value"}        # System property
]

Belonging to entities related to instruments being valued

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

• The property type cannot have a constraintStyle of Identifier.

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

• You cannot include system properties from related entities.

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, use the syntax <entity>/Properties[<domain>/<scope>/<code>], and additionally set 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/Properties[LegalEntity/Scores/DEIScore]", "op": "Value", "options": {   # Property from related legal entities
    "RelationshipDefinitionIdScope": "InstrumentIssuer",
    "RelationshipDefinitionIdCode": "IssuerId",
    }
  }
]

Note the API response returns an array in case the related property is multi-value. If there is more than one value, note the LUSID web app only displays the first:

"data": [
  {
    "Valuation/EffectiveAt": "2023-07-10T00:00:00.0000000+00:00",
    "Holding/Cost/Pfolio": 500,
    "Valuation/PvInPortfolioCcy": 1000,
    "LegalEntity/Properties[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 derived properties using the syntax <entity>/Properties[<domain>/<scope>/<code>], for example:

"metrics": [
  {"key": "Valuation/EffectiveAt", "op": "Value"},                                    # Metric
  {"key": "Holding/Cost/Pfolio", "op": "Value"},                                      # Metric
  {"key": "Valuation/PvInPortfolioCcy", "op": "Value"},                               # Metric
  {"key": "Instrument/Properties[Instrument/MyDerivedProps/Region]", "op": "Value"}   # Derived property
  {"key": "Holding/Properties[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.

Note you can use the Valuation/EffectiveAt LUSID metric to reference the valuation date and perform date operations in the formula, for example:

"derivationFormula": "if(AddressKeys[Valuation/EffectiveAt] gt Properties[Instrument/OTC/StartDate]) then Addresskeys[Valuation/PV] else 0"

You can include a custom metric in a valuation report 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
]