price

Compute price for interest-rate, equity, or credit derivative instrument with Analytic pricer

Since R2020a

Syntax

[Price,PriceResult] = price(inpPricer,inpInstrument)

[Price,PriceResult] = price(___,inpSensitivity)

Description

[Price,PriceResult] = price(inpPricer,inpInstrument) computes the instrument price and related pricing information based on the pricing object inpPricer and the instrument object inpInstrument.

The Analytic pricer supports the following pricer objects:

example

[Price,PriceResult] = price(___,inpSensitivity) adds an optional argument to specify sensitivities.

example

Examples

collapse all

Use `BjerksundStensland` Pricer and `BlackScholes` Model to Price `Spread` Instrument

Open Live Script

This example shows the workflow to price a European exercise Spread instrument when you use a BlackScholes model and a BjerksundStensland pricing method.

Create Spread Instrument Object

Use fininstrument to create a Spread instrument object.

SpreadOpt = fininstrument("Spread",'Strike',5,'ExerciseDate',datetime(2021,9,15),'OptionType',"put",'ExerciseStyle',"european",'Name',"spread_option")

SpreadOpt = 
  Spread with properties:

       OptionType: "put"
           Strike: 5
    ExerciseStyle: "european"
     ExerciseDate: 15-Sep-2021
             Name: "spread_option"

Create BlackScholes Model Object

Use finmodel to create a BlackScholes model object.

BlackScholesModel = finmodel("BlackScholes",'Volatility',[0.2,0.1])

BlackScholesModel = 
  BlackScholes with properties:

     Volatility: [0.2000 0.1000]
    Correlation: [2x2 double]

Create ratecurve Object

Create a flat ratecurve object using ratecurve.

Settle = datetime(2018,9,15);
Maturity = datetime(2023,9,15);
Rate = 0.035;
myRC = ratecurve('zero',Settle,Maturity,Rate,'Basis',12)

myRC = 
  ratecurve with properties:

                 Type: "zero"
          Compounding: -1
                Basis: 12
                Dates: 15-Sep-2023
                Rates: 0.0350
               Settle: 15-Sep-2018
         InterpMethod: "linear"
    ShortExtrapMethod: "next"
     LongExtrapMethod: "previous"

Create BjerksundStensland Pricer Object

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

outPricer = finpricer("analytic",'Model',BlackScholesModel,'DiscountCurve',myRC,'SpotPrice',[100,105],'DividendValue',[0.09,0.17],'PricingMethod',"BjerksundStensland")

outPricer = 
  BjerksundStensland with properties:

    DiscountCurve: [1x1 ratecurve]
            Model: [1x1 finmodel.BlackScholes]
        SpotPrice: [100 105]
    DividendValue: [0.0900 0.1700]
     DividendType: "continuous"

Price Spread Instrument

Use price to compute the price and sensitivities for the Spread instrument.

[Price, outPR] = price(outPricer,SpreadOpt,["all"])

Price = 
7.0596

outPR = 
  priceresult with properties:

       Results: [1x7 table]
    PricerData: []

outPR.Results

ans=1×7 table
    Price            Delta                    Gamma                   Lambda                Vega          Theta       Rho  
    ______    ____________________    ______________________    __________________    ________________    ______    _______

    7.0596    -0.23249     0.27057    0.0069887    0.0055319    -3.2932     3.8327    41.938    18.303    1.1011    -5.6943

Use `Rubinstein` Pricer and `BlackScholes` Model to Price the Absolute Return for `Cliquet` Instruments

Open Live Script

This example shows the workflow to price the absolute return for three Cliquet instruments when you use a BlackScholes model and a Rubinstein pricing method.

Create ratecurve Object

Create a flat ratecurve object using ratecurve.

Settle = datetime(2018,9,15);
Maturity = datetime(2023,9,15);
Rate = 0.035;
myRC = ratecurve('zero',Settle,Maturity,Rate,Basis=12)

