Documentation

### This is machine translation

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

# swapbyhjm

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

## Syntax

``````[Price,PriceTree,CFTree,SwapRate] = swapbyhjm(HJMTree,LegRate,Settle,Maturity)``````
``````[Price,PriceTree,CFTree,SwapRate] = swapbyhjm(___,Name,Value)``````

## Description

example

``````[Price,PriceTree,CFTree,SwapRate] = swapbyhjm(HJMTree,LegRate,Settle,Maturity)``` prices a swap instrument from a Heath-Jarrow-Morton interest-rate tree. `swapbyhjm` computes prices of vanilla swaps, amortizing swaps and forward swaps.```

example

``````[Price,PriceTree,CFTree,SwapRate] = swapbyhjm(___,Name,Value)``` adds additional name-value pair arguments.```

## Examples

collapse all

This example shows how to price an interest-rate swap with a fixed receiving leg and a floating paying leg. Payments are made once a year, and the notional principal amount is \$100. The values for the remaining arguments are:

• Coupon rate for fixed leg: 0.06 (6%)

• Spread for floating leg: 20 basis points

• Swap settlement date: Jan. 01, 2000

• Swap maturity date: Jan. 01, 2003

Based on the information above, set the required arguments and build the `LegRate`, `LegType`, and `LegReset` matrices:

```Settle = '01-Jan-2000'; Maturity = '01-Jan-2003'; Basis = 0; Principal = 100; LegRate = [0.06 20]; % [CouponRate Spread] LegType = [1 0]; % [Fixed Float] LegReset = [1 1]; % Payments once per year ```

Price the swap using the `HJMTree` included in the MAT-file `deriv.mat`. The `HJMTree` structure contains the time and forward-rate information needed to price the instrument.

```load deriv.mat; ```

Use `swapbyhjm` to compute the price of the swap.

```[Price, PriceTree, CFTree] = swapbyhjm(HJMTree, LegRate,... Settle, Maturity, LegReset, Basis, Principal, LegType) ```
```Price = 3.6923 PriceTree = FinObj: 'HJMPriceTree' tObs: [0 1 2 3 4] PBush: {1x5 cell} CFTree = FinObj: 'HJMCFTree' tObs: [0 1 2 3 4] CFBush: { [1x1x2 double] [1x2x2 double] ... [1x8 double]}```

Use `treeviewer` to examine `CFTree` graphically and see the cash flows from the swap along both the up and the down branches. A positive cash flow indicates an inflow (income - payments > 0), while a negative cash flow indicates an outflow (income - payments < 0).

```treeviewer(CFTree) ``` In this example, you have sold a swap (receive fixed rate and pay floating rate). At time `t = 3`, if interest rates go down, your cash flow is positive (\$2.63), meaning that you receive this amount. But if interest rates go up, your cash flow is negative (-\$1.58), meaning that you owe this amount.

`treeviewer` price tree diagrams follow the convention that increasing prices appear on the upper branch of a tree and, so, decreasing prices appear on the lower branch. Conversely, for interest-rate displays, decreasing interest rates appear on the upper branch (prices are rising) and increasing interest rates on the lower branch (prices are falling).

Using the previous data, calculate the swap rate, which is the coupon rate for the fixed leg, such that the swap price at time = 0 is zero.

```LegRate = [NaN 20]; [Price, PriceTree, CFTree, SwapRate] = swapbyhjm(HJMTree,... LegRate, Settle, Maturity, LegReset, Basis, Principal, LegType) ```
```Price = 0 PriceTree = FinObj: 'HJMPriceTree' tObs: [0 1 2 3 4] PBush:{ [1x1x2 double] [1x2x2 double] ... [1x8 double]} CFTree = FinObj: 'HJMCFTree' tObs: [0 1 2 3 4] CFBush:{ [1x1x2 double] [1x2x2 double] ... [1x8 double]} SwapRate = 0.0466 ```

Price an amortizing swap using the `Principal` input argument to define the amortization schedule.

Create the `RateSpec`.

```Rates = 0.035; ValuationDate = '1-Jan-2011'; StartDates = ValuationDate; EndDates = '1-Jan-2017'; Compounding = 1; RateSpec = intenvset('ValuationDate', ValuationDate,'StartDates', StartDates,... 'EndDates', EndDates,'Rates', Rates, 'Compounding', Compounding)```
```RateSpec = struct with fields: FinObj: 'RateSpec' Compounding: 1 Disc: 0.8135 Rates: 0.0350 EndTimes: 6 StartTimes: 0 EndDates: 736696 StartDates: 734504 ValuationDate: 734504 Basis: 0 EndMonthRule: 1 ```

Create the swap instrument using the following data:

```Settle ='1-Jan-2011'; Maturity = '1-Jan-2017'; Period = 1; LegRate = [0.04 10];```

Define the swap amortizing schedule.

