Scenario reference: shift types, templates and limits

This article lists the scenario types, shift types, templates and limits in force when you create a scenario.

How LUSID combines shifts

LUSID applies shifts in a fixed order: price and FX shifts first, then curves and volatility surfaces, then spread-anchored prices.
Within each stage, shifts apply in the order they appear in the scenario, and shifts that hit the same value compound. For example, two −50% price shifts on the same instrument leave it at 25% of its value.
The exception is price shifts: a shift naming an instrument replaces a filter-based shift on the same quote.
A shift that matches nothing is ignored without an error, and the holdings it would have affected keep their base values.
LUSID never shifts historical fixings, such as past interest rate or inflation resets.

Shift types

A scenario contains one or more shifts, and each shift has one of the following types. You can mix types freely in one scenario, but note the order is significant (see above).

Web app name	`scenarioShiftType`	What it shifts	Shift modes
Rate curve shift	`RateCurveShiftDefinition`	Interest rate curves in one currency	parallel, steepen, flatten, twist, tent
Inflation curve shift	`InflationCurveShiftDefinition`	The curve for one inflation index	parallel, steepen, flatten, twist, tent
Credit spread shift	`CreditSpreadShiftDefinition`	Credit spread curves for one ticker	parallel, steepen, flatten, twist, tent
FX shift	`FxShiftDefinition`	The spot rate for one currency pair	absolute, relative, percentage
Price shift	`PriceShiftDefinition`	Prices and other quotes for one instrument, or for every instrument matching a filter	absolute, relative, percentage
Volatility surface shift	`VolSurfaceShiftDefinition`	Equity, interest rate or FX volatility surfaces	absolute, relative
Model option shift	`ModelOptionShiftDefinition`	A pricing model option	absolute, relative
Market data rule shift	`MdkrGroupShiftDefinition`	Which market data rules the recipe uses	None: it reroutes market data instead of shifting it

Every shift except a market data rule shift has an amount between −1,000,000 and 1,000,000. Its meaning depends on the shift mode:

Shift mode	Effect	Example
`absolute`	Adds the amount to the value, in the value’s own units	5 on a price of 100 gives 105; 0.05 on a volatility of 0.25 gives 0.30
`relative`	Multiplies the value by (1 + amount), so the amount is a fraction	−0.2 on a price of 100 gives 80
`percentage`	Multiplies the value by (1 + amount / 100), so the amount is in percentage points	−20 on a price of 100 gives 80

Note: Don’t mix relative and percentage. A relative amount of −50 multiplies the price by −49, not 0.5, and can make a valuation fail. Similarly, volatilities are decimals, so an absolute volatility shift of 5 adds 500 volatility points, not 5.

Rate curve, inflation curve and credit spread shifts

These three types share the same shapes and options. See all categories of complex market data.

Field	Explanation
`ccy`	Rate curve shifts: mandatory. The currency of the curves to shift. Unless you set `curveName`, LUSID shifts every rate curve in that currency, including discount and projection curves. Credit spread shifts: optional. Use it to pick out the right curve when the same ticker has curves in more than one currency.
`curveName`	Rate curve shifts only, optional. Shifts a single curve, identified by the name your recipe uses for it, for example `USDOIS`.
`index`	Inflation curve shifts only, mandatory. The inflation index, for example `UKRPI`. LUSID shifts the zero-coupon inflation swap quotes the curve is built from and rebuilds the curve, keeping its seasonality and fixings.
`ticker`	Credit spread shifts only, mandatory. The ticker of the credit spread curve. The shift also reaches bonds whose price is anchored to a z-spread.
`amount`	The size of the shift. With `scale` set to `Bps`, this is in basis points, so 50 means +50bp. With `scale` set to `Percentage`, it’s a relative change, so 1 multiplies each rate by 1.01.
`shiftType`	The shape of the shift across the window: `parallel`, `steepen`, `flatten`, `twist` or `tent`.
`scale`	`Bps` (the default) or `Percentage`.
`startTenor`, `endTenor`	Optional. The window of the curve to shift, as tenors from the valuation date, for example `1Y` and `10Y`. You can use `BD`, `D`, `W`, `M`, `Q`, `SA` and `Y`. If you omit them, the window runs from the first to the last point of the curve. Points outside the window don’t move at all: there’s no tapering at the edges.
`windowBounds`	Rate and inflation curve shifts only. Whether points exactly on the window’s start and end move: `Inclusive` (the default), `StartExclusive`, `EndExclusive` or `Exclusive`. If two shifts have windows that meet at the same tenor and both include it, that point is shifted twice. Use an exclusive bound on one of them to avoid this.
`pivotTenor`	Tent shifts only, optional. The tenor where the shift is largest. It must lie inside the window. If you omit it, the tent peaks at the middle of the window.
`minimumAmountBps`	Optional. A floor, in basis points, on the size of the shift at each point, applied after the shape. Use it for rules such as the Solvency II requirement that an upward shock is at least one percentage point at every maturity. Points the shape doesn’t move stay unmoved.
`applyWhenValue`	Optional. Shifts only points whose current value meets a condition: `Any` (the default), `Positive` (above zero) or `Negative` (below zero). For example, use `Positive` on a downward shock so rates that are already negative stay unchanged.
`applyTo`	Rate curve shifts only, optional, and only when you add the scenario to individual metrics. A filter that limits which holdings show values in the scenario columns. It doesn’t limit which instruments see the shifted curve, so scenario totals and base totals cover different holdings.

