--- title: "Applying a scenario" slug: "applying-a-scenario-to-a-valuation" updated: 2026-10-29T13:49:34Z published: 2026-10-29T13:49:34Z canonical: "support.lusid.com/applying-a-scenario-to-a-valuation" --- > ## Documentation Index > Fetch the complete documentation index at: https://support.lusid.com/llms.txt > Use this file to discover all available pages before exploring further. # Applying a scenario 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](/v1/docs/applying-a-scenario-to-a-valuation#shifting-other-metrics-in-the-web-app-or-the-api), or [every metric in the entire valuation](/v1/docs/applying-a-scenario-to-a-valuation#shifting-the-entire-valuation-in-the-api). 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](/v1/docs/how-do-i-create-a-scenario#checking-what-a-scenario-will-shift) 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: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image-QHJ6MD4V.png?sv=2026-02-06&spr=https&st=2026-10-30T11%3A39%3A20Z&se=2026-10-30T12%3A39%3A20Z&sr=c&sp=r&sig=p99lW9JQqBimcmsEHVMLYMwc%2F656PSkyBT%2FtgCMl7pw%3D) 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). ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image-791J0QJ9.png?sv=2026-02-06&spr=https&st=2026-10-30T11%3A39%3A20Z&se=2026-10-30T12%3A39%3A20Z&sr=c&sp=r&sig=p99lW9JQqBimcmsEHVMLYMwc%2F656PSkyBT%2FtgCMl7pw%3D) 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](/v1/docs/applying-a-scenario-to-a-valuation#shifting-other-metrics-in-the-web-app-or-the-api). - 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](/v1/docs/applying-a-scenario-to-a-valuation#shifting-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](/v1/docs/recipes-changing-default-recipe-options#handling-failures-matured-and-forward-starting-instruments); 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. **LUSID web app** 1. Right-click the header of the column you want to shift (such as **Yield To Maturity**) and select **Options · Scenario**: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image-YWXIZGDX.png?sv=2026-02-06&spr=https&st=2026-10-30T11%3A39%3A20Z&se=2026-10-30T12%3A39%3A20Z&sr=c&sp=r&sig=p99lW9JQqBimcmsEHVMLYMwc%2F656PSkyBT%2FtgCMl7pw%3D) 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](/v1/docs/how-do-i-create-a-scenario#data-fields): ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image-B5LTHWM4.png?sv=2026-02-06&spr=https&st=2026-10-30T11%3A39%3A20Z&se=2026-10-30T12%3A39%3A20Z&sr=c&sp=r&sig=p99lW9JQqBimcmsEHVMLYMwc%2F656PSkyBT%2FtgCMl7pw%3D) 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. **LUSID API** Call the [GetValuation](https://www.lusid.com/docs/api/lusid/endpoints/aggregation/GetValuation/) API and add `ScenarioScope` and `ScenarioCode` options to [supported metrics](/v1/docs/applying-a-scenario-to-a-valuation#metrics-you-can-shift). 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: ```json curl -X POST 'https://.lusid.com/api/api/aggregation/$valuation'  -H 'Authorization: Bearer '  -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](https://www.lusid.com/docs/api/lusid/endpoints/aggregation/GetValuation/) API request: ```json curl -X POST 'https://.lusid.com/api/api/aggregation/$valuation'  -H 'Authorization: Bearer '  -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](/v1/docs/how-does-lusid-assess-risk) 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](/v1/docs/applying-a-scenario-to-a-valuation#shifting-the-entire-valuation-in-the-api), 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.