ZeroCouponInflationCap

ZeroCouponInflationCap instrument object

Since R2023b

Description

Create and price a ZeroCouponInflationCap instrument object for one or more Zero-Coupon Inflation Cap instruments using this workflow:

Use fininstrument to create a ZeroCouponInflationCap instrument object for one or more Zero-Coupon Inflation Cap instruments.
Use finmodel to specify a JarrowYildirim model object for the ZeroCouponInflationCap instrument object.
Use ratecurve to specify a NominalCurve interest-rate model for the ZeroCouponInflationCap instrument object.
Use ratecurve to specify a RealCurve interest-rate model for the ZeroCouponInflationCap instrument object.
Use finpricer to specify a JarrowYildirim pricing method for one or more ZeroCouponInflationCap instruments.

For more information on this workflow, see Get Started with Workflows Using Object-Based Framework for Pricing Financial Instruments.

For more information on the available models and pricing methods for a ZeroCouponInflationCap instrument, see Choose Instruments, Models, and Pricers.

Creation

Syntax

ZCInflationCap = fininstrument(InstrumentType,Maturity=maturity_date,Notional=notional_value,Strike=strike_value)

ZCInflationCap = fininstrument(___,Name=Value)

Description

ZCInflationCap = fininstrument(InstrumentType,Maturity=maturity_date,Notional=notional_value,Strike=strike_value) creates a ZeroCouponInflationCap object for one or more Zero-Coupon Inflation Cap instruments by specifying InstrumentType and sets the properties for the required name-value arguments Maturity, Notional, and Strike.

example

ZCInflationCap = fininstrument(___,Name=Value) sets optional properties using name-value arguments in addition to the required arguments in the previous syntax. For example, ZCInflationCap = fininstrument("ZeroCouponInflationCap",Maturity=datetime(2033,10,1),Notional=1000,Strike=0.05,Basis=4) creates a ZeroCouponInflationCap instrument with a day count basis of 4. You can specify multiple name-value arguments, in any order.

example

Input Arguments

expand all

`InstrumentType` — Instrument type
string with value `"ZeroCouponInflationCap"` | string array with values of `"ZeroCouponInflationCap"` | character vector with value `'ZeroCouponInflationCap'` | cell array of character vectors with values of `'ZeroCouponInflationCap'`

Instrument type, specified as a string with the value of "ZeroCouponInflationCap", a character vector with the value of 'ZeroCouponInflationCap', an NINST-by-1 string array with values of "ZeroCouponInflationCap", or an NINST-by-1 cell array of character vectors with values of 'ZeroCouponInflationCap'.

Data Types: char | cell | string

Name-Value Arguments

Specify required and optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: ZCInflationCap = fininstrument("ZeroCouponInflationCap",Maturity=datetime(2033,10,1),Notional=1000,Strike=0.05,Basis=4)

Required ZeroCouponInflationCap Name-Value Arguments

expand all

`Maturity` — Contract maturity date
datetime | string | date character vector

Contract maturity date, specified as a scalar datetime, string, or date character vector or an NINST-by-1 vector using a datetime array, string array, or date character vectors.

If you use date character vectors or strings, the format must be recognizable by datetime because the Maturity property is stored as a datetime.

Data Types: double | string | datetime

`Notional` — Notional amount
scalar numeric | numeric vector

Notional amount, specified as a scalar numeric or an NINST-by-1 numeric vector.

Data Types: double

`Strike` — Fixed annual inflation rate strike
scalar decimal | vector of decimals

Fixed annual inflation rate strike, specified as a scalar decimal or an NINST-by-1 vector of decimals.

Data Types: double

Optional ZeroCouponInflationCap Name-Value Arguments

expand all

`StartDate` — Date the contract starts
`Settle` date (default) | datetime | string | date character vector | datetime array | string array | cell array of date character vectors

Date contract starts, specified as a scalar datetime, string, or character vector, or an NINST-by-1 vector using a datetime array, string array, or cell array of date character vectors. If you do not specify a value for StartDate, when pricing the ZeroCouponInflationCap instrument, the JarrowYildirim pricer uses the Settle date of the DiscountCurve as the date that the contract starts.

