Fine-tuning pricing models using model options

Most pricing models have model options that change how they behave: where an FX forward rate comes from, how an equity forward is projected, whether a bond quoted at a market price still reports interest rate risk, and so on.

Setting the right options lets you match an external valuation, unlock risk metrics, or reflect how your desk actually thinks about an instrument, without changing the model itself.

How model options work

A recipe has a pricing section that we strongly recommend you use to change the default pricing models.

At the same time, you can set model options in the modelOptions object of a vendor model rule. Each rule names an instrument type and a pricing model; the options then fine-tune that model for that instrument type, for example:

"pricing": {
  "modelRules": [
    {
      "supplier": "Lusid",
      "modelName": "BlackScholes",
      "instrumentType": "EquityOption",
      "modelOptions": {
        "modelOptionsType": "EquityModelOptions",
        "equityForwardProjectionType": "FlatForwardCurveFromSpot"
      }
    }
  ]
}

Note the following:

• The modelOptionsType field identifies the kind of options. It's mandatory, and each kind has its own set of fields. If you include a kind of option, you must set its mandatory fields, or LUSID rejects the recipe.

• Options belong to a model, not just an instrument type. For example, HullWhiteModelOptions only has an effect when the rule's model is HullWhite1F. The tables below show which models read each kind of option.

• Omitting modelOptions uses the model's defaults. This is the same as setting "modelOptionsType": "EmptyModelOptions", which has no other fields. The defaults are listed for each kind of option below, and they're not always the same across models.

• LUSID ignores options that don't match the model. If you set (for example) EquityModelOptions on a BondLookupPricer rule, LUSID doesn't report an error; it values the instrument using the model's defaults. LUSID does still check that the option values themselves are valid. Check the tables below to make sure your options and model go together.

Summary of model options

FxForwardModelOptions

Use these options to choose the market data an FX forward is valued from. For example, you can value from an FX forward curve rather than from interest rate curves, value without discounting to match an administrator, or value every forward in a third currency using forward rather than spot rates.

If you include FxForwardModelOptions in a rule, you must set forwardRateObservableType, discountingMethod and convertToReportCcy, otherwise LUSID rejects the recipe. Use Invalid to keep a field's default.

Where the forward rate comes from

Note: Forward points and forward rate quotes are keyed by the forward's exact maturity date. LUSID doesn't interpolate between them, so you need a quote for every maturity date in your portfolio. If you hold forwards with many different maturities, an FX forward curve is usually easier to maintain.

Using named models instead

Under the Discounting model, these options give exactly the same results as the named FX forward models:

The named models fix the forward rate source and the discounting method, so they ignore forwardRateObservableType and discountingMethod. They still read convertToReportCcy and allowSpotFallbackForReportCcy.

The ConstantTimeValueOfMoney model also ignores forwardRateObservableType and discountingMethod. It values both legs at the spot rate, with no forward rate and no discounting, so it isn't the same as the undiscounted models above.

Valuing in a report currency

How convertToReportCcy behaves depends on where the forward rate comes from. Say you hold a GBP/USD forward and report in EUR:

• FxForwardCurve or ForwardRate: LUSID values the forward using EUR/GBP and EUR/USD forward rates, and discounts on the EUR discount curve. The spot rate doesn't affect the result. You need the EUR/GBP and EUR/USD forward curves or quotes, and the EUR discount curve.

• ForwardPoints: as above, but the EUR/GBP and EUR/USD forward rates are built from spot rates plus points, so spot rates still affect the result.

• RatesCurve or Invalid: setting convertToReportCcy to true makes no difference. LUSID converts at the spot rate.

If a report currency forward rate is missing, the valuation fails with a market data error naming the missing item, for example FxForwards.EUR.GBP.FxFwdCurve. Set allowSpotFallbackForReportCcy to true to convert at spot instead.

{
  "supplier": "Lusid",
  "modelName": "Discounting",
  "instrumentType": "FxForward",
  "modelOptions": {
    "modelOptionsType": "FxForwardModelOptions",
    "forwardRateObservableType": "FxForwardCurve",
    "discountingMethod": "ConstantTimeValueOfMoney",
    "convertToReportCcy": true
  }
}

For more information on valuing FX forwards, see Modelling FxForwards in LUSID.

EquityModelOptions

Use these options to choose how LUSID projects the forward price of the underlying equity. Projecting from the interest rate curve is the textbook approach. Keeping the forward flat at spot, or supplying your own curve of forward prices, can match a counterparty's or administrator's valuation, or reflect expected dividends.

