--- title: "Applying a scenario" slug: "applying-a-scenario-to-a-valuation" updated: 2026-11-01T11:46:17Z published: 2026-11-01T11:46:17Z 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 portfolio holding 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 affects. ## 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-11-20T21%3A27%3A15Z&se=2026-11-20T22%3A27%3A15Z&sr=b&sp=r&sig=S07vF9lwez%2BCVdgrz2kHv%2BlZXU2rKlBHgjmf6IbnONY%3D) LUSID adds a **Base · Latest** column group showing current PV and, for each scenario, a colour-coded column group to the right showing PV shifted. 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-11-20T21%3A27%3A15Z&se=2026-11-20T22%3A27%3A15Z&sr=b&sp=r&sig=JyOFJMTwdNNzdxxyTRac4W6gYdbn4sieeTQJqmPUi0o%3D) Note the following: - the LUSID web app chooses to shift PV in portfolio currency 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. These metrics are not configurable. - 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 the 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-11-20T21%3A27%3A15Z&se=2026-11-20T22%3A27%3A15Z&sr=b&sp=r&sig=P6uGiZ7CltJXW2G%2BAUyj9gHPAt4xcTnEPui7QPX23XM%3D) 2. Choose a scenario. LUSID adds a copy of the column to its right, tinted in the scenario’s colour and labeled with the column name and scenario [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-11-20T21%3A27%3A15Z&se=2026-11-20T22%3A27%3A15Z&sr=b&sp=r&sig=3xl5PmUkQXUjiy%2FeuZvGzipGWeSJ3ncAhzNKXPgxEpk%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. ### Individual metrics you can stress-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 [stress test 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, consider a portfolio where a 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 entire request unless your recipe allows partial success. ## Reverse stress testing using the API A reverse stress test works backwards from an outcome. Instead of asking what a scenario does to your portfolio, you ask how severe the scenario would have to be to cause a particular loss or gain. For example: how much worse than `MarketCrash` would markets have to get for a portfolio to lose 1,000,000 USD? LUSID multiplies every shift in the scenario by the same factor, or *scale*, and searches for the scale that produces your target change in value. A scale of 1 is the scenario as written. A scale of 2 doubles every shift, so a 20% fall becomes a 40% fall and a 100bp rise becomes 200bp. A scale of 0.5 halves every shift. To do this, call the [SolveReverseStress](https://www.lusid.com/docs/api/lusid/endpoints/scenarios/SolveReverseStress) API with a portfolio, a recipe, an effective date, a scenario and a target change in value: ```json curl -X POST 'https://.lusid.com/api/api/scenarios/$reversestress'  -H 'Authorization: Bearer '  -H 'Content-Type: application/json-patch+json'  -d '{  "portfolioEntityIds": [{"scope": "ScenarioTutorial", "code": "CRASH-USD", "portfolioEntityType": "SinglePortfolio"}],  "recipeId": {"scope": "ScenarioTutorial", "code": "Recipe"},  "effectiveAt": "2026-10-01T00:00:00Z",  "scenario": {"scope": "ScenarioTutorial", "code": "MarketCrash"},  "targetPnl": -1000000,  "metric": "Valuation/PvInPortfolioCcy",  "maxScale": 3 }' ``` The request takes the following fields, in addition to the portfolio, recipe, effective date and scenario: | Field | Description | Default | | --- | --- | --- | | `targetPnl` | Required. The change in value to solve for, in the currency of the metric. Use a negative number for a loss and a positive number for a gain. It can’t be zero. | None | | `metric` | The value LUSID adds up across the portfolio. Use a PV metric such as `Valuation/PvInPortfolioCcy` or `Valuation/PvInReportCcy`, or an analytic metric. You can’t use a risk metric. | `Valuation/PV` | | `reportCurrency` | The currency for `Valuation/PvInReportCcy`. | None | | `maxScale` | The largest scale LUSID tries. | 5 | | `ladderPoints` | The number of evenly spaced scales between zero and `maxScale` that LUSID values first, to find where the answer lies. | 5 | | `tolerance` | How close the result must be to the target, as a fraction of the target. The default of 0.0001 means within 0.01%, or 100 USD on a 1,000,000 USD target. | 0.0001 | | `maxIterations` | The number of extra valuations LUSID performs after valuing the ladder. | 3 | | `asAt`, `filters`, `marketDataOverrides` | Optional. These work as they do in a [GetValuation](https://www.lusid.com/docs/api/lusid/endpoints/aggregation/GetValuation/) request. | None | Consider the following example response (rounded to two decimal places): ```json {  "scale": 2.3336,  "targetPnl": -1000000.0,  "achievedPnl": -1000053.99,  "baseValue": 2349065.29,  "stressedValue": 1349011.30,  "converged": true,  "method": "Interpolation",  "valuations": 3,  "ladder": [    {"scale": 0.6,    "value": 2037485.74, "pnl": -311579.55},    {"scale": 1.2,    "value": 1768447.02, "pnl": -580618.28},    {"scale": 1.8,    "value": 1534170.90, "pnl": -814894.39},    {"scale": 2.3336, "value": 1349011.30, "pnl": -1000053.99},    {"scale": 2.3367, "value": 1347979.07, "pnl": -1001086.22},    {"scale": 2.4,    "value": 1327244.02, "pnl": -1021821.27},    {"scale": 3.0,    "value": 1141066.01, "pnl": -1207999.28}  ],  "warnings": [] } ``` Note the following: - `scale` is the answer. Here, `MarketCrash` would have to be about 2.33 times as severe for the portfolio to lose 1,000,000 USD. That means equities falling 46.7% instead of 20%, the banks 70% instead of 30%, GBP/USD 23.3% instead of 10%, USD rates rising 233bp instead of 100bp, and equity volatility rising by 0.117 instead of 0.05. Every shift scales, including volatility and rate shifts. - `achievedPnl` is the change in value at that scale, and it’s within the tolerance of your target. `stressedValue` is `baseValue` plus `achievedPnl`. `converged` is `true` when LUSID has met the tolerance. - `ladder` lists every scale LUSID valued, in the order of scale, with the portfolio value and change in value at each one. It shows how your loss grows as the scenario gets more severe. LUSID adds extra points near the answer as it homes in. - For a more precise answer, raise `ladderPoints` and lower `tolerance`. With 12 ladder points and a tolerance of 0.000001, the example solves to a scale of 2.33343 and a loss of 1,000,000.02 USD. ### Choosing the metric and maximum scale Two settings need care: - Use a PV metric in a single currency if your portfolio holds instruments in more than one currency. The default metric, `Valuation/PV`, is in each holding’s own currency, which LUSID can’t add up, so it rejects the request. Set `metric` to `Valuation/PvInPortfolioCcy`, or to `Valuation/PvInReportCcy` with a `reportCurrency`. - Choose a `maxScale` that keeps your largest shift realistic. LUSID values the portfolio at every ladder point up to `maxScale`. If any holding can’t be priced at one of them, the whole request fails. For example, at the default `maxScale` of 5, `MarketCrash` would make bank shares fall 150%, at which point the request fails. A `maxScale` of 3 limits the fall to 90%. ### When LUSID can’t find an answer If no scale between zero and `maxScale` reaches your target, LUSID still returns the ladder, but `scale` is empty, `converged` is `false` and `warnings` explains why. This happens when: - The target is too large. For example, `MarketCrash` loses at most about 1,208,000 USD at a scale of 3, so a 2,000,000 USD target is out of reach. Raise `maxScale` if a more severe scenario is still realistic. - The scenario moves the portfolio the wrong way. For example, `MarketCrash` can’t produce a gain at any scale, so a positive target fails. Check the sign of `targetPnl`, and [preview the scenario](/v1/docs/how-do-i-create-a-scenario#checking-what-a-scenario-will-shift) to check what it affects. LUSID rejects the request outright if: - `targetPnl` is zero. - `metric` is a risk metric. - The scenario contains a model option shift or a market data rule shift. These change how LUSID prices or finds market data rather than moving the market by an amount, so there’s nothing to scale.