Documentation Center

  • Trials
  • Product Updates

swapbyzero

Price swap instrument from set of zero curves

Syntax

[Price, SwapRate AI, RecCF, RecCFDates, PayCF, PayCFDates] =
swapbyzero(RateSpec, LegRate, Settle, Maturity)
[Price, SwapRate AI, RecCF, RecCFDates, PayCF, PayCFDates] =
swapbyzero(RateSpec, LegRate, Settle, Maturity,
LegReset, Basis, Principal, LegType, EndMonthRule)
[Price, SwapRate, AI, RecCF, RecCFDates, PayCF, PayCFDates] =
swapbyzero(RateSpec, LegRate, Settle, Maturity,
Name, Value)

Description

[Price, SwapRate AI, RecCF, RecCFDates, PayCF, PayCFDates] =
swapbyzero(RateSpec, LegRate, Settle, Maturity)
prices a swap instrument from a set of zero coupon bond rates. All inputs are either scalars or NINST-by-1 vectors unless otherwise specified. Any date can be a serial date number or date string. An optional argument can be passed as an empty matrix [].

[Price, SwapRate AI, RecCF, RecCFDates, PayCF, PayCFDates] =
swapbyzero(RateSpec, LegRate, Settle, Maturity,
LegReset, Basis, Principal, LegType, EndMonthRule)
prices a swap instrument from a set of zero coupon bond rates with optional input arguments. All inputs are either scalars or NINST-by-1 vectors unless otherwise specified. Any date can be a serial date number or date string. An optional argument can be passed as an empty matrix [].

[Price, SwapRate, AI, RecCF, RecCFDates, PayCF, PayCFDates] =
swapbyzero(RateSpec, LegRate, Settle, Maturity,
Name, Value)
prices a swap instrument from a set of zero coupon bond rates with additional options specified by one or more Name, Value pair arguments.

Input Arguments

RateSpec

Structure containing the properties of an interest-rate structure. See intenvset for information on creating RateSpec.

RateSpec can also be a 1-by-2 input variable of RateSpecs, with the second RateSpec structure containing the discount curve(s) for the paying leg. If only one RateSpec structure is specified, then this RateSpec is used to discount both legs.

LegRate

Number of instruments (NINST)-by-2 matrix, with each row defined as:

[CouponRate Spread] or [Spread CouponRate]

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.

Settle

Settlement date. Settle must be either a scalar or NINST-by-1 vector of serial date numbers or date strings of the same value which represent the settlement date for each swap. Settle must be earlier than Maturity.

Maturity

Maturity date. NINST-by-1 vector of dates representing the maturity date for each swap.

Ordered Input or Name-Value Pair Arguments

Enter the following optional inputs using an ordered syntax or as name-value pair arguments. You cannot mix ordered syntax with name-value pair arguments.

LegReset

NINST-by-2 matrix representing the reset frequency per year for each swap. NINST-by-1 vector representing the frequency of payments per year.

Default: [1 1]

Basis

Day-count basis of the instrument. A vector of integers.

  • 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 (ISMA)

  • 9 = actual/360 (ISMA)

  • 10 = actual/365 (ISMA)

  • 11 = 30/360E (ISMA)

  • 12 = actual/365 (ISDA)

  • 13 = BUS/252

For more information, see basis.

Default: 0 (actual/actual)

Principal

NINST-by-1 vector or NINST-by-1 cell array of the notional principal amounts or principal value schedules. For the latter case, each element of the cell array is a NumDates-by-2 call 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.

Default: 100

LegType

NINST-by-2 matrix. 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.

Default: [1 0] for each instrument

EndMonthRule

End-of-month rule. NINST-by-1 vector. This rule applies only when Maturity is an end-of-month date for a month having 30 or fewer days.

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

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

Default: 1

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 single quotes (' '). You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

AdjustCashFlowsBasis

Adjust the cash flows based on the actual period day count. NINST-by-1 of logicals.

Default: false

BusinessDayConvention