myRC = 
  ratecurve with properties:

                 Type: "zero"
          Compounding: -1
                Basis: 12
                Dates: 15-Sep-2023
                Rates: 0.0350
               Settle: 15-Sep-2018
         InterpMethod: "linear"
    ShortExtrapMethod: "next"
     LongExtrapMethod: "previous"

Create Cliquet Instrument Object

Use fininstrument to create a Cliquet instrument object for three Cliquet instruments.

ResetDates = Settle + years(0:0.25:1);  
CliquetOpt = fininstrument("Cliquet",ResetDates=ResetDates,InitialStrike=[140;150;160],ExerciseStyle="european",Name="cliquet_option")

CliquetOpt=3×1 Cliquet array with properties:
    OptionType
    ExerciseStyle
    ResetDates
    LocalCap
    LocalFloor
    GlobalCap
    GlobalFloor
    ReturnType
    InitialStrike
    Name

Create BlackScholes Model Object

Use finmodel to create a BlackScholes model object.

BlackScholesModel = finmodel("BlackScholes",Volatility=0.28)

BlackScholesModel = 
  BlackScholes with properties:

     Volatility: 0.2800
    Correlation: 1

Create Rubinstein Pricer Object

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

outPricer = finpricer("analytic",DiscountCurve=myRC,Model=BlackScholesModel,SpotPrice=135,DividendValue=0.025,PricingMethod="Rubinstein")

outPricer = 
  Rubinstein with properties:

    DiscountCurve: [1x1 ratecurve]
            Model: [1x1 finmodel.BlackScholes]
        SpotPrice: 135
    DividendValue: 0.0250
     DividendType: "continuous"

Price Cliquet Instruments

Use price to compute the price and sensitivities for the three Cliquet instruments.

[Price, outPR] = price(outPricer,CliquetOpt,"all")

Price = 3×1

   28.1905
   25.3226
   23.8168

outPR=3×1 priceresult array with properties:
    Results
    PricerData

outPR.Results

ans=1×7 table
    Price      Delta      Gamma      Lambda     Vega      Rho      Theta 
    ______    _______    ________    ______    ______    ______    ______

    28.191    0.59697    0.020662    2.8588    105.38    60.643    -14.62

ans=1×7 table
    Price      Delta      Gamma      Lambda     Vega      Rho       Theta 
    ______    _______    ________    ______    ______    ______    _______

    25.323    0.41949    0.016816    2.2364    100.47    55.367    -11.708

ans=1×7 table
    Price      Delta      Gamma      Lambda     Vega      Rho      Theta 
    ______    _______    ________    ______    ______    ______    ______

    23.817    0.29729    0.011133    1.6851    93.219    51.616    -7.511

Use `CMSConvexityHull` Pricer and `CMSConvexityHull` Model to Price `CMS` and `CMSNote` Instruments

Open Live Script

This example shows the workflow to price a CMS and CMSNote instrument when you use a CMSConvexityHull model and a CMSConvexityHull pricing method.

Create ratecurve Object

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