If you use date character vectors or strings, the format must be recognizable by datetime because the StartDate property is stored as a datetime.

Data Types: char | datetime | string

`Basis` — Day count basis
`0` (actual/actual) (default) | scalar integer from `0` to `13` | vector of integers from `0` to `13`

Day count basis, specified as a scalar integer or an NINST-by-1 vector of integers for the following:

0 — actual/actual
1 — 30/360 (SIA)
2 — actual/360
3 — actual/365
4 — 30/360 (PSA)
5 — 30/360 (ISDA)
6 — 30/360 (European)
7 — actual/365 (Japanese)
8 — actual/actual (ICMA)
9 — actual/360 (ICMA)
10 — actual/365 (ICMA)
11 — 30/360E (ICMA)
12 — actual/365 (ISDA)
13 — BUS/252

For more information, see Basis.

Data Types: double

`IssueIndex` — Inflation index at issue date
`CurrentIndex` in `JarrowYildirim` model object (default) | numeric

Inflation index at the issue date, specified as a scalar numeric or an NINST-by-1 vector of numeric values. The inflation index for IssueIndex depends on the country and can be from any of the following:

US — CPI (US Consumer Price Index Urban Consumers (CPI-U))
UK — RPI (UK Retail Price Index (RPI))
Canada — CPI (Canada All-Items Consumer Price Index)
European Union (EU) — HICP-ex Tobacco (EU Harmonized Indices of Consumer Prices (HICP) ex-Tobacco)
Japan — CPI (Japan Consumer Price Index)
China — CPI (China Consumer Price Index)

Note

When you price a ZeroCouponInflationCap instrument using the JarrowYildirim pricer, by default, the IssueIndex value is the CurrentIndex value in the JarrowYildirim model object.

Data Types: double

`Name` — User-defined name for instrument
`""` (default) | string | string array | character vector | cell array of character vectors

User-defined name for the instrument, specified as a scalar string or character vector or an NINST-by-1 cell array of character vectors or string array.

Data Types: char | cell | string

Properties

expand all

`Maturity` — Contract maturity date
scalar datetime | vector of datetimes

Contract maturity date, returned as a scalar datetime or an NINST-by-1 vector of datetimes.

Data Types: datetime

`Notional` — Notional amount
scalar numeric | numeric vector

Notional amount, returned as a scalar numeric or an NINST-by-1 vector of decimals.

Data Types: double

`Strike` — Fixed annual inflation rate strike
scalar decimal | vector of decimals

Fixed annual inflation rate strike, returned as a scalar decimal or an NINST-by-1 vector of decimals.

Data Types: double

`Basis` — Day count basis
`0` (actual/actual) (default) | scalar integer from `0` to `13` | vector of integers from `0` to `13`

Day count basis, returned as a scalar integer or an NINST-by-1 vector of integers.

Data Types: double

`IssueIndex` — Inflation index at issue date
`CurrentIndex` in `JarrowYildirim` model object (default) | numeric

Inflation index at the issue date, returned as a scalar numeric or an NINST-by-1 vector of numeric values.

Data Types: double

`Name` — User-defined name for instrument
`""` (default) | string

User-defined name for the instrument, returned as a string or an NINST-by-1 string array.

Data Types: string

Examples

collapse all

Price `ZeroCouponInflationCap` Instrument Using `JarrowYildirim` Model and `JarrowYildirim` Pricer

Open Live Script

This example shows the workflow to price a ZeroCouponInflationCap instrument when using a JarrowYildirim model and a JarrowYildirim pricing method.

Create ZeroCouponInflationCap Instrument Object

Use fininstrument to create a ZeroCouponInflationCap instrument object.

ZCInflationCap = fininstrument("ZeroCouponInflationCap",Maturity=datetime(2033,10,1),Notional=1000,Strike=0.05,Name="ZCInflationCap")

ZCInflationCap = 
  ZeroCouponInflationCap with properties:

      Notional: 1000
        Strike: 0.0500
         Basis: 0
    IssueIndex: NaN
     StartDate: NaT
      Maturity: 01-Oct-2033
          Name: "ZCInflationCap"

Create JarrowYildirim Model Object

