Documentation

This is machine translation

Translated by Microsoft
Mouseover text to see original. Click the button below to return to the English version of the page.

Note: This page has been translated by MathWorks. Click here to see
To view all translated materials including this page, select Country from the country navigator on the bottom of this page.

Supported Interest-Rate Instruments

Bond

A bond is a long-term debt security with a preset interest-rate and maturity. At maturity, you must pay the principal and interest.

The price or value of a bond is determined by discounting the expected cash flows of the bond to the present, using the appropriate discount rate. The following equation represents the relationship of the expected cash flows and discount rate:

B0=C2[1(1+r2)2tr2]+F(1+r2)2t

where:

B0 is the bond value.

C is the annual coupon payment.

F is the face value of the bond.

r is the required return on the bond.

t is the number of years remaining until maturity.

Financial Instruments Toolbox™ supports the following for pricing and specifying a bond.

Function

Purpose

bondbybdt

Price a bond using a BDT interest-rate tree.

bondbyhw

Price a bond using an HW interest-rate tree.

bondbybk

Price a bond using a BK interest-rate tree.

bondbyhjm

Price a bond using an HJM interest-rate tree.

bondbycir

Price bonds using a CIR tree model.

bondbyzero

Price a bond using a set of zero curves.

instbond

Construct a bond instrument.

Convertible Bond

A convertible bond is a financial instrument that combines equity and debt features. It is a bond with the embedded option to turn it into a fixed number of shares. The holder of a convertible bond has the right, but not the obligation, to exchange the convertible security for a predetermined number of equity shares at a preset price. The debt component is derived from the coupon payments and the principal. The equity component is provided by the conversion feature.

Convertible bonds have several defining features:

  • Coupon — The coupon in convertible bonds are typically lower than coupons in vanilla bonds since investors are willing to take the lower coupon for the opportunity to participate in the company’s stock via the conversion.

  • Maturity — Most convertible bonds are issued with long-stated maturities. Short-term maturity convertible bonds usually do not have call or put provisions.

  • Conversion ratio — Conversion ratio is the number of shares that the holder of the convertible bond receives from exercising the call option of the convertible bond:

    Conversion ratio = par value convertible bond/conversion price of equity

    For example, a conversion ratio of 25 means a bond can be exchanged for 25 shares of stock. This also implies a conversion price of $40 (1000/25). This, $40, would be the price at which the owner would buy the shares. This can be expressed as a ratio or as the conversion price and is specified in the contract along with other provisions.

  • Option type:

    • Callable Convertible: a convertible bond that is callable by the issuer. The issuer of the bond forces conversion, removing the advantage that conversion is at the discretion of the bondholder. Upon call, the bondholder can either convert the bond or redeem at the call price. This option enables the issuer to control the price of the convertible bond and if necessary refinance the debt with a new cheaper one.

    • Puttable Convertible: a convertible bond with a put feature that allows the bondholder to sell back the bond at a premium on a specific date. This option protects the holder against rising interest rates by reducing the year to maturity.

Function

Purpose

cbondbycrr

Price convertible bonds using a CRR binomial tree with the Tsiveriotis and Fernandes model.

cbondbyeqp

Price convertible bonds using an EQP binomial tree with the Tsiveriotis and Fernandes model.

cbondbyitt

Price convertible bonds using an implied trinomial tree with the Tsiveriotis and Fernandes model.

cbondbystt

Price convertible bonds using a standard trinomial tree with the Tsiveriotis and Fernandes model.

instcbond

Construct a cbond instrument for a convertible bond.

Stepped Coupon Bonds

A step-up and step-down bond is a debt security with a predetermined coupon structure over time. With these instruments, coupons increase (step up) or decrease (step down) at specific times during the life of the bond. For more information on options features (call and puts), see Stepped Coupon Bonds with Calls and Puts. The following functions have a modified CouponRate argument to support a new variable coupon schedule allowing pricing of stepped coupon bonds.

Function

Purpose

bondbyzero

Price bonds using a term structure model.

bondbybdt

Price bonds using a BDT tree model.

bondbyhjm

Price bonds using an HJM tree model.

bondbyhw

Price bonds using an HW tree model.

bondbybk

Price bonds using a BK tree model.

bondbycir

Price bonds using a CIR tree model.

instbond

Construct a bond instrument.

instoptbnd

Construct a bond option instrument.

instdisp

Display instruments stored in a variable.

Sinking Fund Bonds

A sinking fund bond is a coupon bond with a sinking fund provision. This provision obligates the issuer to amortize portions of the principal before maturity, affecting bond prices since the time of the principal repayment changes. This means that investors receive the coupon and a portion of the principal paid back over time. These types of bonds reduce credit risk, since it lowers the probability of investors not receiving their principal payment at maturity. For more information on options support for sinking fund bonds, see Sinking Fund Bonds with an Embedded Option. The following functions have a modified Face argument to support a variable face schedule for pricing bonds with a sinking provisions.

Function

Purpose

bondbyzero

Price bonds using a term structure model.

bondbybdt

Price bonds using a BDT tree model.

bondbyhjm

Price bonds using an HJM tree model.

bondbyhw

Price bonds using an HW tree model.

bondbybk

Price bonds using a BK tree model.

bondbycir

Price bonds using a CIR tree model.

instoptbnd

Construct a bond option instrument.

instbond

Construct a bond instrument.

instdisp

Display instruments stored in a variable.

Bonds with an Amortization Schedule

A bond with an amortization schedule repays part of the principal (face value) along with the coupon payments. An amortizing bond is a special case of a sinking fund bond when there is no market purchase option and no call provision. The following functions have a modified Face argument to support an amortization schedule.

Function

Purpose

bondbyzero

Price bonds using a term structure model.

bondbybdt

Price bonds using a BDT tree model.

bondbyhjm

Price bonds using an HJM tree model.

bondbyhw

Price bonds using an HW tree model.

bondbybk

Price bonds using a BK tree model.

bondbycir

Price bonds using a CIR tree model.

Bond Options

Financial Instruments Toolbox supports three types of put and call options on bonds:

  • American option: An option that you exercise any time until its expiration date.

  • European option: An option that you exercise only on its expiration date.

  • Bermuda option: A Bermuda option resembles a hybrid of American and European options. You can exercise it on predetermined dates only, usually monthly.

Financial Instruments Toolbox supports the following for pricing and specifying a bond option.

Function

Purpose

optbndbybdt

Price a bond option price using a BDT interest-rate tree.

optbndbyhw

Price a bond option price using an HW interest-rate tree.

optbndbybk

Price a bond option price using a BK interest-rate tree.

optbndbyhjm

Price a bond option price using an HJM interest-rate tree.

optbndbycir

Price a bond option price using a CIR interest-rate tree.

instoptbnd

Construct a bond option instrument.

Bond with Embedded Options

A bond with embedded options allows the issuer to buy back or redeem the bond at a predetermined price at specified future dates. Financial Instruments Toolbox supports American, European, and Bermuda callable and puttable bonds.

The pricing for a bond with embedded options is as follows:

  • For a callable bond:PriceCallableBond=BondPrice-BondCallOption

  • For a puttable bond: PricePuttableBond = PriceBond + PricePutOption

In addition, Option Adjusted Spread (OAS) is a useful way to value and compare securities with embedded options, like callable or puttable bonds. For more information on OAS, see OAS for Callable and Puttable Bonds.

Financial Instruments Toolbox supports the following for pricing and specifying a bond with embedded options.

Function

Purpose

optembndbybdt

Price a bond with embedded options using a BDT interest-rate tree.

optembndbyhw

Price a bond with embedded options using an HW interest rate tree.

optembndbybk

Price a bond with embedded options using a BK interest-rate tree.

optembndbyhjm

Price a bond with embedded options using an HJM interest-rate tree.

optembndbycir

Price a bond with embedded options using a CIR interest-rate tree.

instoptembnd

Construct a bond-with-embedded-options instrument.

oasbybdt

Determine an option adjusted spread using Black-Derman-Toy model.

oasbybk

Determine an option adjusted spread using Black-Karasinski model.

oasbyhjm

Determine an option adjusted spread using Heath-Jarrow-Morton model.

oasbyhw

Determine an option adjusted spread using Hull-White model.

oasbycir

Determine an option adjusted spread using Cox-Ingersoll-Ross model.

agencyoas

Compute the OAS of the callable bond using the Agency OAS model.

agencyprice

Price the callable bond OAS using the Agency OAS model.

Stepped Coupon Bonds with Calls and Puts

A step-up and step-down bond is a debt security with a predetermined coupon structure over time. For more information on stepped coupon bonds, see Stepped Coupon Bonds. Stepped coupon bonds can have options features (call and puts). The following functions have a modified CouponRate argument to support a new variable coupon schedule allowing pricing stepped coupon bonds with callable and puttable features:

Function

Purpose

optembndbybdt

Price bonds with embedded options using a BDT model tree.

optembndbyhjm

Price bonds with embedded options using an HJM model tree.

optembndbybk

Price bonds with embedded options using a BK model tree.

optembndbyhw

Price bonds with embedded options using an HW model tree.

optembndbycir

Price bonds with embedded options using a CIR model tree.

instbond

Construct a bond instrument.

instoptbnd

Construct a bond option instrument.

instoptembnd

Construct a bond with an embedded option instrument.

instdisp

Display instruments stored in a variable.

Sinking Fund Bonds with an Embedded Option

A sinking fund bond is a coupon bond with a sinking fund provision. For more information on sinking fund bonds, see Sinking Fund Bonds. The sinking fund bond can have a sinking fund option provision allowing the issuer to retire the sinking fund obligation either by purchasing the bonds to be redeemed from the market or by calling the bond via a sinking fund call, whichever is cheaper.

If interest rates are high, then the issuer buys back the required amount of bonds from the market since bonds are cheap. But if interest rates are low (bond prices are high), then most likely the issuer buys the bonds at the call price. Unlike a call feature, however, if a bond has a sinking fund option provision, it is an obligation, not an option, for the issuer to buy back the increments of the issue as stated. Because of this, a sinking fund bond trades at a lower price than a nonsinking fund bond. The following functions have a modified Face argument to support a variable face schedule for pricing bonds with a sinking fund option provision.

Function

Purpose

optembndbybdt

Price bonds with embedded options using a BDT model tree.

optembndbyhjm

Price bonds with embedded options using an HJM model tree.

optembndbybk

Price bonds with embedded options using a BK model tree.

optembndbyhw

Price bonds with embedded options using an HW model tree.

optembndbycir

Price bonds with embedded options using a CIR model tree.

instbond

Construct a bond instrument.

instoptbnd

Construct a bond option instrument.

instdisp

Display instruments stored in a variable.

Fixed-Rate Note

A fixed-rate note is a long-term debt security with a preset interest rate and maturity, by which the interest must be paid. The principal may or may not be paid at maturity. In Financial Instruments Toolbox, the principal is always paid at maturity.

Function

Purpose

fixedbybdt

Price a fixed-rate note using a BDT interest-rate tree.

fixedbyhw

Price a fixed-rate note using an HW interest-rate tree.

fixedbybk

Price a fixed-rate note using a BK interest-rate tree.

fixedbyhjm

Price a fixed-rate note using an HJM interest-rate tree.

fixedbycir

Price a fixed-rate note using a CIR interest-rate tree.

fixedbyzero

Price a fixed-rate note using a set of zero curves.

instfixed

Construct a fixed-rate instrument.

Floating-Rate Note

A floating-rate note is a security like a bond, but the interest rate of the note is reset periodically, relative to a reference index rate, to reflect fluctuations in market interest rates.

Function

Purpose

floatbybdt

Price a floating-rate note using a BDT interest-rate tree.

floatbyhw

Price a floating-rate note using an HW interest-rate tree.

floatbybk

Price a floating-rate note using a BK interest-rate tree.

floatbyhjm

Price a floating-rate note using an HJM interest-rate tree.

floatbycir

Price a floating-rate note using a CIR interest-rate tree.

floatbyzero

Price a floating-rate note using a set of zero curves.

instfloat

Construct a floating-rate note instrument.

Floating-Rate Note with an Amortization Schedule

A floating-rate note with an amortization schedule repays part of the principal (face value) along with the coupon payments. The following functions have a Principal argument to support an amortization schedule.

Function

Purpose

floatbyzero

Price floating-rate note from set of zero curves.

floatbybdt

Price floating-rate note from Black-Derman-Toy interest-rate tree.

floatbyhjm

Price floating-rate note from Heath-Jarrow-Morton interest-rate tree.

floatbyhw

Price floating-rate note from Hull-White interest-rate tree.

floatbybk

Price floating-rate note from Black-Karasinski interest-rate tree.

floatbycir

Price a floating-rate note using a CIR interest-rate tree.

Floating-Rate Note with Caps, Collars, and Floors

A floating-rate note with caps, collars, and floors. This type of instrument can carry restrictions on the maximum (cap) or minimum (floor) coupon rate paid. A cap is an unattractive feature for an investor, since they constrain the coupon rates from increasing. A floor is an attractive feature, since it allows investors to get a minimum coupon rate when market rates decrease below a certain level. Also, a floating-rate note can have a collar which is a combination of a cap and a floor together. The following functions have a CapRate and FloorRate argument to support a capped, collared, or floored floating-rate note.

Function

Purpose

floatbybdt

Price a capped floating-rate note from a Black-Derman-Toy interest-rate tree.

floatbyhjm

Price a capped floating-rate note from a Heath-Jarrow-Morton interest-rate tree.

floatbyhw

Price a capped floating-rate note from a Hull-White interest-rate tree.

floatbybk

Price a capped floating-rate note from a Black-Karasinskiinterest-rate tree.

floatbycir

Price a floating-rate note using a CIR interest-rate tree.

instfloat

Create a capped floating-rate note instrument.

instadd

Add a capped floating-rate note instrument to a portfolio.

Floating-Rate Note with Options

Financial Instruments Toolbox supports three types of put and call options on floating-rate notes:

  • American option — An option that you exercise any time until its expiration date.

  • European option — An option that you exercise only on its expiration date.

  • Bermuda option — A Bermuda option resembles a hybrid of American and European options; you can only exercise it on predetermined dates, usually monthly.

Financial Instruments Toolbox supports the following for pricing and specifying a floating-rate note option:

Function

Purpose

optfloatbybdt

Price an option for floating-rate note using a Black-Derman-Toy interest-rate tree.

optfloatbyhjm

Price an option for floating-rate note using a Heath-Jarrow-Morton interest-rate tree.

optfloatbyhw

Price an option for floating-rate note using a Hull-White interest-rate tree.

optfloatbycir

Price an option for floating-rate note using a Cox-Ingersoll-Ross interest-rate tree.

optfloatbybk

Price an option for floating-rate note using a Black-Karasinski interest-rate tree.

instoptfloat

Define the option instrument for floating-rate note.

Floating-Rate Note with Embedded Options

A floating-rate note with an embedded option enables floating-rate notes to have early redemption features. An FRN with an embedded option gives investors or issuers the option to retire the outstanding principal prior to maturity. An embedded call option gives the right to retire the note prior to the maturity date (callable floater), and an embedded put option gives the right to sell the note back at a specific price (puttable floater).

Financial Instruments Toolbox supports the following for pricing and specifying a floating-rate note with an embedded option:

Function

Purpose

optemfloatbybdt

Price an embedded option for floating-rate note using a Black-Derman-Toy interest-rate tree.

optemfloatbybk

Price an embedded option for floating-rate note using a Black-Karasinski interest-rate tree.

optemfloatbyhjm

Price an embedded option for floating-rate note using a Heath-Jarrow-Morton interest-rate tree.

optemfloatbyhw

Price an embedded option for floating-rate note using a Hull-White interest-rate tree.

optemfloatbycir

Price an embedded option for floating-rate note using a Cox-Ingersoll-Ross interest-rate tree.

instoptemfloat

Define the floating-rate note with embedded option instrument.

Cap

A cap is a contract that includes a guarantee that sets the maximum interest rate to be paid by the holder, based on an otherwise floating interest rate. The payoff for a cap is:

max(CurrentRateCapRate,0)

Function

Purpose

capbybdt

Price a cap instrument using a BDT interest-rate tree.

capbyhw

Price a cap instrument using an HW interest-rate tree.

capbybk

Price a cap instrument using a BK interest-rate tree.

capbyhjm

Price a cap instrument using an HJM interest-rate tree.

capbycir

Price a cap instrument using a CIR interest-rate tree.

capbyblk

Price a cap instrument using the Black option pricing model.

capbynormal

Price a cap instrument with negative rates using the Normal (Bachelier) option pricing model.

capvolstrip

Strip caplet volatilities from flat cap volatilities.

instcap

Construct a cap instrument.

Floor

A floor is a contract that includes a guarantee setting the minimum interest rate to be received by the holder, based on an otherwise floating interest rate. The payoff for a floor is:

max(FloorRateCurrentRate,0)

Function

Purpose

floorbybdt

Price a floor instrument using a BDT interest-rate tree.

floorbyhw

Price a floor instrument using an HW interest-rate tree.

floorbybk

Price a floor instrument using a BK interest-rate tree.

floorbyhjm

Price a floor instrument using an HJM interest-rate tree.

floorbycir

Price a floor instrument using a CIR interest-rate tree.

floorbyblk

Price a floor instrument using the Black option pricing model.

floorbynormal

Price a floor instrument with negative rates using the Normal (Bachelier) option pricing model.

floorvolstrip

Strip floorlet volatilities from flat floor volatilities.

instfloor

Construct a floor instrument.

Range Note

A range note is a structured (market-linked) security whose coupon-rate is equal to the reference rate as long as the reference rate is within a certain range. If the reference rate is outside of the range, the coupon-rate is 0 for that period. This type of instrument entitles the holder to cash flows that depend on the level of some reference interest-rate that is floored to be positive and gives the holder of the note direct exposure to the reference rate. This type of instrument is useful for cases where you believe that interest rates will stay within a certain range. In return for the drawback that no interest is paid for the time the range is left, a range note offers higher coupon rates than comparable standard products, like vanilla floating notes.

Function

Purpose

instrangefloat

Create a range note instrument.

rangefloatbybdt

Price range floating note using a BDT tree.

rangefloatbybk

Price range floating note using a BK tree.

rangefloatbyhjm

Price range floating note using an HJM tree.

rangefloatbyhw

Price range floating note using an HW tree.

rangefloatbycir

Price range floating note using a CIR tree.

Swap

A swap is contract between two parties obligating the parties to exchange future cash flows. This toolbox version handles only the vanilla swap, which is composed of a floating-rate leg and a fixed-rate leg.

Function

Purpose

swapbybdt

Price a swap instrument using a BDT interest-rate tree.

swapbyhw

Price a swap instrument using an HW interest-rate tree.

swapbybk

Price a swap instrument using a BK interest-rate tree.

swapbyhjm

Price a swap instrument using an HJM interest-rate tree.

swapbycir

Price a swap instrument using a CIR interest-rate tree.

swapbyzero

Price a swap instrument using a set of zero curves and price cross currency swaps.

instswap

Construct a swap instrument.

Swap with an Amortization Schedule

A swap with an amortization schedule repays part of the principal (face value) along with the coupon payments. A swap with an amortization schedule is used to manage interest rate risk and serve as a cash flow management tool. For this particular type of swap, the notional amount decreases over time. This means that interest payments decrease not only on the floating leg but also on the fixed leg. The following swap functions have a Principal argument to support an amortization schedule.

Function

Purpose

swapbyzero

Price swap instrument from set of zero curves.

swapbybdt

Price swap instrument from Black-Derman-Toy interest-rate tree.

swapbyhjm

Price swap instrument from Heath-Jarrow-Morton interest-rate tree.

swapbyhw

Price swap instrument from Hull-White interest-rate tree.

swapbybk

Price swap instrument from Black-Karasinski interest-rate tree.

swapbycir

Price a swap instrument using a CIR interest-rate tree.

instswap

Construct swap instrument.

Forward Swap

In a forward interest-rate swap, a fixed interest-rate loan is exchanged for a floating interest-rate loan at a future specified date. The following functions have a StartDate argument to support the future date for the forward swap.

Function

Purpose

swapbyzero

Price a forward swap from a zero curve.

