IPA Volatility Surfaces : IR

This document describes the properties that can be used to construct Interest Rate Volatility Surfaces.

Refer to the Volatility Surfaces overview for details on how to structure the pricing request.

In what follows we will explain how to build the underlying definition section, define your own surface parameters and layout preferences, and what fields can be returned for Interest Rate Volatility Surface.

The column 'Underlying Type' provides the information about which instrument type a certain property applies to (Cap or Swaption).

Inputs

Input Name Type Description Importance Default Value
universe Array of objects The array of objects that describe the volatility surface and the surface preferences. Mandatory No default value applies.

Universe

  • The table below lists the properties that can be requested in the 'universe'.

Input Name Type Description Importance Default Value

underlyingType

 String (enumeration)

The type of underlying used to generate the volatility surface. The possible values are:

  • Cap: caplets stripping model is used,
  • Swaption: volatility cube (SABR calibration) is used.
 Mandatory No default value applies.
surfaceTag String A user-defined string to identify the volatility surface. It can be used to link output results to the requested definition. Limited to 40 characters. Only alphabetic, numeric and '- _.#=@' characters are supported. Optional No default value applies.
underlyingDefinition Object The definition of the volatility surface. For a detailed breakdown, please refer here. Mandatory No default value applies.
surfaceParameters Object The pricing parameters to be applied to the volatility surface. For a detailed breakdown, please refer here. Optional If not provided, default values of parameters are used.
surfaceLayout Object The list of properties used to modify the layout of the volatility surface in outputs. For a detailed breakdown, please refer here. Optional If not provided, default values of parameters are used.

Underlying Definition

  • The table below contains properties of underlyingDefinition object, possible values of these properties for different instrument types and information about whether each property can be used with certain value of instrumentType.

Input Name Type Description Importance Default Value Underlying Type
instrumentCode String

The code to be applied to the volatility surface model. The value is a currency code and is expressed in ISO 4217 alphabetical format (e.g., 'USD').

 Mandatory No default value applies.
  • Cap
  • Swaption
discountingType String (enumeration)

The parameter for selecting the discounting curve and volatilities used to calibrate the model. The possible values are:

  • OisDiscounting,
  • LiborDiscounting.
 Optional The default value is selected depending on instrumentCode.
  • Cap
  • Swaption
indexName String The underlying index name (e.g. 'EURIBOR'). The possible values depending on the currency are listed here. Optional The default value is selected depending on instrumentCode.
  • Cap
  • Swaption
underlyingSwapStructure String The reference to a style of the underlying swap. The possible values depending on the currency are listed here. Optional No default value applies.
  • Swaption
indexTenor String The period code indicating the tenor of the floating rate index of the projected zero coupon curve, which is used to calculate swap rates (e.g., '1M', '1Y'). Optional The default value is the index tenor associated with the underlyingSwapStructure (for 'EUR_AB6E', it is '6M').
  • Swaption
referenceCapletTenor String The period code indicating the tenor of the reference caplet (e.g., '1M', '1Y'). Optional No default value applies.
  • Cap

Surface Parameters

  • The table below contains properties of surfaceParameters object, possible values of these properties for different instrument types and information about whether each property can be used with certain value of instrumentType.

  • Note: 'Date' and 'Tenor' values cannot be set at a time for xAxis and yAxis properties; 'Strike' and 'Moneyness' values cannot be set at a time for xAxis and yAxis properties. 

Input Name Type Description Underlying Type = Cap Underlying Type = Swaption Importance Default Value
xAxis String (enumeration)

The enumerate that specifies the unit for the 'x' axis.

The possible values are:

  • Date,
  • Strike,
  • Tenor,
  • Moneyness.

The possible values are:

  • Strike,
  • Tenor,
  • Expiry.
 Optional The default value is 'Strike'.
yAxis String  (enumeration)

The enumerate that specifies the unit for the 'y' axis.

The possible values are:

  • Date,
  • Strike,
  • Tenor,
  • Moneyness.

The possible values are:

  • Strike,
  • Tenor,
  • Expiry.
 Optional The default value is 'Tenor'.
zAxis String  (enumeration)

The enumerate that specifies the unit for the 'z' axis. 

 N/A

The possible values are:

  • Strike,
  • Tenor,
  • Expiry.
 Optional The default value is 'Expiry'.

valuationDate

 DateTime

The date at which the volatility surface is valued. The value is expressed in ISO 8601 format: YYYY-MM-DDT[hh]:[mm]:[ss]Z (e.g., '2021-01-01T00:00:00Z').

 Applies Applies Optional The default value is today's date.

source

 String

The contributor of the volatility data.

 Applies Applies Optional The default value is selected based on instrumentCode and indexName.
includeCapletsVolatility Boolean The indicator of whether the volatility cube is computed from interpolations on volatility skews, or via ATM swaption volatility and caplets volatility. The possible values are:
  •  True: caplets volatility is included,
  •  False: caplets volatility is not included.