Use finmodel to create a JarrowYildirim model object.

JarrowYildirimModel = finmodel("JarrowYildirim", ...
        NominalVolatility=0.008,RealVolatility=0.005,IndexVolatility=0.01, ...
        NominalConstant=0.04,RealConstant=0.05, ...
        NominalRealCorrelation=0.015,RealIndexCorrelation=-0.32, ...
        NominalIndexCorrelation=0.08,CurrentIndex=101)

JarrowYildirimModel = 
  JarrowYildirim with properties:

          NominalVolatility: 0.0080
             RealVolatility: 0.0050
            IndexVolatility: 0.0100
            NominalConstant: 0.0400
               RealConstant: 0.0500
     NominalRealCorrelation: 0.0150
       RealIndexCorrelation: -0.3200
    NominalIndexCorrelation: 0.0800
               CurrentIndex: 101

Create ratecurve Object

Create a ratecurve object using ratecurve to specify the NominalCurve and RealCurve.

Settle = datetime(2023,10,1);

ZeroTimes = [calmonths(6) calyears([1 2 3 5 7 10 20 30])];
NominalRates = [4.70 4.68 4.14 3.83 3.56 3.51 3.48 3.77 3.66]'./100;
RealRates = [1.47 1.55 1.31 1.30 1.33 1.28 1.25 1.33 1.42]'./100;
ZeroDates = Settle + ZeroTimes;
NominalCurve = ratecurve("zero",Settle,ZeroDates,NominalRates);
RealCurve = ratecurve("zero",Settle,ZeroDates,RealRates);

Create JarrowYildirim Pricer Object

Use finpricer to create a JarrowYildirim object and specify the ratecurve object for the NominalCurve and RealCurve name-value arguments.

JarrowYildirimPricer = finpricer("analytic",Model=JarrowYildirimModel,NominalCurve=NominalCurve,RealCurve=RealCurve)

JarrowYildirimPricer = 
  JarrowYildirim with properties:

           Model: [1x1 finmodel.JarrowYildirim]
    NominalCurve: [1x1 ratecurve]
       RealCurve: [1x1 ratecurve]

Price YearYearInflationCap Instrument

Use price to compute the price for the ZeroCouponInflationCap instrument.

ZCInflationCapPrice = price(JarrowYildirimPricer,ZCInflationCap)

ZCInflationCapPrice = 
2.8981

Price Multiple `ZeroCouponInflationCap` Instruments Using `JarrowYildirim` Model and `JarrowYildirim` Pricer

Open Live Script

This example shows the workflow to price multiple ZeroCouponInflationCap instruments when using a JarrowYildirim model and a JarrowYildirim pricing method.

Create ZeroCouponInflationCap Instrument Object

Use fininstrument to create a ZeroCouponInflationCap instrument object.

Maturity = datetime([2024,1,1 ; 2024,11,1 ; 2024,12,1]);
Notional = [20000 ; 30000 ; 40000];
ZCInflationCap = fininstrument("ZeroCouponInflationCap",Maturity=Maturity,Notional=Notional,Strike=0.05,Name="ZCInflationCap")

ZCInflationCap=3×1 ZeroCouponInflationCap array with properties:
    Notional
    Strike
    Basis
    IssueIndex
    StartDate
    Maturity
    Name

Create JarrowYildirim Model Object

Use finmodel to create a JarrowYildirim model object.

JarrowYildirimModel = finmodel("JarrowYildirim", ...
        NominalVolatility=0.008,RealVolatility=0.005,IndexVolatility=0.01, ...
        NominalConstant=0.04,RealConstant=0.05, ...
        NominalRealCorrelation=0.015,RealIndexCorrelation=-0.32, ...
        NominalIndexCorrelation=0.08,CurrentIndex=101)

JarrowYildirimModel = 
  JarrowYildirim with properties:

          NominalVolatility: 0.0080
             RealVolatility: 0.0050
            IndexVolatility: 0.0100
            NominalConstant: 0.0400
               RealConstant: 0.0500
     NominalRealCorrelation: 0.0150
       RealIndexCorrelation: -0.3200
    NominalIndexCorrelation: 0.0800
               CurrentIndex: 101