swapbybdt

Price a forward swap from a Black-Derman-Toy interest-rate tree.

swapbyhjm

Price a forward swap from a Heath-Jarrow-Morton interest-rate tree.

swapbyhw

Price a forward swap from a Hull-White interest-rate tree.

swapbybk

Price a forward swap from a Black-Karasinskiinterest-rate tree.

swapbycir

Price a swap instrument using a CIR interest-rate tree.

instswap

Create a forward swap instrument.

instadd

Add a capped floating-rate note instrument to a portfolio.

Swaption

A swaption is an option to enter into an interest-rate swap contract. A call swaption allows the option buyer to enter into an interest-rate swap where the buyer of the option pays the fixed-rate and receives the floating-rate. A put swaption allows the option buyer to enter into an interest-rate swap where the buyer of the option receives the fixed-rate and pays the floating-rate.

Function

Purpose

swaptionbybdt

Price a swaption instrument using a BDT interest-rate tree.

swaptionbyhw

Price a swaption instrument using an HW interest-rate tree.

swaptionbybk

Price a swaption instrument using a BK interest-rate tree.

swaptionbyhjm

Price a swaption instrument using an HJM interest-rate tree.

swaptionbycir

Price a swaption instrument using a CIR interest-rate tree.

swaptionbyblk

Price swaptions using the Black model with a forward on a swap.

swaptionbynormal

Price swaptions for negative rates using the Normal (Bachelier) model with a forward on a swap.

instswaption

Construct a swaption instrument.

Use swaptionbyblk to price a swaption using the Black model. The Black model is standard model used in the swaption market when pricing European swaptions. This type of model is widely used by when speed is important to quickly obtain a price at settlement date, even if the price is less accurate than other swaption pricing models based on interest-rate tree models.

Bond Futures

Bond futures are futures contracts where the commodity for delivery is a government bond. There are established global markets for government bond futures. Bond futures provide a liquid alternative for managing interest-rate risk.

In the US market, the Chicago Mercantile Exchange (CME) offers futures on Treasury bonds and notes with maturities of 2, 5, 10, and 30 years. Typically, the following bond future contracts from the CME have maturities of 3, 6, 9, and 12 months:

The short position in a Treasury bond or note future contract must deliver to the long position in one of many possible existing Treasury bonds. For example, in a 30-year Treasury bond future, the short position must deliver a Treasury bond with at least 15 years to maturity. Because these bonds have different values, the bond future contract is standardized by computing a conversion factor. The conversion factor normalizes the price of a bond to a theoretical bond with a coupon of 6%. The price of a bond future contract is represented as:

InvoicePrice=FutPrice×CF+AI

where:

FutPrice is the price of the bond future.

CF is the conversion factor for a bond to deliver in a futures contract.

AI is the accrued interest.

The short position in a futures contract has the option of which bond to deliver and, in the US bond market, when in the delivery month to deliver the bond. The short position typically chooses to deliver the bond known as the Cheapest to Deliver (CTD). The CTD bond most often delivers on the last delivery day of the month.

Financial Instruments Toolbox supports the following bond futures:

  • US Treasury bonds and notes

  • German Bobl, Bund, Buxl, and Schatz

  • UK gilts

  • Japanese government bonds (JGBs)

The functions supporting all bond futures are:

Function

Purpose

convfactor

Calculates bond conversion factors for US Treasury bonds, German Bobl, Bund, Buxl, and Schatz, UK gilts, and JGBs.

bndfutprice

Prices bond future given repo rates.

bndfutimprepo

Calculates implied repo rates for a bond future given price.

The functions supporting US Treasury bond futures are:

Function

Purpose

tfutbyprice

Calculates future prices of Treasury bonds given the spot price.

tfutbyyield

Calculates future prices of Treasury bonds given current yield.

tfutimprepo

Calculates implied repo rates for the Treasury bond future given price.

tfutpricebyrepo

Calculates Treasury bond futures price given the implied repo rates.

tfutyieldbyrepo

Calculates Treasury bond futures yield given the implied repo rates.

For more information on bond futures, see Bond Futures.

See Also

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

Related Examples

More About

Was this topic helpful?