If underlyingType = 'Swaption' and useSmartParams = 'True', this parameter can not be 'False'.		 Applies Applies Optional The default value is 'True'.
volatilityAdjustmentType String (enumeration)

Volatility adjustment method applied to caplets surface before stripping. The possible values are:

  • ConstantCap,
  • ConstantCaplet,
  • NormalizedCap,
  • NormalizedCaplet,
  • ShiftedCap.
 Applies Applies Optional The default value is 'ConstantCap'.
inputVolatilityType String

The type of volatility used for calibration. The possible values are:

  • Default,
  • LogNormalVolatility  (applicable for underlytingType = 'Cap' only),
  • NormalVolatility. 

Note: In most cases it would be preferable to let the service determine the most appropriate one.

 Applies Applies Optional The default value is 'Default'.
outputVolatilityType String (enumeration) The volatility can be expressed as lognormal volatility (%) or normal volatility (bp). The possible values are:
  • Default,
  • LogNormalVolatility,
  • NormalVolatility.

For underlyingType = 'Cap', the value of inputVolatilityType is used.

 N/A Applies Optional The default value is 'Default'.
strikeType

String (enumeration)

The strike axis type of the volatility cube surface. The possible values are:

  • AbsolutePercent,
  • RelativePercent 
 N/A Applies Optional The default value is 'RelativePercent'.
beta Double

The beta parameter that controls curvature of the SABR model. Any number between 0 and 1 (inclusive) can be specified.

 N/A Applies Optional The default value is '0.45'.
calibrationType

String (enumeration)

The Calibration type defines the solver used during calibration (i.e. SABR Model Calibration Optimization Method). The possible values:

  • ConjugateGradient,
  • AlternateConjugateGradient,
  • Powell,
  • SimplexNelderMead.
 N/A Applies Optional The default value is selected based on instrumentCode.
shiftPercent Double The shift applied to calibrated strikes allowing negative rates. The value is expressed in percentages.
The value can not be negative.		 N/A Applies Optional The default value is selected based on instrumentCode.
useSmartParams Boolean

An indicator if a first SABR calibration is used to estimate the model initial parameters (correlation and volatility of volatility). The possible values are:

  • True: pre-calibration is used to estimate initial parameters,
  • False: arbitrary initial parameters are used.

It can not be used if includeCapletsVolatility = 'False'.

 N/A Applies Optional The default value is 'False'.

strippingShiftPercent

 Double

The shift applied to strikes allowing the stripped caplets surface to include volatility even when some strikes are negative. The value is expressed in percentages.
The value can not be negative.

 N/A Applies Optional

The default value is selected based on instrumentCode.

Surface Layout

  • The table below contains properties of surfaceLayout object, possible values of these properties for different instrument types and information about whether each property can be used with certain value of instrumentType.

Input Name Type Description Importance Default Value Underlying Type
format String (enumeration)

The enumerate that specifies the format of the returned volatility surface. The possible values are:

  • Matrix,
  • List,
  • NDimensionalArray (applicable to Swaption only).
 Optional. The default value is 'Matrix'.
  • Cap
  • Swaption

xValues

 Array of string

The array that specifies values of discrete data points on the x-axis. The possible values are determined by value of xAxis.

 Optional The default value is selected depending on the value set in xAxis.
  • Cap
  • Swaption

yValues

 Array of string

The array that specifies values of discrete data points on the y-axis. The possible values are determined by value of yAxis.

 Optional The default value is selected depending on the value set in yAxis.
  • Cap
  • Swaption
zValues Array of string

The array that specifies values of discrete data points on the z-axis.
The possible values are determined by value of zAxis.

 Optional No default value applies.
  • Swaption

 

Outputs

  • The table below lists the outputs and contains information about whether each output is returned for certain value of instrumentType.
Output Name Type Description Underlying Type
surfaceTag String A user-defined string to identify the volatility surface.
  • Cap
  • Swaption
surface Array of arrays The values of the properties that apply to the constructed volatility surface. It is returned if the surface layout's format is set to 'Matrix' or 'List'.
  • Cap
  • Swaption
headers Array of strings The names of the properties that apply to the constructed volatility surface. It is returned if the surface layout's format is set to  'List'.
  • Cap
  • Swaption
ndimensionalArrayShape Array of integers The numbers that describe the size of the constructed volatility surface (i.e. number of points on each dimension of the cube). It is returned if the surface layout's format is set to 'NDimensionalArray'.
  • Swaption
ndimensionalArray Array of strings The values of the properties that apply to the constructed volatility surface (cube). It is returned if the surface layout's format is set to 'NDimensionalArray'.
  • Swaption
x Array of strings The array of points on x-axis. It is returned if the surface layout's format is set to 'NDimensionalArray'.
  • Swaption
y Array of strings The array of points on y-axis. It is returned if the surface layout's format is set to 'NDimensionalArray'.
  • Swaption
z Array of strings The array of points on z-axis. It is returned if the surface layout's format is set to 'NDimensionalArray'.
  • Swaption