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:

• BjerksundStensland

• IkedaKunitomo

• Black

• BlackScholes

• CDSBlack

• CMSConvexityHull

• ConzeViswanathan

• GoldmanSosinGatto

• HeynenKat

• HullWhite

• Heston

• KemnaVorst

• Kirk

• Levy

• Normal

• RollGeskeWhaley

• Rubinstein

• SABR

• TurnbullWakeman

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

Examples

Use Bjerksund-Stensland Pricer and Black-Scholes Model to Price Spread Instrument

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 Black-Scholes Model to Price the Absolure Return for Cliquet Instruments

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 object
  3x1 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 object
  3x1 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

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

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

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

• BjerksundStensland

• IkedaKunitomo

• Black

• BlackScholes

• CDSBlack

• CMSConvexityHull

• ConzeViswanathan

• GoldmanSosinGatto

• HeynenKat

• HullWhite

• Heston

• KemnaVorst

• Kirk

• Levy

• Normal

• RollGeskeWhaley

• SABR

• Rubinstein

• TurnbullWakeman

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

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

The supported instrument objects using a scalar or vector are:

• Cap

• CMS

• CMSNote

• Floor

• Swaption

• Vanilla

• Lookback

• PartialLookback

• Barrier

• DoubleBarrier

• Asian

• Cliquet

• Spread

• CDSOption

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',}

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

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, or SABR pricing method.

Version History

Introduced in R2020a