`Principal ={{'1-Jan-2013' 100;'1-Jan-2014' 80;'1-Jan-2015' 60;'1-Jan-2016' 40; '1-Jan-2017' 20}};`

Build the HJM tree using the following data:

```MatDates = {'1-Jan-2012'; '1-Jan-2013';'1-Jan-2014';'1-Jan-2015';'1-Jan-2016';'1-Jan-2017'}; HJMTimeSpec = hjmtimespec(RateSpec.ValuationDate, MatDates); Volatility = [.10; .08; .06; .04]; CurveTerm = [ 1; 2; 3; 4]; HJMVolSpec = hjmvolspec('Proportional', Volatility, CurveTerm, 1e6); HJMT = hjmtree(HJMVolSpec,RateSpec,HJMTimeSpec);```

Compute the price of the amortizing swap.

`Price = swapbyhjm(HJMT, LegRate, Settle, Maturity, 'Principal', Principal)`
```Price = 1.4574 ```

Price a forward swap using the `StartDate` input argument to define the future starting date of the swap.

Create the `RateSpec`.

```Rates = 0.0374; ValuationDate = '1-Jan-2012'; StartDates = ValuationDate; EndDates = '1-Jan-2018'; Compounding = 1; RateSpec = intenvset('ValuationDate', ValuationDate,'StartDates', StartDates,... 'EndDates', EndDates,'Rates', Rates, 'Compounding', Compounding)```
```RateSpec = struct with fields: FinObj: 'RateSpec' Compounding: 1 Disc: 0.8023 Rates: 0.0374 EndTimes: 6 StartTimes: 0 EndDates: 737061 StartDates: 734869 ValuationDate: 734869 Basis: 0 EndMonthRule: 1 ```

Build an HJM tree.

```MatDates = {'1-Jan-2013'; '1-Jan-2014';'1-Jan-2015';'1-Jan-2016';'1-Jan-2017';'1-Jan-2018'}; HJMTimeSpec = hjmtimespec(RateSpec.ValuationDate, MatDates); Volatility = [.10; .08; .06; .04]; CurveTerm = [ 1; 2; 3; 4]; HJMVolSpec = hjmvolspec('Proportional', Volatility, CurveTerm, 1e6); HJMT = hjmtree(HJMVolSpec,RateSpec,HJMTimeSpec);```

Compute the price of a forward swap that starts in a year (Jan 1, 2013) and matures in four years with a forward swap rate of 4.25%.

```Settle ='1-Jan-2012'; Maturity = '1-Jan-2017'; StartDate = '1-Jan-2013'; LegRate = [0.0425 10]; Price = swapbyhjm(HJMT, LegRate, Settle, Maturity, 'StartDate', StartDate)```
```Price = 1.4434 ```

Using the previous data, compute the forward swap rate, the coupon rate for the fixed leg, such that the forward swap price at time = 0 is zero.

```LegRate = [NaN 10]; [Price, ~,~, SwapRate] = swapbyhjm(HJMT, LegRate, Settle, Maturity, 'StartDate', StartDate)```
```Price = 0 ```
```SwapRate = 0.0384 ```

## Input Arguments

collapse all

Interest-rate tree structure, created by `hjmtree`

Data Types: `struct`

Leg rate, specified as a `NINST`-by-`2` matrix, with each row defined as one of the following:

• `[CouponRate Spread]` (fixed-float)

• `[Spread CouponRate]` (float-fixed)

• `[CouponRate CouponRate]` (fixed-fixed)

• `[Spread Spread]` (float-float)

`CouponRate` is the decimal annual rate. `Spread` is the number of basis points over the reference rate. The first column represents the receiving leg, while the second column represents the paying leg.

Data Types: `double`

Settlement date, specified either as a scalar or `NINST`-by-`1` vector of serial date numbers or date character vectors.

The `Settle` date for every swap is set to the `ValuationDate` of the HJM tree. The swap argument `Settle` is ignored.

Data Types: `char` | `double`

Maturity date, specified as a `NINST`-by-`1` vector of serial date numbers or date character vectors representing the maturity date for each swap.

Data Types: `char` | `double`

### Name-Value Pair Arguments

Specify optional comma-separated pairs of `Name,Value` arguments. `Name` is the argument name and `Value` is the corresponding value. `Name` must appear inside quotes. You can specify several name and value pair arguments in any order as `Name1,Value1,...,NameN,ValueN`.

Example: `[Price,PriceTree,CFTree,SwapRate] = swapbyhjm(HJMTree,LegRate,Settle,Maturity,LegReset,Basis,Principal,LegType)`

Reset frequency per year for each swap, specified as the comma-separated pair consisting of `'LegReset'` and a `NINST`-by-`2` vector.

Data Types: `double`

Day-count basis representing the basis for each leg, specified as the comma-separated pair consisting of `'Basis'` and a `NINST`-by-`1` array (or `NINST`-by-`2` if `Basis` is different for each leg).

• 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

Data Types: `double`

Notional principal amounts or principal value schedules, specified as the comma-separated pair consisting of `'Principal'` and a vector or cell array.

`Principal` accepts a `NINST`-by-`1` vector or `NINST`-by-`1` cell array (or `NINST`-by-`2` if `Principal` is different for each leg) of the notional principal amounts or principal value schedules. For schedules, each element of the cell array is a `NumDates`-by-`2` array where the first column is dates and the second column is its associated notional principal value. The date indicates the last day that the principal value is valid.

Data Types: `cell` | `double`

Leg type, specified as the comma-separated pair consisting of `'LegType'` and a `NINST`-by-`2` matrix with values ```[1 1]``` (fixed-fixed), `[1 0]` (fixed-float), ```[0 1]``` (float-fixed), or `[0 0]` (float-float). Each row represents an instrument. Each column indicates if the corresponding leg is fixed (`1`) or floating (`0`). This matrix defines the interpretation of the values entered in `LegRate`. `LegType` allows `[1 1]` (fixed-fixed), `[1 0]` (fixed-float), `[0 1]` (float-fixed), or `[0 0]` (float-float) swaps

Data Types: `double`

Derivatives pricing options structure, specified as the comma-separated pair consisting of `'Options'` and a structure obtained from using `derivset`.

Data Types: `struct`

End-of-month rule flag for generating dates when `Maturity` is an end-of-month date for a month having 30 or fewer days, specified as the comma-separated pair consisting of `'EndMonthRule'` and a nonnegative integer [`0`, `1`] using a `NINST`-by-`1` (or `NINST`-by-`2` if `EndMonthRule` is different for each leg).

• `0` = Ignore rule, meaning that a payment date is always the same numerical day of the month.

• `1` = Set rule on, meaning that a payment date is always the last actual day of the month.

Data Types: `logical`

Flag to adjust cash flows based on actual period day count, specified as the comma-separated pair consisting of `'AdjustCashFlowsBasis'` and a `NINST`-by-`1` (or `NINST`-by-`2` if `AdjustCashFlowsBasis` is different for each leg) of logicals with values of `0` (false) or `1` (true).

Data Types: `logical`

Business day conventions, specified as the comma-separated pair consisting of `'BusinessDayConvention'` and a character vector or a `N`-by-`1` (or `NINST`-by-`2` if `BusinessDayConvention` is different for each leg) cell array of character vectors of business day conventions. The selection for business day convention determines how non-business days are treated. Non-business days are defined as weekends plus any other date that businesses are not open (e.g. statutory holidays). Values are:

• `actual` — Non-business days are effectively ignored. Cash flows that fall on non-business days are assumed to be distributed on the actual date.

• `follow` — Cash flows that fall on a non-business day are assumed to be distributed on the following business day.

• `modifiedfollow` — Cash flows that fall on a non-business day are assumed to be distributed on the following business day. However if the following business day is in a different month, the previous business day is adopted instead.

• `previous` — Cash flows that fall on a non-business day are assumed to be distributed on the previous business day.

• `modifiedprevious` — Cash flows that fall on a non-business day are assumed to be distributed on the previous business day. However if the previous business day is in a different month, the following business day is adopted instead.

Data Types: `char` | `cell`

Holidays used in computing business days, specified as the comma-separated pair consisting of `'Holidays'` and MATLAB date numbers using a `NHolidays`-by-`1` vector.

Data Types: `double`

Date swap actually starts, specified as the comma-separated pair consisting of `'StartDate'` and a `NINST`-by-`1` vector of dates using a serial date number or a character vector.

Use this argument to price forward swaps, that is, swaps that start in a future date

Data Types: `char` | `double`

## Output Arguments

collapse all

Expected swap prices at time 0, returned as a `NINST`-by-`1` vector.

Tree structure of instrument prices, returned as a MATLAB structure of trees containing vectors of swaption instrument prices and a vector of observation times for each node. Within `PriceTree`:

• `PriceTree.tObs` contains the observation times.

• `PriceTree.PBush` contains the clean prices.

Swap cash flows, returned as a tree structure with a vector of the swap cash flows at each node. This structure contains only `NaN`s because with binomial recombining trees, cash flows cannot be computed accurately at each node of a tree.

Rates applicable to the fixed leg, returned as a `NINST`-by-`1` vector of rates applicable to the fixed leg such that the swaps’ values are zero at time 0. This rate is used in calculating the swaps’ prices when the rate specified for the fixed leg in `LegRate` is `NaN`. The `SwapRate` output is padded with `NaN` for those instruments in which `CouponRate` is not set to `NaN`.

collapse all

### Amortizing Swap

In an amortizing swap, the notional principal decreases periodically because it is tied to an underlying financial instrument with a declining (amortizing) principal balance, such as a mortgage.

### Forward Swap

Agreement to enter into an interest-rate swap arrangement on a fixed date in future.