BlackScholes

Create BlackScholes pricer object for Vanilla, Barrier, Touch, DoubleTouch, or Binary instrument using BlackScholes model

Description

Create and price a Vanilla, Barrier, Touch, DoubleTouch, or Binary instrument object with a BlackScholes model and a BlackScholes pricing method using this workflow:

1. Use fininstrument to create a Vanilla, Barrier, DoubleTouch, Binary or , Touch instrument object.

2. Use finmodel to specify a BlackScholes model for the Vanilla, Barrier, Touch, DoubleTouch, or Binary instrument object.

3. Use finpricer to specify a BlackScholes pricer object for the Vanilla, Barrier, Touch, DoubleTouch, or Binary instrument object.

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 instruments, models, and pricing methods for a Vanilla, Lookback, Barrier, Asian, Spread, Touch, DoubleTouch, or Binary instrument, see Choose Instruments, Models, and Pricers.

Creation

Syntax

BlackScholesPricerObj = finpricer(PricerType,'Model',model,'DiscountCurve',ratecurve_obj,'SpotPrice',spotprice_value)

BlackScholesPricerObj = finpricer(___,Name,Value)

Description

BlackScholesPricerObj = finpricer(PricerType,'Model',model,'DiscountCurve',ratecurve_obj,'SpotPrice',spotprice_value) creates a BlackScholes pricer object by specifying PricerType and sets properties using the required name-value pair arguments DiscountCurve, Model, and SpotPrice.

BlackScholesPricerObj = finpricer(___,Name,Value) sets optional properties using additional name-value pair arguments in addition to the required arguments in the previous syntax. For example, BlackScholesPricerObj = finpricer("Analytic",'Model',BSModel,'DiscountCurve',ratecurve_obj,'SpotPrice',1000,'DividendType',"continuous",'DividendValue',100) creates a BlackScholes pricer object. You can specify multiple name-value pair arguments.

Input Arguments

PricerType — Pricer type

string with value "Analytic" | character vector with value 'Analytic'

Pricer type, specified as a string with the value "Analytic" or a character vector with the value 'Analytic'.

Data Types: char | string

Name-Value Arguments

Specify required and 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: BlackScholesPricerObj = finpricer("Analytic",'Model',BSModel,'DiscountCurve',ratecurve_obj,'SpotPrice',1000,'DividendType',"continuous",'DividendValue',100)

Required BlackScholes Name-Value Pair Arguments

Model — Model object

BlackScholes model object

Model, specified as the comma-separated pair consisting of 'Model' and the name of a previously created BlackScholes model object using finmodel.

Data Types: object

DiscountCurve — ratecurve object for discounting cash flows

ratecurve object

ratecurve object for discounting cash flows, specified as the comma-separated pair consisting of 'DiscountCurve' and the name of a previously created ratecurve object.

Note

Specify a flat ratecurve object for DiscountCurve. If you use a nonflat ratecurve object, the software uses the rate in the ratecurve object at Maturity and assumes that the value is constant for the life of the equity option.

Data Types: object

SpotPrice — Current price of underlying asset

nonnegative numeric

Current price of the underlying asset, specified as the comma-separated pair consisting of 'SpotPrice' and a scalar nonnegative numeric.

Data Types: double

Optional BlackScholes Name-Value Pair Arguments

DividendType — Stock dividend type

"continuous" (default) | string with value "continuous" | character vector with value 'continuous'

Stock dividend type, specified as the comma-separated pair consisting of 'DividendType' and a character vector or string.

Note

When you price currencies using a Vanilla instrument, DividendType must be "continuous" and DividendValue is the annualized risk-free interest rate in the foreign country.

Data Types: char | string

DividendValue — Dividend amount or dividend schedule for underlying stock

0 (default) | scalar numeric | timetable

Dividend amount or dividend schedule for the underlying stock, specified as the comma-separated pair consisting of 'DividendValue' and a scalar numeric for a dividend amount or a timetable for a dividend schedule.

Note

When you price currencies using a Vanilla instrument, the DividendType must be "continuous" and DividendValue is the annualized risk-free interest rate in the foreign country.

Data Types: double | timetable

Output Arguments

BlackScholesPricerObj — Black-Scholes pricer

BlackScholes object

Black-Scholes pricer, returned as a BlackScholes object.

Properties

Model — Model

BlackScholes model object

Model, returned as a BlackScholes model object.

Data Types: object

DiscountCurve — ratecurve object for discounting cash flows

ratecurve object

ratecurve object for discounting cash flows, returned as a ratecurve object.

Data Types: object

SpotPrice — Current price of underlying asset

nonnegative numeric

Current price of the underlying asset, returned as a scalar nonnegative numeric.

Data Types: double

DividendType — Stock dividend type

Read-only: "continuous" (default) | string with value "continuous"

This property is read-only.

Stock dividend type, returned as a string.

Data Types: string

DividendValue — Dividend amount or dividend schedule for underlying stock

0 (default) | scalar nonnegative numeric | timetable

Dividend amount or dividend schedule for the underlying stock, returned as a scalar numeric for a dividend amount or a timetable for a dividend schedule.

Data Types: double | timetable

Object Functions

price

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

