Views:

You can ask LUSID to aggregate performance return for a portfolio over a particular period, for example the preceding 5 days, the year to date, since fund inception, or all of these.

  • To aggregate performance for a transaction portfolio, you must first upload your own simple performance returns to record the net gain or loss of the portfolio, either per day (the default) or per month.
  • To aggregate performance for a reference portfolio, you do not need to upload your own performance return data but you must ensure quotes for each constituent instrument in the portfolio are uploaded to the LUSID quote store.

Uploading a simple performance return for a transaction portfolio

Note: You do not need to upload simple performance returns for a reference portfolio.

To create or update a simple performance return for a transaction portfolio, obtain an API token and call the UpsertPortfolioReturns API, specifying the scope and code of the transaction portfolio and then the returnScope and returnCode of a particular set of simple performance returns, to which you can add as many individual returns as you like. You should supply a PerformanceReturn object in the body of your API request with the following data:

FieldStatusExplanation
effectiveAtRequiredThe effective date of the performance return.
rateOfReturnRequiredThe net gain or loss of the investment over period.
openingMarketValueOptionalThe market value at the start of period. Though optional, you should specify either this or closingMarketValue; do not omit both. LUSID uses the formula below this table to calculate missing market values.
closingMarketValueOptionalSpecify the market value at the end of period. Though optional, you should specify either this or openingMarketValue; do not omit both.
periodOptionalThe default is Daily; this constitutes a return for one day. Specify Monthly to determine this is a return for one month.

You can specify any number you like for the rateOfReturn. For example, you could calculate it as a simple percentage difference between the opening and closing market values:

rateOfReturn = (closingMarketValue – openingMarketValue) / openingMarketValue

Note an individual simple performance return may not have either an openMarketValue or a closingMarketValue (these fields are optional). If no openingMarketValue is provided, then LUSID calculates it as follows:

  • If it is the first performance return, then:
    • If rateOfReturn is 0, then openingMarketValue is 0 as well.
    • If rateOfReturn has a value then openingMarketValue is calculated using the formula:
      openingMarketValue = closingMarketValue / (rateOfReturn + 1)
  • If it is not the first performance return, then openingMarketValue is the previous closingMarketValue.

If no closingMarketValue is provided, then LUSID calculates it using the formula:

closingMarketValue = (rateOfReturn + 1) * openingMarketValue

Note you can:

Calculating aggregated performance return for a transaction or reference portfolio

Call the LUSID GetPortfolioAggregatedReturns API, passing in the scope and code of the portfolio and, optionally, fromEffectiveAt and toEffectiveAt dates to restrict the returns to aggregate.

Note: If the portfolio is a composite portfolio, then LUSID automatically aggregates performance for all its constituent portfolios. See also compositeMethod in the table below.

You should supply an AggregatedReturnsRequest object in the body of your API request with the following data to control how LUSID aggregates performance:

FieldStatusExplanation
metricsRequiredYou must provide at least one PerformanceReturnsMetric object; see the table below.
returnIdsRequired for a transaction portfolioThis is the returnScope and returnCode of the set of simple performance returns to aggregate.
recipeIdOptionalThis is the scope and code of a recipe from which to get FX rates to convert returns into the base currency of the portfolio (including inferring from an inverse FX rate if the appropriate parameter is set). If not specified, this is the built-in default recipe.
compositeMethodOptionalThe default is Asset; if the portfolio is a composite, a weighted average of all constituent portfolios is used to determine the result.

Specify Equal to determine that all the constituent portfolios in the composite are weighted equally.
periodOptionalThe default is Daily. You can change this to Monthly.

Note if you specify Monthly but have no monthly performance returns then daily returns are used to calculate a monthly return if sufficient of the former are available.
outputFrequencyOptionalThe default is Daily; you can change this to either Weekly, Monthly, Quarterly, HalfYearly or Yearly. See also the PERIODRETURN constant window in the table below.
alternativeInceptionDateOptionalThe date from which to include performance returns if this is different from the date when returns begin. Can be a date string or portfolio property. Defaults to the actual inception date.
holidayCalendarsOptionalThe holiday calendar(s) that should be used to determine the data schedule as a comma-separated list of codes (for example CoppClark).

For the metrics field (above), supply at least one PerformanceReturnsMetric object containing the following data:

FieldStatusExplanation
typeOptionalDefaults to Return. Specify:
  • Volatility to cause LUSID to calculate based on the statistical dispersion of returns (how much an asset's price swings around the mean price).
  • IndicativeAmount to calculate based on investing the seedAmount (or wealth index; see below).
windowRequiredSpecify the window to aggregate. This should be a string constituting either a constant window, a multi-X metric, or a Since metric.
 

Constant window

StringExplanation
PERIODRETURNAggregation depends upon the value of outputFrequency (see the table above):
  • If outputFrequency is Daily, this is a ‘1 day return’.
  • If outputFrequency is Weekly, this is a ‘1 week return’.
  • If outputFrequency is Monthly, this is a ‘1 month return’.
  • If outputFrequency is Quarterly, this is a ‘quarter return’.
  • If outputFrequency is HalfYearly, this is a ‘half year return’.
  • If outputFrequency is Yearly, this is a ‘1 year return’.
WTDAggregates returns for the week to date, where Monday is the first day of the week.
MTDAggregates returns for the month to date.
QTDAggregates returns for the quarter to date.
YTDAggregates returns for the year to date.
INCAggregates returns since inception.

Multi-X metric

Since months may be of varying length, there is special handling for the last day of the month. Month-end dates look back to prior month-end dates. So, one month rolling for the 28th February will look back to the 31st of January, not the 28th January.

StringExplanation
XDAggregates returns for X days (eg. 3D)
XWAggregates returns for X weeks (eg. 3W)
XMAggregates returns for X months (eg. 3M)
XYAggregates returns for X years (eg. 3Y)

Since metric

StringExplanation
Since(yyyy-mm-dd)Aggregates returns since a particular date (eg. Since(2012-12-20))
Since(YYYY-mm-dd)Aggregates returns since the most recent occurrence of a day in a year (eg. Since(YYYY-12-20))
Since(PropertyKey)Aggregates returns since the value of a particular property (eg. Since(Portfolio/Test/ReturnDate))
allowPartialOptionalDefaults to False; returns are only aggregated if the date range is fully covered by the return history. For example, a one year return is only aggregated if the portfolio has returns posted for at least one year.

Specify True to aggregate returns from the current state of the return history. Note results will be partial.
annualisedOptionalDefaults to False. Specify True to annualise the result.
withFeeOptionalDefaults to False. Specify True if period is Monthly to include model fees in the performance calculation, and apply the monthly rate of fees using the Portfolio/default/ModelFees system property.  Please note this is only supported for monthly returns.
seedAmountOptionalSpecify a decimal number. The result will be calculated using the formula seedAmount * (1 + window-value), providing type is set to indicativeAmount.
aliasOptionalSpecify a name to display for the metric in the response.