Main Content

swapbyhw

Price swap instrument from Hull-White interest-rate tree

collapse all in page

Syntax

[Price,PriceTree,CFTree,SwapRate] = swapbyhw(HWTree,LegRate,Settle,Maturity)
[Price,PriceTree,CFTree,SwapRate] = swapbyhw(___,Name,Value)

Description

[Price,PriceTree,CFTree,SwapRate] = swapbyhw(HWTree,LegRate,Settle,Maturity) prices a swap instrument from a Hull-White interest-rate tree. swapbyhw computes prices of vanilla swaps, amortizing swaps and forward swaps.

Note

Alternatively, you can use the Swap object to price swap instruments. For more information, see Get Started with Workflows Using Object-Based Framework for Pricing Financial Instruments.

example

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

example

Examples

collapse all

Open Live Script

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, 2005

  • Swap maturity date: Jan. 01, 2008

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

Settle = datetime(2005,1,1);
Maturity = datetime(2008,1,1);
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 HWTree included in the MAT-file deriv.mat. The HWTree structure contains the time and forward-rate information needed to price the instrument. 

load deriv.mat;

Use swapbyhw to compute the price of the swap. 

[Price, PriceTree, SwapRate] = swapbyhw(HWTree, LegRate, ... 
Settle, Maturity, LegReset, Basis, Principal, LegType)
Warning: Swaps are valued at Tree ValuationDate rather than Settle

Price = 5.9109

PriceTree = struct with fields:
     FinObj: 'HWPriceTree'
      PTree: {[5.9109]  [-1.2692 3.0317 7.5253]  [-5.1049 -2.1588 0.8799 4.0142 7.2471]  [-3.3462 -1.7392 -0.1055 1.5553 3.2438]  [0 0 0 0 0]}
       tObs: [0 1 2 3 4]
    Connect: {[2]  [2 3 4]  [2 2 3 4 4]}
      Probs: {[3×1 double]  [3×3 double]  [3×5 double]}


SwapRate = NaN

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, SwapRate] = swapbyhw(HWTree, LegRate, ... 
Settle, Maturity, LegReset, Basis, Principal, LegType)
Warning: Swaps are valued at Tree ValuationDate rather than Settle

Price = 1.4211e-14

PriceTree = struct with fields:
     FinObj: 'HWPriceTree'
      PTree: {[1.4211e-14]  [-5.5941 -1.4265 2.9289]  [-7.9659 -5.0883 -2.1199 0.9423 4.1011]  [-4.8231 -3.2407 -1.6319 0.0036 1.6662]  [0 0 0 0 0]}
       tObs: [0 1 2 3 4]
    Connect: {[2]  [2 3 4]  [2 2 3 4 4]}
      Probs: {[3×1 double]  [3×3 double]  [3×5 double]}


SwapRate = 0.0438
Open Live Script

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

Create the RateSpec. 

Rates = 0.035;
ValuationDate = datetime(2011,1,1);
StartDates = ValuationDate;
EndDates = datetime(2017,1,1);
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 = datetime(2011,1,1);
Maturity = datetime(2017,1,1);
Period = 1;
LegRate = [0.04 10];

Define the swap amortizing schedule. 

Principal ={{datetime(2013,1,1) 100;datetime(2014,1,1) 80;datetime(2015,1,1) 60;datetime(2016,1,1) 40;datetime(2017,1,1) 20}};

Build the HW tree using the following data: 

VolDates = [datetime(2012,1,1) ; datetime(2013,1,1) ; datetime(2014,1,1) ; datetime(2015,1,1) ; datetime(2016,1,1) ; datetime(2017,1,1)];
VolCurve = 0.1;
AlphaDates = datetime(2017,1,1);
AlphaCurve = 0.1;

HWVolSpec = hwvolspec(RateSpec.ValuationDate, VolDates, VolCurve,... 
AlphaDates, AlphaCurve);
HWTimeSpec = hwtimespec(RateSpec.ValuationDate, VolDates, Compounding);
HWT = hwtree(HWVolSpec, RateSpec, HWTimeSpec);

Compute the price of the amortizing swap. 

Price = swapbyhw(HWT, LegRate, Settle, Maturity, 'Principal', Principal)
Price = 
1.4574
Open Live Script

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 = datetime(2012,1,1);
StartDates = ValuationDate;
EndDates = datetime(2018,1,1);
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 HW tree. 

VolDates = [datetime(2013,1,1) ; datetime(2014,1,1) ; datetime(2015,1,1) ; datetime(2016,1,1) ; datetime(2017,1,1) ; datetime(2018,1,1)];
VolCurve = 0.1;
AlphaDates = datetime(2018,1,1);
AlphaCurve = 0.1;

HWVolSpec = hwvolspec(RateSpec.ValuationDate, VolDates, VolCurve,... 
AlphaDates, AlphaCurve);
HWTimeSpec = hwtimespec(RateSpec.ValuationDate, VolDates, Compounding);
HWT = hwtree(HWVolSpec, RateSpec, HWTimeSpec);

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 = datetime(2012,1,1);
Maturity = datetime(2017,1,1);
StartDate = datetime(2013,1,1);
LegRate = [0.0425 10];

Price = swapbyhw(HWT, 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] = swapbyhw(HWT, LegRate, Settle, Maturity, 'StartDate', StartDate)
Price = 
4.2633e-14

SwapRate = 
0.0384

Input Arguments

collapse all

Interest-rate tree structure, created by hwtree

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 using a datetime array, string array, or date character vectors.

To support existing code, swapbyhw also accepts serial date numbers as inputs, but they are not recommended.

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

Maturity date, specified as a NINST-by-1 vector using a datetime array, string array, or date character vectors representing the maturity date for each swap.

To support existing code, swapbyhw also accepts serial date numbers as inputs, but they are not recommended.

Name-Value Arguments

Specify 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.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: [Price,PriceTree,CFTree,SwapRate] = swapbyhw(HWTree,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

For more information, see Basis.

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 dates using a NHolidays-by-1 vector.

Data Types: datetime

Date swap actually starts, specified as the comma-separated pair consisting of 'StartDate' and a NINST-by-1 vector using a datetime array, string array, or date character vectors.

To support existing code, swapbyhw also accepts serial date numbers as inputs, but they are not recommended.

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

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.PTree contains the clean prices.

  • PriceTree.tObs contains the observation times.

  • PriceTree.Connect contains the connectivity vectors. Each element in the cell array describes how nodes in that level connect to the next. For a given tree level, there are NumNodes elements in the vector, and they contain the index of the node at the next level that the middle branch connects to. Subtracting 1 from that value indicates where the up-branch connects to, and adding 1 indicated where the down branch connects to.

  • PriceTree.Probs contains the probability arrays. Each element of the cell array contains the up, middle, and down transition probabilities for each node of the level.

Swap cash flows, returned as a tree structure with a vector of the swap cash flows at each node. This structure contains only NaNs 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.

More About

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.

Version History

Introduced before R2006a

expand all

See Also

| | | | | |

Topics