Loading constituents and rebalancing a reference portfolio

You can create a reference portfolio to model an index such as the FTSE 100 or S&P 500 in LUSID.

You can load any number of constituents into a reference portfolio. Each constituent consists of a reference to an underlying instrument stored in the LUSID instrument master, and an initial weight corresponding to the proportion of the index you wish to allocate to that asset.

The weights of all the constituents can be set to float according to real-time pricing information, causing portfolio asset allocations to automatically change. You can rebalance the portfolio (that is, reset floating weights back to the initial weights) either on an ad-hoc basis or at a regular cadence.

For example, consider the following reference portfolio consisting of two equity constituents, each with an equal initial weight on 1 March 2022:

Loading constituents

To load constituents into a reference portfolio, obtain an API token and call the UpsertReferencePortfolioConstituents API.

Note: If you have a Luminesce license, you can write a SQL query using the Lusid.Portfolio.Constituent.Writer provider.

All the constituents you upsert must have the same:

• Effective from date. For Floating or Periodical (see below), this determines the prices of initial weights.

• Weight type, either Static, Floating or Periodical:

  Weight type	Reset period type	Reset period count	Explanation
  Static	n/a	n/a	Weights do not float.
  Floating	n/a	n/a	Weights float according to real-time pricing information. Weights are automatically rebalanced the next time you call the UpsertReferencePortfolioConstituents API.
  Periodical	Daily Weekly Monthly Quarterly Annually	A positive integer representing a quantity of the reset period type.	Weights float according to real-time pricing information. Weights are automatically rebalanced: The next time you call the UpsertReferencePortfolioConstituents API. When the reset period is triggered. For example, if you specify an effective from date of Tuesday 1 March 2022, then: Daily 5 rebalances weights every five days after the effective from date, so for example Sunday 6th March, Friday 11 March and so on. Weekly 2 rebalances weights every fourteen days after the effective from date, so for example Tuesday 15 March, Tuesday 29 March and so on. Monthly 4 rebalances weights every four months on the same date, so for example Friday 1 July, Tuesday 1 November and so on. Quarterly 2 rebalances weights twice a year on the same date, for example Thursday 1 September 2022, Wednesday 1 March 2023 and so on. Annually 10 rebalances weights once a decade on the same date, for example Monday 1 March 2032 and so on.

For each constituent, you must specify:

• At least one instrument identifier that enables LUSID to successfully resolve it to an instrument in the LUSID instrument master.

• An initial weight. Note this need not be a percentage (that is, the weights of all constituents need not add up to 100), though floating weight calculations are easier to interpret if they do.

You can optionally:

• Add properties if you want to extend the data model and store extra information not recorded by the standard set of data fields. These properties must be from the ReferenceHolding domain.

• Specify a currency if the underlying instrument is denominated in a foreign currency; that is, one different to the base currency of the reference portfolio. Note this is not used to calculate floating weights, but is used to normalise metrics such as PV and produce a meaningful report if you choose to value the reference portfolio.

The following example demonstrates how to load equally-weighted BP and Microsoft constituents:

• Into a reference portfolio with a scope of reference and code of example (in the URL below)

• With an effective from date for the initial weights of 1 March 2022

• That is set to Periodical with a reset period of Daily 3, so that floating weights automatically rebalance every three days after the effective from date (that is, on 4 March, 7 March and so on):

curl -X POST "https://<your-domain>.lusid.com/api/api/referenceportfolios/reference/example/constituents"
  -H "Authorization: Bearer <your-API-access-token>"
  -H "Content-Type: application/json"
   -d '{
    "effectiveFrom": "2022-03-01T00:00:00Z",
    "weightType": "Periodical",
    "periodType": "Daily",
    "periodCount": 3,
    "constituents": [
      {
        "instrumentIdentifiers": {
          "instrument/default/LusidInstrumentId": "LUID_00003D9N"
        },
        "weight": 50,
       "currency": "GBP"
      },
      {
        "instrumentIdentifiers": {
          "instrument/default/LusidInstrumentId": "LUID_00003DEG"
        },
        "weight": 50,
        "currency": "USD"
      }
    ] 
  }'

Reloading constituents

You can optionally call the UpsertReferencePortfolioConstituents API with a new effective from date, weight type and set of constituents. 

Note that if you do LUSID replaces the current constituents in the portfolio with the new dataset. Any existing constituents not included in the new dataset are removed.

Loading real-time pricing information

You can load real-time pricing information into the LUSID quote store to cause weights to automatically float (providing the weight type is Floating or Periodical).

To do this, you must load at least two prices per constituent:

• A price that is valid for the effective from date.

• A price that is valid for the date you wish to examine asset allocations.

Imagine we want to examine asset allocations twice, on 2 March and 3 March 2022. We need to load three prices for each of BP and Microsoft, for example:

Call the UpsertQuotes API to bulk-load prices into the LUSID quote store. Note each quote must be upserted in a particular way:

Note: The scope that quotes are loaded into must be the same as the reference portfolio scope.

For example, to load the 1 March 2022 price of 100 for BP into a reference quote scope (in the URL; this is created if it does not exist, and must be the same as the reference portfolio scope):

curl -X POST "https://<your-domain>.lusid.com/api/api/quotes/reference"
  -H "Authorization: Bearer <your-API-access-token>"
  -H "Content-Type: application/json"
  -d '{
    "Quote-0001": {
      "quoteId": {
        "quoteSeriesId": {
          "provider": "Lusid",
          "instrumentIdType": "LusidInstrumentId",
          "instrumentId": "LUID_00003D9N",
          "quoteType": "Price",
          "field": "mid"
        },
        "effectiveAt": "2022-03-01T00:00:00Z"
      },
      "metricValue": {
        "value": 100,
        "unit": "GBP"
      }
    }
  }'

Examining asset allocations over time

Call the GetReferencePortfolioConstituents API to examine how floating weights have caused asset allocations to change on a particular date.

For example, to examine asset allocations on 2 March 2022:

curl -X GET "https://<your-domain>.lusid.com/api/api/referenceportfolios/reference/example/constituents?effectiveAt=2022-03-02&propertyKeys=Instrument%2Fdefault%2FName" 
  -H "Authorization: Bearer <your-API-access-token>"

The Floating Weight column reveals that Microsoft now constitutes 57.14% of the portfolio. This is because the price of BP has gone down and Microsoft up since 1 March:

If we examine again on 3 March we can see that BP now constitutes 66.67% of the portfolio. This is because the price of BP has gone up and Microsoft down since 1 March:

Note: For an example of creating a reference portfolio and tracking floating weights in order to generate the transactions required to populate a ‘mirror’ transaction portfolio, see this Jupyter Notebook.

Rebalancing a reference portfolio

If we call the GetReferencePortfolioConstituents API again on 4 March we can see that the Daily 3 reset period has triggered and that the floating weights have been reset back to the initial weights: