swapbyzero

Price swap instrument from set of zero curves and price cross-currency swaps

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,Name,Value)

Description

[Price,SwapRate,AI,RecCF,RecCFDates,PayCF,PayCFDates] = swapbyzero(RateSpec,LegRate,Settle,Maturity) prices a swap instrument. You can use swapbyzero to compute prices of vanilla swaps, amortizing swaps, and forward swaps. All inputs are either scalars or NINST-by-1 vectors unless otherwise specified. Any date can be a date character vector. An optional argument can be passed as an empty matrix [].

Note

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

[Price,SwapRate,AI,RecCF,RecCFDates,PayCF,PayCFDates] = swapbyzero(RateSpec,LegRate,Settle,Maturity,Name,Value) prices a swap instrument with additional options specified by one or more Name,Value pair arguments. You can use swapbyzero to compute prices of vanilla swaps, amortizing swaps, forward swaps, and cross-currency swaps. For more information on the name-value pairs for vanilla swaps, amortizing swaps, and forward swaps, see Vanilla Swaps, Amortizing Swaps, Forward Swaps.

Specifically, you can use name-value pairs for FXRate, ExchangeInitialPrincipal, and ExchangeMaturityPrincipal to compute the price for cross-currency swaps. For more information on the name-value pairs for cross-currency swaps, see Cross-Currency Swaps.

Examples

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 = datetime(2000,1,1);
Maturity = datetime(2003,1,1);
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 = 
0

SwapRate = 
0.0466