Examples

Price Vanilla Instrument Using BlackScholes Model and BlackScholes Pricer

This example shows the workflow to price a Vanilla instrument when you use a BlackScholes model and a BlackScholes pricing method.

Create Vanilla Instrument Object

Use fininstrument to create a Vanilla instrument object.

VanillaOpt = fininstrument("Vanilla",'ExerciseDate',datetime(2018,5,1),'Strike',29,'OptionType',"put",'ExerciseStyle',"european",'Name',"vanilla_option")

VanillaOpt = 
  Vanilla with properties:

       OptionType: "put"
    ExerciseStyle: "european"
     ExerciseDate: 01-May-2018
           Strike: 29
             Name: "vanilla_option"

Create BlackScholes Model Object

Use finmodel to create a BlackScholes model object.

BlackScholesModel = finmodel("BlackScholes",'Volatility',0.25)

BlackScholesModel = 
  BlackScholes with properties:

     Volatility: 0.2500
    Correlation: 1

Create ratecurve Object

Create a flat ratecurve object using ratecurve.

Settle = datetime(2018,1,1);
Maturity = datetime(2019,1,1);
Rate = 0.05;
myRC = ratecurve('zero',Settle,Maturity,Rate,'Basis',1)

myRC = 
  ratecurve with properties:

                 Type: "zero"
          Compounding: -1
                Basis: 1
                Dates: 01-Jan-2019
                Rates: 0.0500
               Settle: 01-Jan-2018
         InterpMethod: "linear"
    ShortExtrapMethod: "next"
     LongExtrapMethod: "previous"

Create BlackScholes Pricer Object

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

outPricer = finpricer("analytic",'DiscountCurve',myRC,'Model',BlackScholesModel,'SpotPrice',30,'DividendValue',0.045)

outPricer = 
  BlackScholes with properties:

    DiscountCurve: [1×1 ratecurve]
            Model: [1×1 finmodel.BlackScholes]
        SpotPrice: 30
    DividendValue: 0.0450
     DividendType: "continuous"

Price Vanilla Instrument

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

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

Price = 
1.2046

outPR = 
  priceresult with properties:

       Results: [1×7 table]
    PricerData: []

outPR.Results

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

    1.2046    -0.36943    0.086269    -9.3396    6.4702    -4.0959    -2.3107

Use BlackScholes Pricer and BlackScholes Model to Price Vanilla Instrument for Foreign Exchange

This example shows the workflow to price a Vanilla instrument for foreign exchange (FX) when you use a BlackScholes model and a BlackScholes pricing method. Assume that the current exchange rate is $0.52 and has a volatility of 12% per year. The annualized continuously compounded foreign risk-free rate is 8% per year.

Create Vanilla Instrument Object

Use fininstrument to create a Vanilla instrument object.

VanillaOpt = fininstrument("Vanilla",'ExerciseDate',datetime(2022,9,15),'Strike',.50,'OptionType',"put",'ExerciseStyle',"european",'Name',"vanilla_fx_option")

VanillaOpt = 
  Vanilla with properties:

       OptionType: "put"
    ExerciseStyle: "european"
     ExerciseDate: 15-Sep-2022
           Strike: 0.5000
             Name: "vanilla_fx_option"

Create BlackScholes Model Object

Use finmodel to create a BlackScholes model object.

Sigma = .12;
BlackScholesModel = finmodel("BlackScholes",'Volatility',Sigma)

BlackScholesModel = 
  BlackScholes with properties:

     Volatility: 0.1200
    Correlation: 1

Create ratecurve Object

Create a ratecurve object using ratecurve.

Settle = datetime(2018,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: [10×1 datetime]
                Rates: [10×1 double]
               Settle: 15-Sep-2018
         InterpMethod: "linear"
    ShortExtrapMethod: "next"
     LongExtrapMethod: "previous"

Create BlackScholes Pricer Object

Use finpricer to create a BlackScholes pricer object and use the ratecurve object for the 'DiscountCurve' name-value pair argument. When you price currencies using a Vanilla instrument, DividendType must be 'continuous' and DividendValue is the annualized risk-free interest rate in the foreign country.

ForeignRate = 0.08;
outPricer = finpricer("analytic",'DiscountCurve',myRC,'Model',BlackScholesModel,'SpotPrice',.52,'DividendType',"continuous",'DividendValue',ForeignRate)

outPricer = 
  BlackScholes with properties:

    DiscountCurve: [1×1 ratecurve]
            Model: [1×1 finmodel.BlackScholes]
        SpotPrice: 0.5200
    DividendValue: 0.0800
     DividendType: "continuous"

Price Vanilla Instrument

Use price to compute the price and sensitivities for the Vanilla FX instrument.

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

Price = 
0.1123

outPR = 
  priceresult with properties:

       Results: [1×7 table]
    PricerData: []

outPR.Results

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

    0.11229    -0.59114    1.5562    -3.7706    0.20212    -1.6799    -0.023676

More About

Black-Scholes Pricing Method

The Black-Scholes pricing method provides a framework for valuing options based on several key factors, including the underlying asset price, strike price, time to expiration, risk-free interest rate, and volatility.

Version History

Introduced in R2020a