The default if you omit modelOptions depends on the instrument type and model:

Note: The same underlying can therefore have a different forward price in an equity option than in a CFD or equity swap, unless you set this option explicitly. Under ConstantTimeValueOfMoney, ForwardProjectedFromRatesCurve and FlatForwardCurveFromSpot give the same result, because that model doesn't use an interest rate curve.

If you include EquityModelOptions in a rule, you must set equityForwardProjectionType.

{
  "supplier": "Lusid",
  "modelName": "Discounting",
  "instrumentType": "ContractForDifference",
  "modelOptions": {
    "modelOptionsType": "EquityModelOptions",
    "equityForwardProjectionType": "ForwardProjectedFromRatesCurve"
  }
}

FundingLegModelOptions

Use this option to choose how much of a funding leg (for example, the funding leg of an equity swap held as a separate position) LUSID values. You can value the full remaining schedule of coupons, or just the interest accrued so far, which some funds prefer for reporting because it doesn't depend on assumptions about future notional.

If you include FundingLegModelOptions in a rule, you must set expectedFundingLegNotional.

For example, for a 1,000,000 notional leg paying EURIBOR 3M plus 50bp, valued 45 days into a 3 month coupon with rates at 3%:

Valuation/Accrued is 4,375.00 either way.

{
  "supplier": "Lusid",
  "modelName": "Discounting",
  "instrumentType": "FundingLeg",
  "modelOptions": {
    "modelOptionsType": "FundingLegModelOptions",
    "expectedFundingLegNotional": "Zero"
  }
}

Note: A funding leg takes its notional from your holding, so you must value it in a portfolio. Book the transaction with the Transaction/default/RequiresFundingLegHistory property set to true.

IndexModelOptions

Use these options to look through an instrument to the portfolio it represents, for example to value a ‘fund of funds’ portfolio at the level of the underlying holdings, or to expand an index into its constituents. You can choose how LUSID scales the constituents to the size of your holding.

If you omit modelOptions, LUSID doesn't look through the instrument, and values it from its price, unless the rule's model is InlinedIndex, which looks through using Sum.

LUSID scales units, PV and accrued interest by the same factor.

Note the following:

• Sum fails if the child portfolio has a net value of zero (for example, longs and shorts that cancel out, or an empty portfolio), with the error "Unable to perform lookthrough scaling for portfolio… with zero net value". AbsoluteSum works when longs and shorts cancel out. Unity returns no rows at all for an empty child portfolio, so the holding silently disappears from your valuation.

• For Sum and AbsoluteSum, you can choose what LUSID shares out. The conservedQuantityForLookthroughExpansion pricing option controls this: PV (the default), or Exposure. For example, use Exposure if the child holds futures, whose exposure is much larger than their PV. See Recipes: Changing default recipe options.

• IndexModelOptions works with any model that's valid for the instrument type. For a SimpleInstrument, that's SimpleStatic or InlinedIndex. For other instrument types with a look-through portfolio, such as a Bond, LUSID shares out the value calculated by the rule's model.

• LUSID values the child holdings using the same recipe as the parent.

{
  "supplier": "Lusid",
  "modelName": "SimpleStatic",
  "instrumentType": "SimpleInstrument",
  "modelOptions": {
    "modelOptionsType": "IndexModelOptions",
    "portfolioScaling": "Sum"
  }
}

SimpleModelOptions

Use these options when you want LUSID to value an instrument purely from the price you supply. You can switch off the accrued interest calculation, so LUSID doesn't ask for fixings it doesn't need. If your swap marks are quoted around par, you can have LUSID read them that way.

Note: With priceIsParOffset, the scale factor is the par value. A price of 101 loaded with a scale factor of 1 is read as 100 times par, and the PV is wrong by a factor of 10,000. Load swap prices quoted per 100 with no scale factor or a scale factor of 100.

Note: The direction of the swap doesn't change the sign of the value LUSID takes from the price. Quote a swap from the point of view of the position you hold.

{
  "supplier": "Lusid",
  "modelName": "SimpleStatic",
  "instrumentType": "InterestRateSwap",
  "modelOptions": {
    "modelOptionsType": "SimpleModelOptions",
    "assumeAccruedIsZero": true,
    "priceIsParOffset": true
  }
}

For more information, see Modelling interest rate swaps in LUSID.

BondLookupModelOptions