In swapbyzero , if Settle is not on a reset date (and 'StartDate' is not specified), the effective date is assumed to be the previous reset date before Settle in order to compute the accrued interest and dirty price. In this example, the effective date is ( '15-Sep-2009' ), which is the previous reset date before the ( '08-Jun-2010' ) Settle date.

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 = datetime(2008,6,1);
RateSpec = intenvset('Rates', [.005 .0075 .01 .014 .02 .025 .03]',...
'StartDates',Settle, 'EndDates',[datetime(2010,12,8) , datetime(2011,6,8) , datetime(2012,6,8) , datetime(2013,6,8) , datetime(2015,6,8) , datetime(2017,6,8) ,datetime(2020,6,8)]');
Maturity = datetime(2020,9,15);
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 = 
-7.7485

SwapRate = 
NaN

AI = 
1.4098

RecCF = 1×14

   -1.7623    2.4863    2.5000    2.5000    2.5000    2.5137    2.4932    2.4932    2.5000    2.5000    2.5000    2.5137    2.4932  102.4932

RecCFDates = 1×14

      733560      733666      734031      734396      734761      735129      735493      735857      736222      736588      736953      737320      737684      738049

PayCF = 1×14

   -0.3525    0.4973    1.0006    1.0006    2.0510    2.5944    3.6040    3.8939    4.4152    4.6923    4.9895    4.8400    5.1407  104.9126

PayCFDates = 1×14

      733560      733666      734031      734396      734761      735129      735493      735857      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 = datetime(2012,5,1); 
EndDates = [datetime(2013,5,1) ; datetime(2014,5,1) ; datetime(2015,5,1) ; datetime(2016,5,1)];
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 = struct with fields:
           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 = 4×2

    0.0356    0.0366
    0.0412    0.0422
    0.0449    0.0459
    0.0477    0.0497

Define the swap instruments.

Settle = datetime(2012,5,1);
Maturity = datetime(2015,5,1);
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×2

    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 = datetime(2012,5,1); 
EndDates = [datetime(2013,5,1) ; datetime(2014,5,1) ; datetime(2015,5,1) ; datetime(2016,5,1)];
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=1×2 struct array with fields:
    FinObj
    Compounding
    Disc
    Rates
    EndTimes
    StartTimes
    EndDates
    StartDates
    ValuationDate
    Basis
    EndMonthRule

Define the swap instruments.

Settle = datetime(2012,5,1);
Maturity = datetime(2015,5,1);
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×1

    3.9693
    1.9846
    3.9693

Compute a Forward Par Swap Rate

To compute a forward par swap rate, set the StartDate parameter to a future date and set the fixed coupon rate in the LegRate input to NaN.

Define the zero curve data and build a zero curve using IRDataCurve.

ZeroRates = [2.09 2.47 2.71 3.12 3.43 3.85 4.57]'/100;
Settle = datetime(2012,1,1);
EndDates = datemnth(Settle,12*[1 2 3 5 7 10 20]');
Compounding = 1;

ZeroCurve = IRDataCurve('Zero',Settle,EndDates,ZeroRates,'Compounding',Compounding)

ZeroCurve = 
			 Type: Zero
		   Settle: 734869 (01-Jan-2012)
	  Compounding: 1
			Basis: 0 (actual/actual)
	 InterpMethod: linear
			Dates: [7x1 double]
			 Data: [7x1 double]

Create a RateSpec structure using the toRateSpec method.

RateSpec = ZeroCurve.toRateSpec(EndDates)

RateSpec = struct with fields:
           FinObj: 'RateSpec'
      Compounding: 1
             Disc: [7x1 double]
            Rates: [7x1 double]
         EndTimes: [7x1 double]
       StartTimes: [7x1 double]
         EndDates: [7x1 double]
       StartDates: 734869
    ValuationDate: 734869
            Basis: 0
     EndMonthRule: 1

Compute the forward swap rate (the coupon rate for the fixed leg), such that the forward swap price at time = 0 is zero. The forward swap starts in a month (1-Feb-2012) and matures in 10 years (1-Feb-2022).

StartDate = datetime(2012,2,1);
Maturity = datetime(2022,2,1);
LegRate = [NaN 0];

[Price, SwapRate] = swapbyzero(RateSpec, LegRate, Settle, Maturity,...
'StartDate', StartDate)

Price = 
0

SwapRate = 
0.0378

Compute a Forward Swap Rate Using the Optional Input BusinessDayConvention

The swapbyzero function generates the cash flow dates based on the Settle and Maturity dates, while using the Maturity date as the "anchor" date from which to count backwards in regular intervals. By default, swapbyzero does not distinguish non-business days from business days. To make swapbyzero move non-business days to the following business days, you can you can set the optional name-value input argument BusinessDayConvention with a value of follow.

Define the zero curve data and build a zero curve using IRDataCurve.

ZeroRates = [2.09 2.47 2.71 3.12 3.43 3.85 4.57]'/100;
Settle = datetime(2012,1,5);
EndDates = datemnth(Settle,12*[1 2 3 5 7 10 20]');
Compounding = 1;
ZeroCurve = IRDataCurve('Zero',Settle,EndDates,ZeroRates,'Compounding',Compounding);
RateSpec = ZeroCurve.toRateSpec(EndDates);
StartDate = datetime(2012,2,5);
Maturity = datetime(2022,2,5);
LegRate = [NaN 0];

To demonstrate the optional input BusinessDayConvention, swapbyzero is first used without and then with the optional name-value input argument BusinessDayConvention. Notice that when using BusinessDayConvention, all days are business days.

[Price1,SwapRate1,~,~,RecCFDates1,~,PayCFDates1] = swapbyzero(RateSpec,LegRate,Settle,Maturity,...
    'StartDate',StartDate);
datestr(RecCFDates1)

ans = 11x11 char array
    '05-Jan-2012'
    '05-Feb-2013'
    '05-Feb-2014'
    '05-Feb-2015'
    '05-Feb-2016'
    '05-Feb-2017'
    '05-Feb-2018'
    '05-Feb-2019'
    '05-Feb-2020'
    '05-Feb-2021'
    '05-Feb-2022'

isbusday(RecCFDates1)

ans = 11x1 logical array

   1
   1
   1
   1
   1
   0
   1
   1
   1
   1
      ⋮

[Price2,SwapRate2,~,~,RecCFDates2,~,PayCFDates2] = swapbyzero(RateSpec,LegRate,Settle,Maturity,...
    'StartDate',StartDate,'BusinessDayConvention','follow');
datestr(RecCFDates2)

ans = 12x11 char array
    '05-Jan-2012'
    '06-Feb-2012'
    '05-Feb-2013'
    '05-Feb-2014'
    '05-Feb-2015'
    '05-Feb-2016'
    '06-Feb-2017'
    '05-Feb-2018'
    '05-Feb-2019'
    '05-Feb-2020'
    '05-Feb-2021'
    '07-Feb-2022'

isbusday(RecCFDates2)

ans = 12x1 logical array

   1
   1
   1
   1
   1
   1
   1
   1
   1
   1
      ⋮

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

Create the swap instrument using the following data:

Settle = datetime(2011,1,1);
Maturity = datetime(2017,1,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}};

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 = 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.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 = datetime(2012,1,1);
StartDate = datetime(2013,1,1);
Maturity = datetime(2016,1,1);
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 = datetime(2000,1,1);
Maturity = datetime(2003,12,1);
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 = datetime(2013,5,15);
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')
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 = datetime(2018,5,15); % 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

Price a Fixed-Fixed Currency Swap

Price an existing cross currency swap that receives a fixed rate of JPY and pays a fixed rate of USD at an annual frequency.

Settle = datetime(2015,8,15);
Maturity = datetime(2018,8,15);
Reset = 1;
LegType = [1 1]; % Fixed-Fixed

r_USD = .09;
r_JPY = .04;
 
FixedRate_USD = .08;
FixedRate_JPY = .05;

Principal_USD = 10000000;
Principal_JPY = 1200000000;
 
S = 1/110;

RateSpec_USD = intenvset('StartDate',Settle,'EndDate', Maturity,'Rates',r_USD,'Compounding',-1);
RateSpec_JPY = intenvset('StartDate',Settle,'EndDate', Maturity,'Rates', r_JPY,'Compounding',-1);

Price = swapbyzero([RateSpec_JPY RateSpec_USD], [FixedRate_JPY FixedRate_USD],...
Settle, Maturity,'Principal',[Principal_JPY Principal_USD],'FXRate',[S 1], 'LegType',LegType)

Price = 
1.5430e+06

Price a Float-Float Currency Swap

Price a new swap where you pay a EUR float and receive a USD float.

Settle = datetime(2015,12,22);
Maturity = datetime(2018,8,15);
LegRate = [0 -50/10000];
LegType = [0 0]; % Float Float
LegReset = [4 4];
FXRate = 1.1;
Notional = [10000000 8000000];

USD_Dates = datemnth(Settle,[1 3 6 12*[1 2 3 5 7 10 20 30]]');
USD_Zero = [0.03 0.06 0.08 0.13 0.36 0.76 1.63 2.29 2.88 3.64 3.89]'/100;
Curve_USD = intenvset('StartDate',Settle,'EndDates',USD_Dates,'Rates',USD_Zero);

EUR_Dates = datemnth(Settle,[3 6 12*[1 2 3 5 7 10 20 30]]');
EUR_Zero = [0.017 0.033 0.088 .27 .512 1.056 1.573 2.183 2.898 2.797]'/100;
Curve_EUR = intenvset('StartDate',Settle,'EndDates',EUR_Dates,'Rates',EUR_Zero);

Price = swapbyzero([Curve_USD Curve_EUR], ...
    LegRate, Settle, Maturity,'LegType',LegType,'LegReset',LegReset,'Principal',Notional,...
    'FXRate',[1 FXRate],'ExchangeInitialPrincipal',false)

Price = 
1.2002e+06

Input Arguments

RateSpec — Interest-rate structure

structure

Interest-rate structure, specified using intenvset to create a RateSpec.

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

Data Types: struct

LegRate — Leg rate

matrix

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

Settle — Settlement date

datetime array | string array | date character vector

Settlement date, specified either as a scalar or NINST-by-1 vector using a datetime array, string array, or date character vectors with the same value which represents the settlement date for each swap. Settle must be earlier than Maturity.

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

Maturity — Maturity date

datetime array | string array | date character vector

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, swapbyzero 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,SwapRate,AI,RecCF,RecCFDates,PayCF,PayCFDates] = swapbyzero(RateSpec,LegRate,Settle,
Maturity,'LegType',LegType,'LatestFloatingRate',LatestFloatingRate,'AdjustCashFlowsBasis',true,
'BusinessDayConvention','modifiedfollow')

Vanilla Swaps, Amortizing Swaps, Forward Swaps

LegReset — Reset frequency per year for each swap

[1 1] (default) | vector

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

Basis — Day-count basis of instrument

0 (actual/actual) (default) | integer from 0 to 13

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

Principal — Notional principal amounts or principal value schedules

100 (default) | vector or cell array

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

LegType — Leg type

[1 0] for each instrument (default) | matrix with values [1 1] (fixed-fixed), [1 0] (fixed-float), [0 1] (float-fixed), or [0 0] (float-float)

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

EndMonthRule — End-of-month rule flag for generating dates when Maturity is end-of-month date for month having 30 or fewer days

1 (in effect) (default) | nonnegative integer [0,1]

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

AdjustCashFlowsBasis — Flag to adjust cash flows based on actual period day count

false (default) | value of 0 (false) or 1 (true)

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

BusinessDayConvention — Business day conventions

actual (default) | character vector | cell array of character vectors

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 — Holidays used in computing business days

if not specified, the default is to use holidays.m (default) | MATLAB^® dates

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

StartDate — Dates when swaps actually start

If not specified, date is Settle (default) | character vector | cell array of character vectors

Dates when the swaps actually start, specified as the comma-separated pair consisting of 'StartDate' and a NINST-by-1 vector of character vectors or cell array of character vectors.

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

LatestFloatingRate — Rate for the next floating payment

If not specified, then RateSpec must contain this information (default) | scalar numeric

Rate for the next floating payment, set at the last reset date, specified as the comma-separated pair consisting of 'LatestFloatingRate' and a scalar numeric value.

LatestFloatingRate accepts a Rate for the next floating payment, set at the last reset date. LatestFloatingRate is a NINST-by-1 (or NINST-by-2 if LatestFloatingRate is different for each leg).

Data Types: double

ProjectionCurve — Rate curve used in generating cash flows for the floating leg of the swap

if ProjectionCurve is not specified, then RateSpec is used both for discounting and generating cash flows for the floating leg (default) | RateSpec or vector

Rate curve used in generating cash flows for the floating leg of the swap, specified as the comma-separated pair consisting of 'ProjectionCurve' and a RateSpec.

If specifying a fixed-float or a float-fixed swap, the ProjectionCurve rate curve is used in generating cash flows for the floating leg of the swap. This structure must be created using intenvset.

If specifying a fixed-fixed or a float-float swap, then ProjectionCurve is NINST-by-2 vector because each floating leg could have a different projection curve.

Data Types: struct

Cross-Currency Swaps

FXRate — Foreign exchange (FX) rate applied to cash flows

if not specified, both legs of swapbyzero are in same currency (default) | array

Foreign exchange (FX) rate applied to cash flows, specified as the comma-separated pair consisting of 'FXRate' and a NINST-by-2 array of doubles. Since the foreign exchange rate could be applied to either the payer or receiver leg, there are 2 columns in the input array and you must specify which leg has the foreign currency.

Data Types: double

ExchangeInitialPrincipal — Flag to indicate if initial Principal is exchanged

0 (false) (default) | array

Flag to indicate if initial Principal is exchanged, specified as the comma-separated pair consisting of 'ExchangeInitialPrincipal' and a NINST-by-1 array of logicals.

Data Types: logical

ExchangeMaturityPrincipal — Flag to indicate if Principal exchanged at Maturity

1 (true) (default) | array

Flag to indicate if Principal is exchanged at Maturity, specified as the comma-separated pair consisting of 'ExchangeMaturityPrincipal' and a NINST-by-1 array of logicals. While in practice most single currency swaps do not exchange principal at maturity, the default is true to maintain backward compatibility.

Data Types: logical

Output Arguments

Price — Swap prices

matrix

Swap prices, returned as the number of instruments (NINST) by number of curves (NUMCURVES) matrix. Each column arises from one of the zero curves. Price output is the dirty price. To compute the clean price, subtract the accrued interest (AI) from the dirty price.

SwapRate — Rates applicable to fixed leg

matrix

Rates applicable to the fixed leg, returned as a NINST-by-NUMCURVES matrix 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.

AI — Accrued interest

matrix

Accrued interest, returned as a NINST-by-NUMCURVES matrix.

RecCF — Cash flows for receiving leg

matrix

Cash flows for the receiving leg, returned as a NINST-by-NUMCURVES matrix.

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 — Payment dates for receiving leg

matrix

Payment dates for the receiving leg, returned as an NINST-by-NUMCURVES matrix.

PayCF — Cash flows for paying leg

matrix

Cash flows for the paying leg, returned as an NINST-by-NUMCURVES matrix.

PayCFDates — Payment dates for paying leg

matrix

Payment dates for the paying leg, returned as an NINST-by-NUMCURVES matrix.

More About

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.

Cross-currency Swap

Swaps where the payment legs of the swap are denominated in different currencies.

One difference between cross-currency swaps and standard swaps is that an exchange of principal may occur at the beginning and/or end of the swap. The exchange of initial principal will only come into play in pricing a cross-currency swap at inception (in other words, pricing an existing cross-currency swap will occur after this cash flow has happened). Furthermore, these exchanges of principal typically do not affect the value of the swap (since the principal values of the two legs are chosen based on the currency exchange rate) but affect the cash flows for each leg.

References

[1] Hull, J. Options, Futures and Other Derivatives Fourth Edition. Prentice Hall, 2000.

Version History

Introduced before R2006a

R2022b: Serial date numbers not recommended

Although swapbyzero supports serial date numbers, datetime values are recommended instead. The datetime data type provides flexible date and time formats, storage out to nanosecond precision, and properties to account for time zones and daylight saving time.

To convert serial date numbers or text to datetime values, use the datetime function. For example:

t = datetime(738427.656845093,"ConvertFrom","datenum");
y = year(t)

y =

        2021

There are no plans to remove support for serial date number inputs.