Create ratecurve Object

Create a ratecurve object using ratecurve to specify the NominalCurve and RealCurve.

Settle = datetime(2023,10,1);

ZeroTimes = [calmonths(6) calyears([1 2 3 5 7 10 20 30])];
NominalRates = [4.70 4.68 4.14 3.83 3.56 3.51 3.48 3.77 3.66]'./100;
RealRates = [1.47 1.55 1.31 1.30 1.33 1.28 1.25 1.33 1.42]'./100;
ZeroDates = Settle + ZeroTimes;
NominalCurve = ratecurve("zero",Settle,ZeroDates,NominalRates);
RealCurve = ratecurve("zero",Settle,ZeroDates,RealRates);

Create JarrowYildirim Pricer Object

Use finpricer to create a JarrowYildirim object and specify the ratecurve object for the NominalCurve and RealCurve name-value arguments.

JarrowYildirimPricer = finpricer("analytic",Model=JarrowYildirimModel,NominalCurve=NominalCurve,RealCurve=RealCurve)

JarrowYildirimPricer = 
  JarrowYildirim with properties:

           Model: [1x1 finmodel.JarrowYildirim]
    NominalCurve: [1x1 ratecurve]
       RealCurve: [1x1 ratecurve]

Price ZeroCouponInflationCap Instruments

Use price to compute the prices for the three ZeroCouponInflationCap instruments.

[ZCInflationCapPrice,outPR] = price(JarrowYildirimPricer,ZCInflationCap,"all")

ZCInflationCapPrice = 3×1

   12.5264
   12.0850
   15.4779

outPR=1×3 priceresult array with properties:
    Results
    PricerData

More About

expand all

Zero Coupon Inflation-Indexed Cap

A zero coupon inflation-indexed cap is a contract where the buyer pays a premium to receive a fixed payment if inflation exceeds a predetermined cap rate.

The payment, made at the contract's end, is the difference between the realized inflation rate and the cap rate. If inflation is below the cap, no payment is made. The contract, typically linked to an inflation index like the Consumer Price Index (CPI), provides protection if the inflation rate exceeds the cap level. The holder receives a payment based on the difference between the actual inflation rate and the cap. The contract has an expiration date and applies for a specified period, adjustable for longer or shorter durations.

Algorithms

To price a zero coupon inflation-indexed cap using a JarrowYildirim and a JarrowYildirim pricing method:

$\begin{array}{l} K = (^{1 + κ) M} = (^{1 + S t r i k e) M} \\ Z C I C a p (t, T_{M}, I_{0}, K, N) = N P_{n} (t, T_{M}) [m Φ (\frac{\ln \frac{m}{K} + \frac{1}{2} V^{2} (t, T_{M})}{V (t, T_{M})}) - K Φ (\frac{\ln \frac{m}{K} - \frac{1}{2} V^{2} (t, T_{M})}{V (t, T_{M})})] \\ Z C I F l o o r (t, T_{M}, I_{0}, K, N) = N P_{n} (t, T_{M}) [K Φ (- \frac{\ln \frac{m}{K} - \frac{1}{2} V^{2} (t, T_{M})}{V (t, T_{M})}) - m Φ (- \frac{\ln \frac{m}{K} + \frac{1}{2} V^{2} (t, T_{M})}{V (t, T_{M})})] \\ m = E_{n}^{T_{M}} [\frac{I (T_{M})}{I_{0}} | ℱ_{t}] = \frac{I (t)}{I_{0}} E_{n}^{T_{M}} [\frac{I (T_{M})}{I (t)} | ℱ_{t}] = \frac{I (t)}{I_{0}} \frac{P_{r} (t, T_{M})}{P_{n} (t, T_{M})} \\ V^{2} (t, T_{M}) = σ_{I}^{2} (T_{M} - t) \\ + \frac{σ_{n}^{2}}{a_{n}^{2}} [T_{M} - t + \frac{2}{a_{n}} e^{- a_{n} (T_{M} - t)} - \frac{1}{2 a_{n}} e^{- 2 a_{n} (T_{M} - t)} - \frac{3}{2 a_{n}}] \\ + \frac{σ_{r}^{2}}{a_{r}^{2}} [T_{M} - t + \frac{2}{a_{r}} e^{- a_{r} (T_{M} - t)} - \frac{1}{2 a_{r}} e^{- 2 a_{r} (T_{M} - t)} - \frac{3}{2 a_{r}}] \\ - 2 ρ_{n, r} \frac{σ_{n} σ_{r}}{a_{n} a_{r}} [T_{M} - t - B_{n} (t, T_{M}) - B_{r} (t, T_{M}) + \frac{1 - e^{- (a_{n} + a_{r}) (T_{M} - t)}}{a_{n} + a_{r}}] \\ + 2 ρ_{n, I} \frac{σ_{n} σ_{I}}{a_{n}} [T_{M} - t - B_{n} (t, T_{M})] - 2 ρ_{r, I} \frac{σ_{r} σ_{I}}{a_{r}} [T_{M} - t - B_{r} (t, T_{M})] \\ B_{r} (t, T_{M}) = \frac{1 - e^{- a_{r} (T_{M} - t)}}{a_{r}} \\ B_{n} (t, T_{M}) = \frac{1 - e^{- a_{n} (T_{M} - t)}}{a_{n}} \end{array}$