The BondLookupPricer pricing model values a bond at its market price. Because the price doesn't depend on any curve, by default LUSID reports interest rate risk such as Risk/Rates/Pv01 as zero, with an explanation in the Aggregation/Errors column, and no credit spread risk.

Use these options to get interest rate and credit spread risk, such as Pv01, key rate durations and CS01, for a bond you value from market data. LUSID does this by valuing the bond off the discount curve at a constant spread over it.

The spread comes from the following sources, in order of preference:

Note: With workout set to NextCall, the PV is unchanged if LUSID works out the spread from the market price. If you load a credit spread curve or ZSpread quote, LUSID values the bond's cashflows to the call date at that spread, so the PV changes.

Note: LUSID loads a ZSpread quote using a market data rule with a quote type of Rate. Order this rule after the rule for the bond's price (quote type Price). If the Rate rule comes first, any bond in the same recipe that you value without spreadAnchoredRisk fails, because LUSID picks up its ZSpread quote as its price.

{
  "supplier": "Lusid",
  "modelName": "BondLookupPricer",
  "instrumentType": "Bond",
  "modelOptions": {
    "modelOptionsType": "BondLookupModelOptions",
    "spreadAnchoredRisk": true,
    "spreadAnchorSource": "SolvedFromPrice"
  }
}

For more information, see Modelling vanilla fixed-rate bonds in LUSID and How does LUSID assess risk?.

HullWhiteModelOptions

The HullWhite1F pricing model values callable and puttable bonds on an interest rate lattice, so the value of the call or put is reflected in the PV and risk.

Use these options to calibrate the model to your own view of rates volatility, shock that volatility for scenarios, and control how option-adjusted risk measures are calculated. All fields are optional. If you omit modelOptions, LUSID uses the defaults below.

{
  "supplier": "Lusid",
  "modelName": "HullWhite1F",
  "instrumentType": "ComplexBond",
  "modelOptions": {
    "modelOptionsType": "HullWhiteModelOptions",
    "meanReversion": 0.03,
    "volatilityByCurrency": { "USD": 0.01, "EUR": 0.007 }
  }
}

Note: Volatility and mean reversion are model options rather than market data, so LUSID doesn't report volatility risk for them. Use volatilityMultiplier in a scenario instead.

Note: Analytic/OAS and the effective measures need a market price for the bond. If you request any of them and the price is missing, the whole row fails, including the PV. If you load an OAS quote (quote type Rate), order its market data rule after the rule for the bond's price.

BondForwardModelOptions

Use this option to choose how a bond forward is valued. Valuing from the quoted contract price is simple, but gives no interest rate risk. Modelling the forward from the deliverable bond gives you the full curve risk of the position.

Note the following:

• A BondForward rule using the Discounting model must include BondForwardModelOptions with bondForwardProjectionType set, otherwise LUSID rejects the recipe. Values are case-sensitive. BondForward isn't supported by ConstantTimeValueOfMoney. Under SimpleStatic, LUSID ignores these options and values from the contract's price quote.

• The deliverable must be a mastered Bond or ComplexBond in the same currency as the forward. You must master the BondForward too and value it in a portfolio, rather than valuing it on its own.

• LUSID looks up the forward contract's own price quote by its LUID, so you need a market data rule for Quote.LusidInstrumentId.*.

• DeliverableSpreadAnchoredToQuote requires a ZSpread quote for the deliverable. A credit spread curve doesn't replace it.

• Order the Price rule before the Rate rule for the ZSpread quote. If the Rate rule comes first, ForwardProjectedFromFundingCurve reads the ZSpread quote as the deliverable's price, and the valuation is wrong, with no error.

{
  "supplier": "Lusid",
  "modelName": "Discounting",
  "instrumentType": "BondForward",
  "modelOptions": {
    "modelOptionsType": "BondForwardModelOptions",
    "bondForwardProjectionType": "ForwardProjectedFromFundingCurve"
  }
}

FlexibleLoanPricerOptions

Use this option to report a standalone loan or deposit at the interest accrued so far, rather than including a clean value. This is common practice for private credit.

For example, a 1,000,000 loan at 5% drawn on 1 January and valued on 1 July has a PV of 1,024,794.52 by default, and 24,794.52 (the accrued interest) with setCleanPVToZero set to true.

{
  "supplier": "Lusid",
  "modelName": "FlexibleLoanPricer",
  "instrumentType": "FlexibleLoan",
  "modelOptions": {
    "modelOptionsType": "FlexibleLoanPricerOptions",
    "setCleanPVToZero": true
  }
}