Require payment dates to be business dates. NINST-by-1 cell array with possible choices of business day convention:

  • actual

  • follow

  • modifiedfollow

  • previous

  • modifiedprevious

Default: actual

Holidays

Holidays used for business day convention. NHOLIDAYS-by-1 of MATLAB® date numbers.

Default: If none specified, holidays.m is used.

LatestFloatingRate

Rate for the next floating payment, set at the last reset date. NINST-by-1 of scalars.

Default: If not specified, then the RateSpec must contain this information.

ProjectionCurve

The rate curve to be used in generating cash flows for the floating leg of the swap. This structure must be created using intenvset.

Default: If ProjectionCurve is not specified, then the RateSpec is used both for discounting and generating cash flows for the floating leg.

StartDate

NINST-by-1 vector of dates when the swap actually starts. Use this argument to price forward swaps, i.e., swaps that start in a future date

Default: Settle date

Output Arguments

Price

Number of instruments (NINST) by number of curves (NUMCURVES) matrix of swap prices. Each column arises from one of the zero curves.

SwapRate

NINST-by-NUMCURVES matrix of rates applicable to the fixed leg such that the swap's 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.

Output cash flows, cash flow dates, and accrued interest.

AI

NINST-by-NUMCURVES matrix of accrued interest.

RecCF

NINST-by-NUMCURVES matrix of cash flows for the receiving leg.

    Note:   If there is more than one curve specified in the RateSpec input, then the first NCURVES row corresponds to the first swap, the second NCURVES row correspond to the second swap, and so on.

RecCFDates

NINST-by-NUMCURVES matrix of payment dates for the receiving leg.

PayCF

NINST-by-NUMCURVES matrix of cash flows for the paying leg.

PayCFDates

NINST-by-NUMCURVES matrix of payment dates for the paying leg.

Examples

expand all

Price an Interest-Rate Swap

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

Load the file deriv.mat, which provides ZeroRateSpec, the interest-rate term structure needed to price the bond.

load deriv.mat;

Use swapbyzero to compute the price of the swap.

Price = swapbyzero(ZeroRateSpec, LegRate, Settle, Maturity,...
LegReset, Basis, Principal, LegType)
Price =

    3.6923

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, SwapRate] = swapbyzero(ZeroRateSpec, LegRate, Settle,...
Maturity, LegReset, Basis, Principal, LegType)
Price =

  -1.4211e-14


SwapRate =

    0.0466

Use swapbyzero with name-value pair arguments for LegRate, LegType, LatestFloatingRate, AdjustCashFlowsBasis, and BusinessDayConvention to calculate output for Price, SwapRate, AI, RecCF, RecCFDates, PayCF, and PayCFDates:

