You can ask LUSID to aggregate performance returns 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:

effectiveAtRequiredAn effective datetime marking the end of the return period.
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 specify 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 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, LUSID automatically aggregates performance for all constituent portfolios. Note if you want the dispersion metric you should call the GetAggregatedReturnsDispersionMetrics API instead, providing the composite has at least six constituent portfolios and each has been in for the whole year. If you want to analyse how the composite return has been calculated afterward, call the GetCompositeBreakdown API.

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

metricsRequiredYou must provide at least one PerformanceReturnsMetric object; see the following table.
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 following table.
alternativeInceptionDateOptionalThe date from which to include performance returns if this is different from the date when returns begin. Can be a date string or a portfolio property. Defaults to the actual inception date.
holidayCalendarsOptionalThe holiday calendar code(s) that should be used to determine the date schedule as a comma-separated list (for example CoppClark).
currencyOptionalConverts the results to the specified currency. If omitted, results are in the portfolio currency. Can be a ISO 4217 currency code string or a portfolio property.

Defaults to ReturnData, in which case LUSID calculates results for the returns uploaded to the system. Specify:

  • AllDays to calculate results for all dates including weekends (if there is no return for a particular date, it is treated as 0 rather than omitted).
  • WeekDays to calculate results for all dates excluding weekends (if there is no return for a particular date, it is treated as 0 rather than omitted).
  • If period is Monthly, MonthEnd to use the last return found for a particular month as the return for the last day of the month, rather than not returning a result.

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

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

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.

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

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.