Main Content

Swap

Swap instrument object

Description

Create and price a Swap instrument object using this workflow:

  1. Use fininstrument to create a Swap instrument object.

  2. Use ratecurve to specify a curve model for the Swap instrument or use finmodel to specify a HullWhite or BlackKarasinski model.

  3. Use finpricer to specify a Discount pricing method when using a ratecurve object or an IRTree pricing method when using a HullWhite or BlackKarasinski model for the Swap instrument.

For more information on this workflow, see Get Started with Workflows Using Object-Based Framework for Pricing Financial Instruments.

For more information on the available models and pricing methods for a Swap instrument, see Choose Instruments, Models, and Pricers.

Creation

Description

example

SwapInstrument = fininstrument(InstrumentType,'Maturity',maturity_date,'LegRate',leg_rate) creates a Swap object by specifying InstrumentType and sets the properties for the required name-value pair arguments Maturity and LegRate.

The Swap instrument supports vanilla swaps, amortizing swaps and forward swaps. You can use the Swap instrument for a single currency swap but not a cross-currency swap. For more information on a Swap instrument, see More About.

example

SwapInstrument = fininstrument(___,Name,Value) sets optional properties using additional name-value pairs in addition to the required arguments in the previous syntax. For example, SwapInstrument = fininstrument("Swap",'Maturity',datetime(2019,1,30),'LegRate',[0.06 0.12],'LegType',["fixed","fixed"],'Basis',1,'Notional',100,'StartDate',datetime(2016,1,30),'DaycountAdjustedCashFlow',true,'BusinessDayConvention',"follow",'ProjectionCurve',ratecurve,'Name',"swap_instrument") creates a Swap option with a maturity of January 30, 2019. You can specify multiple name-value pair arguments.

Input Arguments

expand all

Instrument type, specified as a string with the value of "Swap" or a character vector with the value of 'Swap'.

Data Types: char | string

Swap Name-Value Pair Arguments

Specify required and 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: SwapInstrument = fininstrument("Swap",'Maturity',datetime(2019,1,30),'LegRate',[0.06 0.12],'LegType',["fixed","fixed"],'Basis',1,'Notional',100,'StartDate',datetime(2016,1,30),'DaycountAdjustedCashFlow',true,'BusinessDayConvention',"follow",'ProjectionCurve',ratecurve,'Name',"swap_instrument")
Required Swap Name-Value Pair Arguments

expand all

Swap maturity date, specified as the comma-separated pair consisting of 'Maturity' and a scalar datetime, serial date number, date character vector, or date string.

If you use a date character vector or date string, the format must be recognizable by datetime because the Maturity property is stored as a datetime.

Data Types: char | double | string | datetime

Leg rate in decimal values, specified as the comma-separated pair consisting of 'LegRate' and a NINST-by-2 matrix. Each row can be 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 in decimals over the reference rate. The first column represents the receiving leg, while the second column represents the paying leg.

Data Types: double

Optional Swap Name-Value Pair Arguments

expand all

Leg type, specified as the comma-separated pair consisting of 'LegType' and a cell array of character vectors or a string array with the supported values. The LegType defines the interpretation of the values entered in LegRate.

Note

When you specify a Swap instrument as the underlying asset for a Swaption instrument while using a Normal, SABR, Black, or HullWhite pricer, the Swap LegType must be ["fixed","float"] or ["float","fixed"]. You must also set the ExerciseStyle name-value pair argument of the associated Swaption instrument to 'European'.

Data Types: cell | string

Rate curve for projecting floating cash flows, specified as the comma-separated pair consisting of 'ProjectionCurve' and a ratecurve object. You must create this object using ratecurve. Use this optional input if the forward curve is different from the discount curve.

Data Types: object

Frequency of payments per year, specified as the comma-separated pair consisting of 'Reset' and scalar or NINST-by-2 if Reset is different for each leg) with one of the following values: 0, 1, 2, 3, 4, 6, or 12.

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 amount or principal value schedule, specified as the comma-separated pair consisting of 'Notional' and a scalar numeric or timetable. Use a scalar for a vanilla Swap instrument and a timetable for an amortizing Swap instrument.

Notional accepts a scalar for a principal amount (or a NINST-by-2 matrix if Notional is different for each leg) or a timetable for principal value schedules. For schedules, the first column of the timetable is dates and the second column is the associated notional principal value. The date indicates the last day that the principal value is valid.

Data Types: timetable | double

Latest floating rate for float legs, specified as the comma-separated pair consisting of 'LatestFloatingRate' and a scalar numeric value.

LatestFloatingRate is a NINST-by-1 matrix (or NINST-by-2 matrix if LatestFloatingRate is different for each leg).

Data Types: double

Lag in rate setting, specified as the comma-separated pair consisting of 'ResetOffset' and a NINST-by-2 vector.

Data Types: double

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

Data Types: logical

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

  • "actual" — Nonbusiness 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 nonbusiness day are assumed to be distributed on the following business day.

  • "modifiedfollow" — Cash flows that fall on a nonbusiness 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 nonbusiness day are assumed to be distributed on the previous business day.

  • "modifiedprevious" — Cash flows that fall on a nonbusiness 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 | string

Holidays used in computing business days, specified as the comma-separated pair consisting of 'Holidays' and dates using datetimes, serial date numbers, cell array of date character vectors, or date string array. For example:

H = holidays(datetime('today'),datetime(2025,12,15));
Swap = fininstrument("Swap",'Maturity',datetime(2025,12,15),'LegRate',[0.06 20],'Holidays',H)

Data Types: double | cell | datetime | string

End-of-month rule flag for generating dates when Maturity is an end-of-month date for a month with 30 or fewer days, specified as the comma-separated pair consisting of 'EndMonthRule' and a logical value of true or false using a NINST-by-1 (or NINST-by-2 if EndMonthRule is different for each leg).

  • If you set EndMonthRule to false, the software ignores the rule, meaning that a payment date is always the same numerical day of the month.

  • If you set EndMonthRule to true, the software sets the rule on, meaning that a payment date is always the last actual day of the month.

Data Types: logical

Date swap starts, specified as the comma-separated pair consisting of 'StartDate' and a scalar datetime, serial date number, date character vector, or date string.

Use StartDate to price a forward swap, that is, a swap that starts at a future date.

If you use a date character vector or date string, the format must be recognizable by datetime because the StartDate property is stored as a datetime.

Data Types: char | double | string | datetime

User-defined name for the instrument, specified as the comma-separated pair consisting of 'Name' and a scalar string or character vector.

Data Types: char | string

Properties

expand all

Maturity date, returned as a datetime.

Data Types: datetime

Leg rate, returned as a NINST-by-2 matrix of decimal values, 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)

Data Types: double

Leg type, returned as a string array with the values ["fixed","fixed"], ["fixed","float"], ["float","fixed"], or ["float","float"].

Data Types: string

Rate curve used in projecting the future cash flows, returned as a ratecurve object.

Data Types: object

Reset frequency per year for each swap, returned as an NINST-by-2 vector.

Data Types: double

Day count basis, returned as an NINST-by-2 vector.

Data Types: double

Lag in rate setting, returned as an NINST-by-2 vector.

Data Types: double

Notional principal amount, returned as a scalar numeric or timetable.

Data Types: cell | double

Rate for the next floating payment, set at the last reset date, returned as a scalar numeric value.

Data Types: double

Flag to adjust cash flows based on actual period day count, returned as an NINST-by-1 matrix (or an NINST-by-2 matrix if AdjustCashFlowsBasis is different for each leg) of logicals with values of true or false.

Data Types: logical

Business day conventions, returned as a string or a NINST-by-2 string array if BusinessDayConvention is different for each leg.

Data Types: char | cell | string

Holidays used in computing business days, returned as datetimes.

Data Types: datetime

End-of-month rule flag for generating dates when Maturity is an end-of-month date for a month with 30 or fewer days, returned as a scalar logical.

Data Types: logical

Date swap starts, returned as a datetime.

Data Types: datetime

User-defined name for the instrument, returned as a string.

Data Types: string

Object Functions

cashflowsComputes cash flow for FixedBond, FloatBond, Swap, FRA, or Deposit instrument
parswaprateCompute par swap rate for Swap instrument

Examples

collapse all

This example shows the workflow to price a vanilla Swap instrument when you use a ratecurve and a Discount pricing method.

Create ratecurve Object

Create a ratecurve object using ratecurve for the underlying interest-rate curve for the Swap instrument.

Settle = datetime(2019,9,15);
Type = 'zero';
ZeroTimes = [calmonths(6) calyears([1 2 3 4 5 7 10 20 30])]';
ZeroRates = [0.0052 0.0055 0.0061 0.0073 0.0094 0.0119 0.0168 0.0222 0.0293 0.0307]';
ZeroDates = Settle + ZeroTimes;
 
myRC = ratecurve('zero',Settle,ZeroDates,ZeroRates)
myRC = 
  ratecurve with properties:

                 Type: "zero"
          Compounding: -1
                Basis: 0
                Dates: [10x1 datetime]
                Rates: [10x1 double]
               Settle: 15-Sep-2019
         InterpMethod: "linear"
    ShortExtrapMethod: "next"
     LongExtrapMethod: "previous"

Create Swap Instrument Object

Use fininstrument to create a vanilla Swap instrument object.

Swap = fininstrument("Swap",'Maturity',datetime(2024,9,15),'LegRate',[0.022 0.019 ],'LegType',["float","fixed"],'ProjectionCurve',myRC,'Name',"swap_instrument")
Swap = 
  Swap with properties:

                     LegRate: [0.0220 0.0190]
                     LegType: ["float"    "fixed"]
                       Reset: [2 2]
                       Basis: [0 0]
                    Notional: 100
          LatestFloatingRate: [NaN NaN]
                 ResetOffset: [0 0]
    DaycountAdjustedCashFlow: [0 0]
             ProjectionCurve: [1x2 ratecurve]
       BusinessDayConvention: ["actual"    "actual"]
                    Holidays: NaT
                EndMonthRule: [1 1]
                   StartDate: NaT
                    Maturity: 15-Sep-2024
                        Name: "swap_instrument"

Create Discount Pricer Object

Use finpricer to create a Discount pricer object and use the ratecurve object for the 'DiscountCurve' name-value pair argument.

outPricer = finpricer("Discount", 'DiscountCurve',myRC)
outPricer = 
  Discount with properties:

    DiscountCurve: [1x1 ratecurve]

Price Swap Instrument

Use price to compute the price and sensitivities for the vanilla Swap instrument.

[Price, outPR] = price(outPricer, Swap,["all"])
Price = 7.2279
outPR = 
  priceresult with properties:

       Results: [1x2 table]
    PricerData: []

outPR.Results
ans=1×2 table
    Price       DV01  
    ______    ________

    7.2279    -0.02212

This example shows the workflow to price an amortizing Swap instrument when you use a ratecurve and a Discount pricing method.

Create ratecurve Object

Create a ratecurve object using ratecurve for the underlying interest-rate curve for the Swap instrument.

Settle = datetime(2019,1,1);
Type = 'zero';
ZeroTimes = [calmonths(6) calyears([1 2 3 4 5 7 10 20 30])]';
ZeroRates = [0.0052 0.0055 0.0061 0.0073 0.0094 0.0119 0.0168 0.0222 0.0293 0.0307]';
ZeroDates = Settle + ZeroTimes;
 
myRC = ratecurve('zero',Settle,ZeroDates,ZeroRates)
myRC = 
  ratecurve with properties:

                 Type: "zero"
          Compounding: -1
                Basis: 0
                Dates: [10x1 datetime]
                Rates: [10x1 double]
               Settle: 01-Jan-2019
         InterpMethod: "linear"
    ShortExtrapMethod: "next"
     LongExtrapMethod: "previous"

Create Swap Instrument Object

Use fininstrument to create an amortizing Swap instrument object.

Maturity = datetime(2024,1,1);
ADates = datetime([2020,1,1 ; 2024,1,1]);
APrincipal = [100; 85];
Notional = timetable(ADates,APrincipal);
Swap = fininstrument("Swap",'Maturity',Maturity,'LegRate',[0.035,0.01],'Reset',[1 1],'Notional',Notional,'Name',"swap_instrument")
Swap = 
  Swap with properties:

                     LegRate: [0.0350 0.0100]
                     LegType: ["fixed"    "float"]
                       Reset: [1 1]
                       Basis: [0 0]
                    Notional: [2x1 timetable]
          LatestFloatingRate: [NaN NaN]
                 ResetOffset: [0 0]
    DaycountAdjustedCashFlow: [0 0]
             ProjectionCurve: [0x0 ratecurve]
       BusinessDayConvention: ["actual"    "actual"]
                    Holidays: NaT
                EndMonthRule: [1 1]
                   StartDate: NaT
                    Maturity: 01-Jan-2024
                        Name: "swap_instrument"

Create Discount Pricer Object

Use finpricer to create a Discount pricer object and use the ratecurve object for the 'DiscountCurve' name-value pair argument.

outPricer = finpricer("Discount", 'DiscountCurve',myRC)
outPricer = 
  Discount with properties:

    DiscountCurve: [1x1 ratecurve]

Price Swap Instrument

Use price to compute the price and sensitivities for the amortizing Swap instrument.

[Price, outPR] = price(outPricer, Swap,["all"])
Price = 5.7183
outPR = 
  priceresult with properties:

       Results: [1x2 table]
    PricerData: []

outPR.Results
ans=1×2 table
    Price       DV01  
    ______    ________

    5.7183    0.022979

This example shows the workflow to price a vanilla Swap instrument when you use a HullWhite model and an IRTree pricing method.

Create ratecurve Object

Create a ratecurve object using ratecurve for the underlying interest-rate curve for the Swap instrument.

Settle = datetime(2020,1,15);
Type = 'zero';
ZeroTimes = [calmonths(6) calyears([1 2 3 4 5 7 10 20 30])]';
ZeroRates = [0.0052 0.0055 0.0061 0.0073 0.0094 0.0119 0.0168 0.0222 0.0293 0.0307]';
ZeroDates = Settle + ZeroTimes;
 
myRC = ratecurve('zero',Settle,ZeroDates,ZeroRates)
myRC = 
  ratecurve with properties:

                 Type: "zero"
          Compounding: -1
                Basis: 0
                Dates: [10x1 datetime]
                Rates: [10x1 double]
               Settle: 15-Jan-2020
         InterpMethod: "linear"
    ShortExtrapMethod: "next"
     LongExtrapMethod: "previous"

Create Swap Instrument Object

Use fininstrument to create a vanilla Swap instrument object.

LegType = ["float","fixed"]
LegType = 1x2 string
    "float"    "fixed"

Swap = fininstrument("Swap",'Maturity',datetime(2030,9,15),'LegRate',[0.022 0.019],'LegType',LegType,'ProjectionCurve',myRC,'Name',"swap_instrument");

Create HullWhite Model Object

Use finmodel to create a HullWhite model object.

HullWhiteModel = finmodel("HullWhite",'Alpha',0.032,'Sigma',0.04)
HullWhiteModel = 
  HullWhite with properties:

    Alpha: 0.0320
    Sigma: 0.0400

Compute Swap Instrument Cash Flow Dates

Use cfdates to compute the cash flows.

CFdates = cfdates(Settle, Swap.Maturity, Swap.Reset(1), Swap.Basis(1))
CFdates = 1x22 datetime
Columns 1 through 5

   15-Mar-2020   15-Sep-2020   15-Mar-2021   15-Sep-2021   15-Mar-2022

Columns 6 through 10

   15-Sep-2022   15-Mar-2023   15-Sep-2023   15-Mar-2024   15-Sep-2024

Columns 11 through 15

   15-Mar-2025   15-Sep-2025   15-Mar-2026   15-Sep-2026   15-Mar-2027

Columns 16 through 20

   15-Sep-2027   15-Mar-2028   15-Sep-2028   15-Mar-2029   15-Sep-2029

Columns 21 through 22

   15-Mar-2030   15-Sep-2030

Create IRTree Pricer Object

Use finpricer to create an IRTree pricer object and use the ratecurve object for the 'DiscountCurve' name-value pair argument.

HWTreePricer = finpricer("IRTree",'Model',HullWhiteModel,'DiscountCurve',myRC,'TreeDates',CFdates')
HWTreePricer = 
  HWBKTree with properties:

             Tree: [1x1 struct]
        TreeDates: [22x1 datetime]
            Model: [1x1 finmodel.HullWhite]
    DiscountCurve: [1x1 ratecurve]

Price Swap Instrument

Use price to compute the price and sensitivities for the vanilla Swap instrument.

[Price, outPR] = price(HWTreePricer, Swap,"all")
Price = 24.3727
outPR = 
  priceresult with properties:

       Results: [1x4 table]
    PricerData: [1x1 struct]

outPR.Results
ans=1×4 table
    Price        Vega        Gamma     Delta 
    ______    __________    _______    ______

    24.373    8.5265e-10    -8790.5    820.67

More About

expand all

Introduced in R2020a