Settle = datenum('08-Jun-2010');
RateSpec = intenvset('Rates', [.005 .0075 .01 .014 .02 .025 .03]',...
'StartDates',Settle, 'EndDates',{'08-Dec-2010','08-Jun-2011',...
'08-Jun-2012','08-Jun-2013','08-Jun-2015','08-Jun-2017','08-Jun-2020'}');
Maturity = datenum('15-Sep-2020');
LegRate = [.025 50];
LegType = [1 0]; % fixed/floating
LatestFloatingRate = .005;

[Price, SwapRate, AI, RecCF, RecCFDates, PayCF,PayCFDates] = ...
swapbyzero(RateSpec, LegRate, Settle, Maturity,'LegType',LegType,...
'LatestFloatingRate',LatestFloatingRate,'AdjustCashFlowsBasis',true,...
'BusinessDayConvention','modifiedfollow')
Price =

   -6.7259


SwapRate =

   NaN


AI =

    1.4575


RecCF =

  Columns 1 through 7

   -1.8219    2.5000    2.5000    2.5137    2.4932    2.4932    2.5000

  Columns 8 through 12

    2.5000    2.5000    2.5137    2.4932  102.4932


RecCFDates =

  Columns 1 through 6

      734297      734396      734761      735129      735493      735857

  Columns 7 through 12

      736222      736588      736953      737320      737684      738049


PayCF =

  Columns 1 through 7

   -0.3644    0.5000    1.4048    1.9961    2.8379    3.2760    3.8218

  Columns 8 through 12

    4.1733    4.5164    4.4920    4.7950  104.6608


PayCFDates =

  Columns 1 through 6

      734297      734396      734761      735129      735493      735857

  Columns 7 through 12

      736222      736588      736953      737320      737684      738049

Price Swaps By Specifying Multiple Term Structures Using RateSpec

Price three swaps using two interest-rate curves. First, define the data for the interest-rate term structure:

StartDates = '01-May-2012';
EndDates = {'01-May-2013'; '01-May-2014';'01-May-2015';'01-May-2016'};
Rates = [[0.0356;0.041185;0.04489;0.047741],[0.0366;0.04218;0.04589;0.04974]];

Create the RateSpec using intenvset.

RateSpec = intenvset('Rates', Rates, 'StartDates',StartDates,...
'EndDates', EndDates, 'Compounding', 1)
RateSpec = 

           FinObj: 'RateSpec'
      Compounding: 1
             Disc: [4x2 double]
            Rates: [4x2 double]
         EndTimes: [4x1 double]
       StartTimes: [4x1 double]
         EndDates: [4x1 double]
       StartDates: 734990
    ValuationDate: 734990
            Basis: 0
     EndMonthRule: 1

Look at the Rates for the two interest-rate curves.

RateSpec.Rates
ans =

    0.0356    0.0366
    0.0412    0.0422
    0.0449    0.0459
    0.0477    0.0497

Define the swap instruments.

Settle = '01-May-2012';
Maturity = '01-May-2015';
LegRate = [0.06 10];
Principal = [100;50;100];  % Three notional amounts

Price three swaps using two curves.

Price = swapbyzero(RateSpec, LegRate, Settle, Maturity, 'Principal', Principal)
Price =

    3.9688    3.6869
    1.9844    1.8434
    3.9688    3.6869

Price Swap By Specifying Multiple Term Structures Using a 1-by-2 RateSpec

Price a swap using two interest-rate curves. First, define data for the two interest-rate term structures:

StartDates = '01-May-2012';
EndDates = {'01-May-2013'; '01-May-2014';'01-May-2015';'01-May-2016'};
Rates1 = [0.0356;0.041185;0.04489;0.047741];
Rates2 = [0.0366;0.04218;0.04589;0.04974];

Create the RateSpec using intenvset.

RateSpecReceiving = intenvset('Rates', Rates1, 'StartDates',StartDates,...
'EndDates', EndDates, 'Compounding', 1);
RateSpecPaying= intenvset('Rates', Rates2, 'StartDates',StartDates,...
'EndDates', EndDates, 'Compounding', 1);
RateSpec=[RateSpecReceiving RateSpecPaying]
RateSpec = 

1x2 struct array with fields:

    FinObj
    Compounding
    Disc
    Rates
    EndTimes
    StartTimes
    EndDates
    StartDates
    ValuationDate
    Basis
    EndMonthRule

Define the swap instruments.

Settle = '01-May-2012';
Maturity = '01-May-2015';
LegRate = [0.06 10];
Principal = [100;50;100];

Price three swaps using the two curves.

Price = swapbyzero(RateSpec, LegRate, Settle, Maturity, 'Principal', Principal)
Price =

    3.9693
    1.9846
    3.9693

Price an Amortizing Swap

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);

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}};

Compute the price of the amortizing swap.

Price = swapbyzero(RateSpec, LegRate, Settle, Maturity, 'Principal' , Principal)
Price =

    1.4574

Price a Forward Swap

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

Create the RateSpec.

Rates = 0.0325;
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 = 

           FinObj: 'RateSpec'
      Compounding: 1
             Disc: 0.8254
            Rates: 0.0325
         EndTimes: 6
       StartTimes: 0
         EndDates: 737061
       StartDates: 734869
    ValuationDate: 734869
            Basis: 0
     EndMonthRule: 1

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

Settle ='1-Jan-2012';
StartDate = '1-Jan-2013';
Maturity = '1-Jan-2016';
LegRate = [0.0427 10];

Price = swapbyzero(RateSpec, LegRate, Settle, Maturity, 'StartDate' , StartDate)
Price =

    2.5083

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] = swapbyzero(RateSpec, LegRate, Settle, Maturity,...
'StartDate' , StartDate)
Price =

     0


SwapRate =

    0.0335

Specify the Rate at the Instrument's Starting Date When it Cannot be Obtained From the RateSpec

If Settle is not on a reset date of a floating-rate note, swapbyzero attempts to obtain the latest floating rate before Settle from RateSpec or the LatestFloatingRate parameter. When the reset date for this rate is out of the range of RateSpec (and LatestFloatingRate is not specified), swapbyzero fails to obtain the rate for that date and generates an error. This example shows how to use the LatestFloatingRate input parameter to avoid the error.

Create the error condition when a swap instrument's StartDate cannot be determined from the RateSpec.

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

load deriv.mat; 

Price = swapbyzero(ZeroRateSpec, LegRate, Settle, Maturity,... 
'LegReset', LegReset, 'Basis', Basis, 'Principal', Principal, ...
'LegType', LegType)
Error using floatbyzero (line 256)
The rate at the instrument starting date cannot be obtained from RateSpec.
 Its reset date (01-Dec-1999) is out of the range of dates contained in RateSpec.
 This rate is required to calculate cash flows at the instrument starting date.
 Consider specifying this rate with the 'LatestFloatingRate' input parameter.

Error in swapbyzero (line 289)
[FloatFullPrice, FloatPrice,FloatCF,FloatCFDates] = floatbyzero(FloatRateSpec, Spreads, Settle,...

Here, the reset date for the rate at Settle was 01-Dec-1999, which was earlier than the valuation date of ZeroRateSpec (01-Jan-2000). This error can be avoided by specifying the rate at the swap instrument's starting date using the LatestFloatingRate input parameter.

Define LatestFloatingRate and calculate the floating-rate price.

Price = swapbyzero(ZeroRateSpec, LegRate, Settle, Maturity,... 
'LegReset', LegReset, 'Basis', Basis, 'Principal', Principal, ...
'LegType', LegType, 'LatestFloatingRate', 0.03)
Price =

    4.7594

Price a Swap Using a Different Curve to Generate the Cash Flows of the Floating Leg

Define the OIS and Libor rates.

Settle = datenum('15-Mar-2013');
CurveDates = daysadd(Settle,360*[1/12 2/12 3/12 6/12 1 2 3 4 5 7 10],1);
OISRates = [.0018 .0019 .0021 .0023 .0031 .006  .011 .017 .021 .026 .03]';
LiborRates = [.0045 .0047 .005 .0055 .0075 .011 .016 .022 .026 .030 .0348]';

Plot the dual curves.

figure,plot(CurveDates,OISRates,'r');hold on;plot(CurveDates,LiborRates,'b')
datetick
legend({'OIS Curve', 'Libor Curve'})

Create an associated RateSpec for the OIS and Libor curves.

OISCurve = intenvset('Rates',OISRates,'StartDate',Settle,'EndDates',CurveDates);
LiborCurve = intenvset('Rates',LiborRates,'StartDate',Settle,'EndDates',CurveDates);

Define the swap.

Maturity = datenum('15-Mar-2018'); % Five year swap
FloatSpread = 0;
FixedRate = .025;
LegRate = [FixedRate FloatSpread];

Compute the price of the swap instrument. The LiborCurve term structure will be used to generate the cash flows of the floating leg. The OISCurve term structure will be used for discounting the cash flows.

Price = swapbyzero(OISCurve, LegRate, Settle,...
Maturity,'ProjectionCurve',LiborCurve)
Price =

   -0.3697

Compare results when the term structure OISCurve is used both for discounting and also generating the cash flows of the floating leg.

PriceSwap = swapbyzero(OISCurve, LegRate, Settle, Maturity)
PriceSwap =

    2.0517

More About

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

See Also

| | | |

Was this topic helpful?