where:

N is the notional value.
k is the fixed annual inflation rate cap or floor strike.
K = 1 + k is one plus the cap or floor strike.
M is the maturity in years.
T_M is the maturity date.
I(t) is the inflation index at t.
I₀ is the issue index.
$Φ (\cdot)$ is the standard normal cumulative distribution.
$P_{x} (t, T)$ is the zero coupon price (where n is nominal and r is real).
$σ_{n}$ is the nominal rate volatility (positive constant).
$σ_{r}$ is the real rate volatility (positive constant).
$σ_{I}$ is the inflation index volatility (positive constant).
$ρ_{r, I}$ is the real rate and inflation index correlation.
$ρ_{n, I}$ is the nominal rate and inflation index correlation.
$ρ_{n, r}$ is the nominal rate and real rate correlation.
$a_{n}$ , $a_{r}$ are the positive constants.

References

[1] Jarrow, R. and Yildirim, Y. "Pricing Treasury Inflation Protected Securities and Related Derivatives using an HJM Model." Journal of Financial and Quantitative Analysis. Vol. 38, 2003.

[2] Kerkhof, J. "Inflation Derivatives Explained: Markets, Products, and Pricing." Fixed Income Quantitative Research, Lehman Brothers, July 2005.

[3] Mercurio, F. "Pricing Inflation-Indexed Derivatives." Quantitative Finance, Vol. 5, Issue 3, pp .289–302, 2005.

Version History

Introduced in R2023b

ZeroCouponInflationCap

Description

Creation

Syntax

Description

Input Arguments

`InstrumentType` — Instrument type
string with value `"ZeroCouponInflationCap"` | string array with values of `"ZeroCouponInflationCap"` | character vector with value `'ZeroCouponInflationCap'` | cell array of character vectors with values of `'ZeroCouponInflationCap'`

`Maturity` — Contract maturity date
datetime | string | date character vector

`Notional` — Notional amount
scalar numeric | numeric vector

`Strike` — Fixed annual inflation rate strike
scalar decimal | vector of decimals

`StartDate` — Date the contract starts
`Settle` date (default) | datetime | string | date character vector | datetime array | string array | cell array of date character vectors

`Basis` — Day count basis
`0` (actual/actual) (default) | scalar integer from `0` to `13` | vector of integers from `0` to `13`

`IssueIndex` — Inflation index at issue date
`CurrentIndex` in `JarrowYildirim` model object (default) | numeric

`Name` — User-defined name for instrument
`""` (default) | string | string array | character vector | cell array of character vectors

Properties

`Maturity` — Contract maturity date
scalar datetime | vector of datetimes

`Notional` — Notional amount
scalar numeric | numeric vector

`Strike` — Fixed annual inflation rate strike
scalar decimal | vector of decimals

`Basis` — Day count basis
`0` (actual/actual) (default) | scalar integer from `0` to `13` | vector of integers from `0` to `13`