Settle = datetime(2022,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;
 
ZeroCurve = ratecurve('zero',Settle,ZeroDates,ZeroRates)

ZeroCurve = 
  ratecurve with properties:

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

Create CMS Instrument Object

Use fininstrument to create a CMS instrument object.

CMSInstrument = fininstrument("CMS",Maturity=datetime(2028,9,15),CMSReferenceTenor=10,LegRate=[0 0.01],LegType=["cms" "fixed"],Name="CMS instrument")

CMSInstrument = 
  CMS with properties:

           CMSReferenceReset: 2
           CMSReferenceTenor: 10
                     LegRate: [0 0.0100]
                     LegType: ["cms"    "fixed"]
                       Reset: [2 2]
                       Basis: [0 0]
                    Notional: 100
          LatestFloatingRate: [NaN NaN]
               LatestCMSRate: NaN
                 ResetOffset: [0 0]
    DaycountAdjustedCashFlow: [0 0]
             ProjectionCurve: [0x0 ratecurve]
       BusinessDayConvention: ["actual"    "actual"]
                    Holidays: NaT
                EndMonthRule: [1 1]
                   StartDate: NaT
                    Maturity: 15-Sep-2028
                        Name: "CMS instrument"

Create CMSNote Instrument Object

Use fininstrument to create a CMSNote instrument object.

CMSNoteInstrument = fininstrument("CMSNote",Maturity=datetime(2028,9,15),CMSReferenceTenor=10,Name="CMSNote instrument")

CMSNoteInstrument = 
  CMSNote with properties:

           CMSReferenceReset: 2
           CMSReferenceTenor: 10
                      Spread: 0
         InitialCouponPeriod: 0
           InitialCouponRate: 0
                      Period: 2
                       Basis: 0
                   Principal: 100
          LatestFloatingRate: NaN
               LatestCMSRate: NaN
                 ResetOffset: 0
    DaycountAdjustedCashFlow: 0
             ProjectionCurve: [0x0 ratecurve]
       BusinessDayConvention: "actual"
                    Holidays: NaT
                EndMonthRule: 1
                   StartDate: NaT
                    Maturity: 15-Sep-2028
                        Name: "CMSNote instrument"

Create CMSConvexityHull Model Object

Use finmodel to create a CMSConvexityHull model object.

SwapStartDates = datetime(2022,3,15) + calmonths(0:6:13*6)';

FwdSwapVolatility = [37.5;38.7;39.3;39.5;39.4;39.3;39.2;...
    39;38.8;38.5;38.3;38;37.8;37.7]./100;

CMSConvexityHullModel = finmodel("CMSConvexityHull",CMSConvexityData=timetable(SwapStartDates,FwdSwapVolatility))

CMSConvexityHullModel = 
  CMSConvexityHull with properties:

    CMSConvexityData: [14x3 timetable]

CMSConvexityHullModel.CMSConvexityData

ans=14×3 timetable
    SwapStartDates    FwdSwapVolatility    FwdVolatility    FwdSwapFwdCorrelation
    ______________    _________________    _____________    _____________________

    15-Mar-2022             0.375                0                    0          
    15-Sep-2022             0.387                0                    0          
    15-Mar-2023             0.393                0                    0          
    15-Sep-2023             0.395                0                    0          
    15-Mar-2024             0.394                0                    0          
    15-Sep-2024             0.393                0                    0          
    15-Mar-2025             0.392                0                    0          
    15-Sep-2025              0.39                0                    0          
    15-Mar-2026             0.388                0                    0          
    15-Sep-2026             0.385                0                    0          
    15-Mar-2027             0.383                0                    0          
    15-Sep-2027              0.38                0                    0          
    15-Mar-2028             0.378                0                    0          
    15-Sep-2028             0.377                0                    0

Create CMSConvexityHull Pricer Object

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

CMSConvexityHullPricer = finpricer("analytic",Model=CMSConvexityHullModel,DiscountCurve=ZeroCurve)

CMSConvexityHullPricer = 
  CMSConvexityHull with properties:

            Model: [1x1 finmodel.CMSConvexityHull]
    DiscountCurve: [1x1 ratecurve]

Price CMS and CMSNote Instruments

Use price to compute the price for the CMS and CMSNote instruments.

[CMSPrice, outPR] = price(CMSConvexityHullPricer,CMSInstrument)

CMSPrice = 
11.5623

outPR = 
  priceresult with properties:

       Results: [1x1 table]
    PricerData: [13x7 timetable]

outPR.PricerData % For the CMS instrument

ans=13×7 timetable
       Time        SwapStartDates    ForwardSwapRates    ConvexityAdjustments    TimingAdjustments    CMSRates    Accruals    SwapEndDates
    ___________    ______________    ________________    ____________________    _________________    ________    ________    ____________

    15-Sep-2022     15-Sep-2022          0.021605                      0                 0            0.021605        0       15-Sep-2032 
    15-Mar-2023     15-Sep-2022          0.021605                      0                 0            0.021605      0.5       15-Sep-2032 
    15-Sep-2023     15-Mar-2023           0.02286             0.00019992                 0             0.02306      0.5       15-Mar-2033 
    15-Mar-2024     15-Sep-2023          0.024135             0.00045273                 0            0.024588      0.5       15-Sep-2033 
    15-Sep-2024     15-Mar-2024          0.025431             0.00074919                 0             0.02618      0.5       15-Mar-2034 
    15-Mar-2025     15-Sep-2024          0.026751              0.0010992                 0             0.02785      0.5       15-Sep-2034 
    15-Sep-2025     15-Mar-2025           0.02801              0.0014918                 0            0.029502      0.5       15-Mar-2035 
    15-Mar-2026     15-Sep-2025          0.029262              0.0019316                 0            0.031194      0.5       15-Sep-2035 
    15-Sep-2026     15-Mar-2026          0.030318              0.0023865                 0            0.032705      0.5       15-Mar-2036 
    15-Mar-2027     15-Sep-2026            0.0313              0.0028593                 0             0.03416      0.5       15-Sep-2036 
    15-Sep-2027     15-Mar-2027          0.032102               0.003331                 0            0.035433      0.5       15-Mar-2037 
    15-Mar-2028     15-Sep-2027          0.032798              0.0038007                 0            0.036599      0.5       15-Sep-2037 
    15-Sep-2028     15-Mar-2028          0.033406              0.0042947                 0              0.0377      0.5       15-Mar-2038

[CMSNotePrice, outPR] = price(CMSConvexityHullPricer,CMSNoteInstrument)

CMSNotePrice = 
109.1087

outPR = 
  priceresult with properties:

       Results: [1x1 table]
    PricerData: [13x7 timetable]

outPR.PricerData % For the CMS Note instrument

ans=13×7 timetable
       Time        SwapStartDates    ForwardSwapRates    ConvexityAdjustments    TimingAdjustments    CMSRates    Accruals    SwapEndDates
    ___________    ______________    ________________    ____________________    _________________    ________    ________    ____________

    15-Sep-2022     15-Sep-2022          0.021605                      0                 0            0.021605        0       15-Sep-2032 
    15-Mar-2023     15-Sep-2022          0.021605                      0                 0            0.021605      0.5       15-Sep-2032 
    15-Sep-2023     15-Mar-2023           0.02286             0.00019992                 0             0.02306      0.5       15-Mar-2033 
    15-Mar-2024     15-Sep-2023          0.024135             0.00045273                 0            0.024588      0.5       15-Sep-2033 
    15-Sep-2024     15-Mar-2024          0.025431             0.00074919                 0             0.02618      0.5       15-Mar-2034 
    15-Mar-2025     15-Sep-2024          0.026751              0.0010992                 0             0.02785      0.5       15-Sep-2034 
    15-Sep-2025     15-Mar-2025           0.02801              0.0014918                 0            0.029502      0.5       15-Mar-2035 
    15-Mar-2026     15-Sep-2025          0.029262              0.0019316                 0            0.031194      0.5       15-Sep-2035 
    15-Sep-2026     15-Mar-2026          0.030318              0.0023865                 0            0.032705      0.5       15-Mar-2036 
    15-Mar-2027     15-Sep-2026            0.0313              0.0028593                 0             0.03416      0.5       15-Sep-2036 
    15-Sep-2027     15-Mar-2027          0.032102               0.003331                 0            0.035433      0.5       15-Mar-2037 
    15-Mar-2028     15-Sep-2027          0.032798              0.0038007                 0            0.036599      0.5       15-Sep-2037 
    15-Sep-2028     15-Mar-2028          0.033406              0.0042947                 0              0.0377      0.5       15-Mar-2038

Input Arguments

collapse all

`inpPricer` — Pricer object
`BjerksundStensland` object | `IkedaKunitomo` object | `Black` object | `BlackScholes` object | `CDSBlack` object | `CMSConvexityHull` object | `ConzeViswanathan` object | `GoldmanSosinGatto` object | `HeynenKat` object | `HullWhite` object | `Heston` object | `KemnaVorst` object | `Kirk` object | `Levy` object | `Normal` object | `Rubinstein` object | `RollGeskeWhaley` object | `SABR` object | `TurnbullWakeman` object | `JarrowYildirim` object

Pricer object (previously created using finpricer), specified as a scalar. The supported pricer objects are:

Data Types: object

`inpInstrument` — Instrument object
`Cap` object | `CMS` object | `CMSNote` object | `Floor` object | `Swaption` object | `Vanilla` object | `Lookback` object | `PartialLookback` object | `Barrier` object | `DoubleBarrier` object | `Asian` object | `Spread` object | `Cliquet` object | `VarianceSwap` object | `CDSOption` object | `YearYearInflationCap` object | `YearYearInflationFloor` object | `YearYearInflationSwap` object | `ZeroCouponInflationCap` object | `ZeroCouponInflationFloor` object | `ZeroCouponInflationSwap` object

Instrument object (previously created using fininstrument), specified as a scalar or a vector.

The supported instrument objects using a scalar or vector are:

The supported instrument object using a scalar is:

VarianceSwap

Data Types: object

`inpSensitivity` — List of sensitivities to compute
`[ ]` (default) | string array with values dependent on pricer object | cell array of character vectors with values dependent on pricer object

(Optional) List of sensitivities to compute, specified as a NOUT-by-1 or a 1-by-NOUT cell array of character vectors or string array.

The supported sensitivities depend on the pricing method.

`inpPricer` Object	Supported Sensitivities
`BjerksundStensland`	`{'delta','gamma','vega', 'theta','rho','price','lambda'}`
`IkedaKunitomo`	`{'delta','gamma','vega','theta','rho','price','lambda'}`
`Black`	`'price'`
`CMSConvexityHull`	`'price'`
`BlackScholes`	`{'delta','gamma','vega','theta','rho','price','lambda'}`
`CDSBlack`	`'price'`
`ConzeViswanathan`	`{'delta','gamma','vega','theta','rho','price','lambda}'`
`GoldmanSosinGatto`	`{'delta','gamma','vega','theta','rho','price','lambda}'`
`HeynenKat`	`{'delta','gamma','vega','theta','rho','price','lambda}'`
`HullWhite`	`'price'`
`Heston`	`'price'`
`KemnaVorst`	`{'delta','gamma','vega','theta','rho','price','lambda'}`
`Kirk`	`{'delta','gamma','vega','theta','rho','price','lambda'}`
`Levy`	`{'delta','gamma','vega','theta','rho','price','lambda'}`
`Normal`	`'price'`
`RollGeskeWhaley`	`{'delta','gamma','vega','theta','rho','price','lambda'}`
`Rubinstein`	`{'delta','gamma','vega','theta','rho','price','lambda'}`
`SABR`	`'price'`
`TurnbullWakeman`	`{'delta','gamma','vega','theta','rho','price',}`
`JarrowYildirim`	`'price'`

inpSensitivity = {'All'} or inpSensitivity = ["All"] specifies that all sensitivities for the pricing method are returned. This is the same as specifying inpSensitivity to include each sensitivity.

Example: inpSensitivity = ["delta","gamma","vega","lambda","rho","theta","price"]

Data Types: cell | string

Output Arguments

collapse all

`Price` — Instrument price
numeric

Instrument price, returned as a numeric.

`PriceResult` — Price result
`PriceResult` object

Price result, returned as a PriceResult object. The object has the following fields:

PriceResult.Results — Table of results that includes sensitivities (if you specify inpSensitivity)
PriceResult.PricerData — Structure for pricer data
Note
When pricing a VarianceSwap, PriceResult.FairVariance is returned.

Note

The inpPricer options that do not support sensitivities do not return a PriceResult. For example, there is no PriceResult returned for when using a Black, CDSBlack, HullWhite, Normal, Heston, SABR, or JarrowYildirim pricing method.

More About

collapse all

Delta

A delta sensitivity measures the rate at which the price of an option is expected to change relative to a $1 change in the price of the underlying asset.

Delta is not a static measure; it changes as the price of the underlying asset changes (a concept known as gamma sensitivity), and as time passes. Options that are near the money or have longer until expiration are more sensitive to changes in delta.

Gamma

A gamma sensitivity measures the rate of change of an option's delta in response to a change in the price of the underlying asset.

In other words, while delta tells you how much the price of an option might move, gamma tells you how fast the option's delta itself will change as the price of the underlying asset moves. This is important because this helps you understand the convexity of an option's value in relation to the underlying asset's price.

Vega

A vega sensitivity measures the sensitivity of an option's price to changes in the volatility of the underlying asset.

Vega represents the amount by which the price of an option would be expected to change for a 1% change in the implied volatility of the underlying asset. Vega is expressed as the amount of money per underlying share that the option's value will gain or lose as volatility rises or falls.

Theta

A theta sensitivity measures the rate at which the price of an option decreases as time passes, all else being equal.

Theta is essentially a quantification of time decay, which is a key concept in options pricing. Theta provides an estimate of the dollar amount that an option's price would decrease each day, assuming no movement in the price of the underlying asset and no change in volatility.

Rho

A rho sensitivity measures the rate at which the price of an option is expected to change in response to a change in the risk-free interest rate.

Rho is expressed as the amount of money an option's price would gain or lose for a one percentage point (1%) change in the risk-free interest rate.

Lambda

A lambda sensitivity measures the percentage change in an option's price for a 1% change in the price of the underlying asset.

Lambda is a measure of leverage, indicating how much more sensitive an option is to price movements in the underlying asset compared to owning the asset outright.

Version History

Introduced in R2020a

expand all

R2023b: Support for Pricing Inflation Instruments Using `JarrowYildirim` Pricer

You can use the price function to calculate the price of a YearYearInflationCap, YearYearInflationFloor, ZeroCouponInflationCap, or ZeroCouponInflationFloor using a JarrowYildirim model object and a JarrowYildirim pricing method.

price

Syntax

Description

Examples

Use `BjerksundStensland` Pricer and `BlackScholes` Model to Price `Spread` Instrument

Use `Rubinstein` Pricer and `BlackScholes` Model to Price the Absolute Return for `Cliquet` Instruments

Use `CMSConvexityHull` Pricer and `CMSConvexityHull` Model to Price `CMS` and `CMSNote` Instruments

Input Arguments

`inpSensitivity` — List of sensitivities to compute
`[ ]` (default) | string array with values dependent on pricer object | cell array of character vectors with values dependent on pricer object

Output Arguments

`Price` — Instrument price
numeric

`PriceResult` — Price result
`PriceResult` object

More About

Delta

Gamma

Vega

Theta

Rho

Lambda

Version History

R2023b: Support for Pricing Inflation Instruments Using `JarrowYildirim` Pricer

See Also

Topics

price

Syntax

Description

Examples

Use BjerksundStensland Pricer and BlackScholes Model to Price Spread Instrument

Use Rubinstein Pricer and BlackScholes Model to Price the Absolute Return for Cliquet Instruments

Use CMSConvexityHull Pricer and CMSConvexityHull Model to Price CMS and CMSNote Instruments

Input Arguments

inpSensitivity — List of sensitivities to compute [ ] (default) | string array with values dependent on pricer object | cell array of character vectors with values dependent on pricer object

Output Arguments

Price — Instrument price numeric

PriceResult — Price result PriceResult object

More About

Delta

Gamma

Vega

Theta

Rho

Lambda

Version History

R2023b: Support for Pricing Inflation Instruments Using JarrowYildirim Pricer

See Also

Topics

Use `BjerksundStensland` Pricer and `BlackScholes` Model to Price `Spread` Instrument

Use `Rubinstein` Pricer and `BlackScholes` Model to Price the Absolute Return for `Cliquet` Instruments

Use `CMSConvexityHull` Pricer and `CMSConvexityHull` Model to Price `CMS` and `CMSNote` Instruments

`inpSensitivity` — List of sensitivities to compute
`[ ]` (default) | string array with values dependent on pricer object | cell array of character vectors with values dependent on pricer object

`Price` — Instrument price
numeric

`PriceResult` — Price result
`PriceResult` object

R2023b: Support for Pricing Inflation Instruments Using `JarrowYildirim` Pricer