Shapes

Each shape sets how much of amount applies at each point of the window, from the start of the window (the short end) to the end (the long end):

`shiftType`	At the start of the window	At the end of the window	In between
`parallel`	Full amount	Full amount	Full amount
`steepen`	Zero	Full amount	Rises in a straight line
`flatten`	Full amount	Zero	Falls in a straight line
`twist`	Minus the full amount	Full amount	A straight line through zero at the middle of the window
`tent`	Zero	Zero	Rises in a straight line to the full amount at the pivot, then falls back. Useful for key-rate shocks.

FX shifts

FX shifts move spot rates only. They don’t shift FX forward curves.

Field	Explanation
`currencyPair`	Mandatory. The pair to shift, for example `GBP/USD`. LUSID shifts the rate in whichever direction it’s used: a −10% shift on `GBP/USD` takes GBP/USD from 1.30 to 1.17, and moves USD/GBP to match.
`amount`, `shiftType`	The size and mode of the shift: `absolute` (in units of the rate), `relative` or `percentage`.

Price shifts

Note the following:

A price shift changes quotes, not instruments. It affects any holding valued from the shifted quote, including derivatives that use it as their underlying price. For example, shifting an equity’s price also changes the value of an option on it priced with BlackScholes. It has no effect on instruments whose pricing model doesn’t use a quote, such as a bond valued using Discounting.
A filter only matches instruments held in the portfolios you’re valuing. If you hold an option but not its underlying share, a filter doesn’t reach the share’s price. To shift it, name the share with instrument instead.
If a shift that names an instrument and a filter-based shift both hit the same quote, LUSID applies only the shift that names the instrument, whatever order they appear in.

Field	Explanation
`instrument`	The identifier of a single instrument whose quote to shift. You can use any of the instrument’s identifiers, for example its LUID or its `ClientInternal` value. Supply either `instrument` or `filter`, not both.
`filter`	A filter selecting the instruments whose quotes to shift. See below.
`amount`, `shiftType`	The size and mode of the shift: `absolute`, `relative` or `percentage`.
`quoteType`	Optional. The type of quote to shift: `Price` (the default), `Spread`, `Rate` or `DirtyPrice`.

Price shift filters

Filters use a subset of the LUSID filter syntax:

Fields: name, assetClass, domCcy, lusidInstrumentId, scope, identifiers[<type>] and properties[Instrument/<scope>/<code>]
Operators: eq, neq, gt, gte, lt, lte, in, and and or

For example, assetClass eq 'Equities' and domCcy eq 'GBP' selects every sterling equity.

Note: LUSID saves a scenario whose filter uses a field it doesn’t support, and only reports the problem when you use the scenario in a valuation. A filter that matches no instruments doesn’t report a problem at all. Preview your scenario before you rely on it.

Volatility surface shifts

