Applying a scenario

  • Updated on Oct 29, 2026
  • Published on Oct 29, 2026
Prev Next

The quickest and most intuitive way to apply a scenario is to use the LUSID web app to shift PV in portfolio currency for every holding in a portfolio and show before (base) and after (shifted) values side-by-side.

Alternatively you can shift individual metrics from a supported set, or every metric in the entire valuation.

Note the following:

  • Applying a scenario never changes your stored market data. LUSID shifts the market data it has located in memory only.

  • LUSID uses the version of the scenario that was current at the valuation’s as-at time, so you can reproduce past results.

  • A shift that matches nothing in your portfolio doesn’t cause an error: the holdings it would have affected simply keep their base values. If a result looks unchanged, preview the scenario to check what it hits.

Stress-testing PV in portfolio currency using the web app

Navigate to Portfolio Management > Valuations and choose a portfolio, a recipe and an effective date in the usual way.

Then, from the Scenarios picker, choose one or more scenarios:

LUSID adds a Base · Latest column group showing current PV and, for each scenario, a colour-coded column group to the right showing shifted PV. Each group holds two columns:

  • PV in portfolio currency for each holding (the Valuation/PvInPortfolioCcy metric with the DefaultSum operation).

  • That PV as a proportion of the portfolio total (the Valuation/PvInPortfolioCcy metric with the Proportion operation).

Note the following:

  • PV in portfolio currency is shifted because it reflects every kind of shift, including FX, and it’s in one currency, so you can add it up across the portfolio. For example, under a scenario where HSBC shares fall 30% and GBP/USD falls 10%, a USD portfolio’s HSBC holding falls 37% in portfolio currency, but only 30% in its own currency, GBP.

  • Every other metric, such as PV in holding currency or accrued interest, keeps its base value. See how to shift individual metrics.

  • Each scenario always gets the same colour, for every user. Groups appear in the order you chose them. The web app remembers your choice of scenarios for each dashboard.

  • If your view includes risk metrics, some holdings may not be able to produce them. For example, equities valued from a price have no curve to bump. To stop one such holding failing the whole report, set the allowPartiallySuccessfulEvaluation recipe pricing option; the affected cells are then blank.

Stress-testing individual metrics using the web app or API

You can see most PV and analytic metrics under a scenario, not just PV in portfolio currency, but you must apply a scenario explicitly to each metric.

  1. Right-click the header of the column you want to shift (such as Yield To Maturity) and select Options · Scenario:

  2. Choose a scenario. LUSID adds a copy of the column to its right, tinted in the scenario’s colour and labelled with the column name and the scenario’s short code:

To change the scenario on a copy, right-click it and choose another one. To remove the copy, choose Base · Latest. You can also add a scenario version of a metric when you add the column: in Add columns, select Options next to the metric and choose a Scenario.

Note the following:

  • You can only do this for metrics that support scenarios (see below). For other columns, the menu doesn’t offer Scenario.

  • You can add one scenario per copy, but as many copies as you like.

  • LUSID adds a scenario version of the metric next to the normal one, so you can compare them.

  • You can’t add a scenario to the columns inside the groups created by the Scenarios picker. If a scenario is already applied through the picker, you can’t also choose it for the PV in portfolio currency column.

Call the GetValuation API and add ScenarioScope and ScenarioCode options to supported metrics.

Consider the following example, which returns PV in holding currency, PV in portfolio currency and modified duration, each with and without the MarketCrash scenario for comparison purposes:

curl -X POST 'https://<your-domain>.lusid.com/api/api/aggregation/$valuation'
  -H 'Authorization: Bearer <your-API-access-token>'
  -H 'Content-Type: application/json-patch+json'
  -d '{
  "portfolioEntityIds": [{"scope": "ScenarioTutorial", "code": "CRASH-USD", "portfolioEntityType": "SinglePortfolio"}],
  "recipeId": {"scope": "ScenarioTutorial", "code": "Recipe"},
  "valuationSchedule": {"effectiveAt": "2026-10-01T00:00:00Z"},
  "metrics": [
    {"key": "Instrument/default/Name", "op": "Value"},
    {"key": "Valuation/PV", "op": "Value"},
    {"key": "Valuation/PV", "op": "Value", "options": {"ScenarioScope": "ScenarioTutorial", "ScenarioCode": "MarketCrash"}, "returnAs": "PV_Crash"},
    {"key": "Valuation/PvInPortfolioCcy", "op": "Value"},
    {"key": "Valuation/PvInPortfolioCcy", "op": "Value", "options": {"ScenarioScope": "ScenarioTutorial", "ScenarioCode": "MarketCrash"}, "returnAs": "PvPortfolioCcy_Crash"},
    {"key": "Analytic/ModifiedDuration", "op": "Value"},
    {"key": "Analytic/ModifiedDuration", "op": "Value", "options": {"ScenarioScope": "ScenarioTutorial", "ScenarioCode": "MarketCrash"}, "returnAs": "ModDur_Crash"}
  ]
}'