`IssueIndex` — Inflation index at issue date
`CurrentIndex` in `JarrowYildirim` model object (default) | numeric

`Name` — User-defined name for instrument
`""` (default) | string

Examples

Price `ZeroCouponInflationCap` Instrument Using `JarrowYildirim` Model and `JarrowYildirim` Pricer

Price Multiple `ZeroCouponInflationCap` Instruments Using `JarrowYildirim` Model and `JarrowYildirim` Pricer

More About

Zero Coupon Inflation-Indexed Cap

Algorithms

References

Version History

See Also

Functions

Topics

ZeroCouponInflationCap

Description

Creation

Syntax

Description

Input Arguments

InstrumentType — Instrument type string with value "ZeroCouponInflationCap" | string array with values of "ZeroCouponInflationCap" | character vector with value 'ZeroCouponInflationCap' | cell array of character vectors with values of 'ZeroCouponInflationCap'

Maturity — Contract maturity date datetime | string | date character vector

Notional — Notional amount scalar numeric | numeric vector

Strike — Fixed annual inflation rate strike scalar decimal | vector of decimals

StartDate — Date the contract starts Settle date (default) | datetime | string | date character vector | datetime array | string array | cell array of date character vectors

Basis — Day count basis 0 (actual/actual) (default) | scalar integer from 0 to 13 | vector of integers from 0 to 13

IssueIndex — Inflation index at issue date CurrentIndex in JarrowYildirim model object (default) | numeric

Name — User-defined name for instrument "" (default) | string | string array | character vector | cell array of character vectors

Properties

Maturity — Contract maturity date scalar datetime | vector of datetimes

Notional — Notional amount scalar numeric | numeric vector

Strike — Fixed annual inflation rate strike scalar decimal | vector of decimals

Basis — Day count basis 0 (actual/actual) (default) | scalar integer from 0 to 13 | vector of integers from 0 to 13

IssueIndex — Inflation index at issue date CurrentIndex in JarrowYildirim model object (default) | numeric

Name — User-defined name for instrument "" (default) | string

Examples

Price ZeroCouponInflationCap Instrument Using JarrowYildirim Model and JarrowYildirim Pricer

Price Multiple ZeroCouponInflationCap Instruments Using JarrowYildirim Model and JarrowYildirim Pricer

More About

Zero Coupon Inflation-Indexed Cap

Algorithms

References

Version History

See Also

Functions

Topics

`InstrumentType` — Instrument type
string with value `"ZeroCouponInflationCap"` | string array with values of `"ZeroCouponInflationCap"` | character vector with value `'ZeroCouponInflationCap'` | cell array of character vectors with values of `'ZeroCouponInflationCap'`

`Maturity` — Contract maturity date
datetime | string | date character vector

`Notional` — Notional amount
scalar numeric | numeric vector

`Strike` — Fixed annual inflation rate strike
scalar decimal | vector of decimals

`StartDate` — Date the contract starts
`Settle` date (default) | datetime | string | date character vector | datetime array | string array | cell array of date character vectors

`Basis` — Day count basis
`0` (actual/actual) (default) | scalar integer from `0` to `13` | vector of integers from `0` to `13`

`IssueIndex` — Inflation index at issue date
`CurrentIndex` in `JarrowYildirim` model object (default) | numeric

`Name` — User-defined name for instrument
`""` (default) | string | string array | character vector | cell array of character vectors

`Maturity` — Contract maturity date
scalar datetime | vector of datetimes

`Notional` — Notional amount
scalar numeric | numeric vector

`Strike` — Fixed annual inflation rate strike
scalar decimal | vector of decimals

`Basis` — Day count basis
`0` (actual/actual) (default) | scalar integer from `0` to `13` | vector of integers from `0` to `13`

`IssueIndex` — Inflation index at issue date
`CurrentIndex` in `JarrowYildirim` model object (default) | numeric

`Name` — User-defined name for instrument
`""` (default) | string

Price `ZeroCouponInflationCap` Instrument Using `JarrowYildirim` Model and `JarrowYildirim` Pricer

Price Multiple `ZeroCouponInflationCap` Instruments Using `JarrowYildirim` Model and `JarrowYildirim` Pricer