Field	Explanation
`instrument`	Mandatory. Identifies the surface by its market data name, not by an instrument identifier: Equity volatility: the underlying code used in the surface’s name, for example the LUID in `LUID_00003HDK/USD/LN`. To shift every equity volatility surface, use `EquityVol.*`. Interest rate volatility: the currency, for example `USD`. FX volatility: the currency pair, for example `GBP/USD`.
`amount`, `shiftType`	The size and mode of the shift: `absolute` or `relative`. Volatilities are decimals, so an absolute amount of 0.05 adds 5 volatility points, and a relative amount of 0.2 raises volatility by 20%.
`strike`	Optional. Shifts only points at exactly this strike.
`expiry`	Optional. A tenor such as `1Y`. LUSID shifts only the expiry nearest to it.

Model option shifts

A model option shift changes a parameter of a pricing model rather than market data. Currently you can only shift the Volatility and MeanReversion options of the HullWhite1F bond pricing model. LUSID rejects any other model or option when you save the scenario.

Field	Explanation
`modelName`, `optionName`	Mandatory. For example, `HullWhite1F` and `Volatility`.
`instrumentType`, `ccy`	Optional. Limit the shift to model rules for one instrument type, for example `ComplexBond`, or one currency.
`amount`, `shiftType`	`absolute` adds the amount in the option’s own units; `relative` scales the configured value by a fraction.

Market data rule shifts

A market data rule shift doesn’t move any values. Instead, it supplies one to ten alternative market data rules, each with its own key, for example to value the same portfolio at bid, mid and ask. Note the following:

Each rule produces its own scenario column in the valuation report, while the base column still uses the recipe’s own rules.
Any other shifts in the same scenario apply on top of each rule, so you can see (for example) bid prices under stress.
A scenario can contain only one market data rule shift.
You can only use it by adding the scenario to individual metrics, not for a whole valuation request, and not in a reverse stress test.

Scenario types

Every scenario has one of the following types. The type helps you organise scenarios, and the LUSID web app groups them by type in its pickers. It has no effect on valuation, and you can’t add your own types.

Scenario type	Typical use
`Historical`	A replay of a past market event, such as the 2008 financial crisis
`Regulatory`	A stress prescribed by a regulator, such as a Solvency II interest rate shock
`Hypothetical`	Any other what-if. This is the default in the web app, and the type LUSID gives scenarios created from a template.

Templates

LUSID provides the following built-in templates. You can’t create your own. Template names aren’t case-sensitive; parameter names are.

Template	Parameters	Creates
`RatesUp`	`ccy` (mandatory), `amount` in basis points (default 50)	A parallel rise in every rate curve in the currency
`RatesDown`	`ccy` (mandatory), `amount` in basis points (default −50)	A parallel fall in every rate curve in the currency
`CurveSteepener`	`ccy` (mandatory), `amount` in basis points (default 50)	A steepening shift, largest at the long end
`CurveFlattener`	`ccy` (mandatory), `amount` in basis points (default 50)	A flattening shift, largest at the short end
`VolSpike`	`instrument` (mandatory; the volatility surface’s market data name), `amount` as a fraction (default 0.20, meaning +20%)	A relative rise in one volatility surface
`EquityCrash`	Exactly one of `instrument` or `filter`, `amount` in percentage points (default −20)	A percentage fall in the price of one instrument, or every instrument matching the filter
`FxShock`	`currencyPair` (mandatory), `amount` in percentage points (default −5)	A percentage move in one currency pair
`RiskOff`	`ccy` and `instrument` (both mandatory). No `amount`.	The instrument’s price −20%, its volatility surface +20% relative, and the currency’s rate curves −50bp

Note: VolSpike takes its amount as a fraction, whereas EquityCrash and FxShock take percentage points. Entering 20 for VolSpike raises volatility by 2,000%.

Limits

Item	Limit
Shifts per scenario	1,000 (100 when you edit the scenario in the LUSID web app)
`amount`	−1,000,000 to 1,000,000
`scope`, `code`	64 characters each
`shortCode`	10 characters
`displayName`, `description`	1,024 characters each
Rules in a market data rule shift	10
Market data rule shifts per scenario	1
Template parameters	10, each up to 2,000 characters

What you can’t shift

You can’t currently use a scenario to shift:

FX forward curves or equity curves
Historical fixings and resets
The valuation date, to roll the portfolio forward in time
Correlations or dividends