Note the following:

  • You can add different scenarios to different metrics, or several scenarios to the same metric, in one request.

  • Use returnAs to give a scenario column a friendly name. The name must start with a letter and contain only letters, numbers, underscores and hyphens. If you omit it, LUSID names the column after the metric and its options, for example Valuation/PvInPortfolioCcy(ScenarioScope="ScenarioTutorial", ScenarioCode="MarketCrash").

  • Operations work on scenario columns too. For example, "op": "Proportion" returns each holding’s share of the portfolio total under the scenario.

  • The response includes a scenarioDiagnostics section listing each piece of market data the scenarios shifted.

  • If you add scenario options to a metric that doesn’t support them (such as a risk metric), LUSID rejects the request.

Metrics you can test

Most analytic metrics apply to bonds and other fixed-income instruments. For holdings a metric doesn’t apply to, the cell is blank under the scenario, as it is in the base column.

Category

Metrics

PV

Valuation/PV (holding currency), Valuation/PvInPortfolioCcy, Valuation/PvInReportCcy, Valuation/InstrumentPV (per unit). PV in portfolio and report currency convert at the scenario’s FX rates.

Duration and convexity

Analytic/ModifiedDuration, Analytic/MacaulayDuration, Analytic/EffectiveDuration, Analytic/EffectiveKeyRateDuration, Analytic/SpreadDuration, Analytic/SpreadDurationToWorst, Analytic/Convexity, Analytic/EffectiveConvexity

Yields

Analytic/YieldToMaturity, Analytic/YieldToWorst, Analytic/YieldToCall, Analytic/YieldToPut (and their /Date variants), Analytic/CouponEquivalentYield, Analytic/Discount

Spreads and margins

Analytic/ZSpread, Analytic/ZSpreadToWorst, Analytic/GSpread, Analytic/ISpread, Analytic/OAS, Analytic/DiscountMargin, Analytic/DiscountMarginToWorst

Credit sensitivity

Analytic/CS01, Analytic/CS01/Central, Analytic/EffectiveCS01

Other analytics

Analytic/Theta, Analytic/WeightedAverageLife, Analytic/default/HoldingCashflows

Stress-testing the entire valuation using the API

You can apply a single scenario to the entire valuation (that is, recalculate every metric, including risk metrics), using the API. Note you cannot perform this operation using the web app.

To do this, specify a scenario scope and code in your GetValuation API request:

curl -X POST 'https://<your-domain>.lusid.com/api/api/aggregation/$valuation'
  -H 'Authorization: Bearer <your-API-access-token>'
  -H 'Content-Type: application/json-patch+json'
  -d '{
  "portfolioEntityIds": [{"scope": "ScenarioTutorial", "code": "CRASH-USD", "portfolioEntityType": "SinglePortfolio"}],
  "recipeId": {"scope": "ScenarioTutorial", "code": "Recipe"},
  "valuationSchedule": {"effectiveAt": "2026-10-01T00:00:00Z"},
  "scenario": {"scope": "ScenarioTutorial", "code": "MarketCrash"},
  "metrics": [
    {"key": "Instrument/default/Name", "op": "Value"},
    {"key": "Valuation/PvInPortfolioCcy", "op": "Value"},
    {"key": "Risk/Rates/Pv01", "op": "Value"}
  ]
}'

Note the following:

  • The response contains no base values. To compare, run the same request again without scenario.

  • You can only apply a single scenario this way, and you can’t also add scenario options to individual metrics in the same request.

  • You can’t use a scenario that contains a market data rule shift, or a rate curve shift with applyTo.

  • To value against a particular version of the scenario, add an asAt to the scenario’s scope and code. Otherwise LUSID uses the version current at the request’s as-at time.

Stress-testing risk metrics

Risk metrics measure sensitivity: how much a holding’s value would change if a risk factor moved by a small amount. For example, Risk/Rates/Pv01 reports the change in value for a 1bp rise in rates. LUSID calculates it by nudging the curve and revaluing.

When you shift the entire valuation, LUSID first moves the market by the scenario, and then calculates the risk metric on top of the shifted market. The result is your sensitivity in the stressed world: how exposed you’d be after the scenario has happened.

For example, in the tutorial portfolio, the US Treasury’s Risk/Rates/Pv01 is −733.61 USD today. Under a scenario that raises USD rates by 100bp, it’s −676.61 USD. The bond is less sensitive to a further rise once rates are higher, so a hedge sized for today would be too large after the shock.

Note the following:

  • This is the only way to shift a risk metric. You can’t add scenario options to a risk metric, and the web app doesn’t offer it.

  • Risk metrics are only available for holdings whose pricing model depends on market data LUSID can bump. Holdings valued from a looked-up price, such as equities under SimpleStatic, can’t produce risk, and fail the request unless your recipe allows partial success.

© 2025 FINBOURNE Technology