`Spread` instrument object

## Description

Create and price a `Spread` instrument object for one or more Spread instruments using this workflow:

1. Use `fininstrument` to create a `Spread` instrument object for one or more Spread instruments.

2. Use `finmodel` to specify a `BlackScholes` or `Bachelier` model for the `Spread` instrument object.

3. Choose a pricing method.

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 `Spread` instrument, see Choose Instruments, Models, and Pricers.

## Creation

### Syntax

``SpreadObj = fininstrument(InstrumentType,'Strike',strike_value,'ExerciseDate',exercise_date)``
``SpreadObj = fininstrument(___,Name,Value)``

### Description

example

````SpreadObj = fininstrument(InstrumentType,'Strike',strike_value,'ExerciseDate',exercise_date)` creates a `Spread` object for one or more Spread instruments by specifying `InstrumentType` and sets the properties for the required name-value pair arguments `Strike` and `ExerciseDate`.```

example

````SpreadObj = fininstrument(___,Name,Value)` sets optional properties using additional name-value pairs in addition to the required arguments in the previous syntax. For example, ```SpreadObj = fininstrument("Spread",'Strike',100,'ExerciseDate',datetime(2019,1,30),'OptionType',"put",'ExerciseStyle',"American",'Name',"spread_instrument")``` creates a `Spread` put option with an American exercise. You can specify multiple name-value pair arguments.```

### Input Arguments

expand all

Instrument type, specified as a string with the value of `"Spread"`, a character vector with the value of `'Spread'`, an `NINST`-by-`1` string array with values of `"Spread"`, or an `NINST`-by-`1` cell array of character vectors with values of `'Spread'`.

Data Types: `char` | `cell` | `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: ```SpreadObj = fininstrument("Spread",'Strike',100,'ExerciseDate',datetime(2019,1,30),'OptionType',"put",'ExerciseStyle',"American",'Name',"spread_instrument")```

Required `Spread` Name-Value Pair Arguments

expand all

Option strike price value, specified as the comma-separated pair consisting of `'Strike'` and a scalar nonnegative numeric or an `NINST`-by-`1` nonnegative numeric vector.

Data Types: `double`

Option exercise date, specified as the comma-separated pair consisting of `'ExerciseDate'` and a scalar or an `NINST`-by-`1` vector using a datetime array, string array, or date character vectors.

Note

For a European option, there is only one `ExerciseDate` on the option expiry date.

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

If you use date character vectors or strings, the format must be recognizable by `datetime` because the `ExerciseDate` property is stored as a datetime.

Optional `Spread` Name-Value Pair Arguments

expand all

Option type, specified as the comma-separated pair consisting of `'OptionType'` and a scalar string or character vector or an `NINST`-by-`1` cell array of character vectors or string array.

Data Types: `char` | `cell` | `string`

Option exercise style, specified as the comma-separated pair consisting of `'ExerciseStyle'` and a scalar string or character vector or an `NINST`-by-`1` cell array of character vectors or string array.

Data Types: `string` | `cell` | `char`

User-defined name for one of more instruments, specified as the comma-separated pair consisting of `'Name'` and a scalar string or character vector or an `NINST`-by-`1` cell array of character vectors or string array.

Data Types: `char` | `cell` | `string`

## Properties

expand all

Option strike price value, returned as a scalar nonnegative numeric or an `NINST`-by-`1` nonnegative numeric vector.

Data Types: `double`

Option exercise date, returned as a scalar datetime or an `NINST`-by-`1` vector of datetimes.

Data Types: `datetime`

Option type, returned as a scalar string or an `NINST`-by-`1` string array with values of `"call"` or `"put"`.

Data Types: `string`

Option exercise style, returned as a string or an `NINST`-by-`1` string array with values of `"European"`.

Data Types: `string`

User-defined name for the instrument, returned as a scalar string or an `NINST`-by-`1` string array.

Data Types: `string`

## Examples

collapse all

This example shows the workflow to price a `Spread` instrument with a European option when using a `BlackScholes` model and a `BjerksundStensland` pricing method.

Create `Spread` Instrument Object

Use `fininstrument` to create a `Spread` instrument object.

`SpreadOpt = fininstrument("Spread",'Strike',105,'ExerciseDate',datetime(2021,9,15),'OptionType',"put",'ExerciseStyle',"european",'Name',"spread_option")`
```SpreadOpt = Spread with properties: OptionType: "put" Strike: 105 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',[103 105],'DividendValue',[0.025 , 0.028],'PricingMethod',"BjerksundStensland")`
```outPricer = BjerksundStensland with properties: DiscountCurve: [1x1 ratecurve] Model: [1x1 finmodel.BlackScholes] SpotPrice: [103 105] DividendValue: [0.0250 0.0280] DividendType: "continuous" ```

Price `Spread` Instrument

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

`[Price, outPR] = price(outPricer,SpreadOpt,["all"])`
```Price = 95.9884 ```
```outPR = priceresult with properties: Results: [1x7 table] PricerData: [] ```
`outPR.Results`
```ans=1×7 table Price Delta Gamma Lambda Vega Theta Rho ______ __________________ _______________________ ____________________ ________________ _____ _______ 95.988 -0.8916 0.90457 0.0021316 0.00048175 -0.95673 0.97064 13.582 1.5785 3.135 -278.49 ```

This example shows the workflow to price multiple `Spread` instruments with a European option when using a `BlackScholes` model and a `BjerksundStensland` pricing method.

Create `Spread` Instrument Object

Use `fininstrument` to create a `Spread` instrument object for three Spread instruments.

`SpreadOpt = fininstrument("Spread",'Strike',[105 ; 120 ; 150],'ExerciseDate',datetime([2021,9,15 ; 2021,10,15 ; 2021,11,15]),'OptionType',"put",'ExerciseStyle',"european",'Name',"spread_option")`
```SpreadOpt=3×1 object 3x1 Spread array with properties: OptionType Strike ExerciseStyle ExerciseDate Name ```

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',[103 160],'DividendValue',[0.025 , 0.028],'PricingMethod',"BjerksundStensland")`
```outPricer = BjerksundStensland with properties: DiscountCurve: [1x1 ratecurve] Model: [1x1 finmodel.BlackScholes] SpotPrice: [103 160] DividendValue: [0.0250 0.0280] DividendType: "continuous" ```

Price `Spread` Instruments

Use `price` to compute the prices and sensitivities for the `Spread` instruments.

`[Price, outPR] = price(outPricer,SpreadOpt,["all"])`
```Price = 3×1 146.1732 159.1989 185.5513 ```
```outPR=3×1 object 3x1 priceresult array with properties: Results PricerData ```
`outPR.Results`
```ans=1×7 table Price Delta Gamma Lambda Vega Theta Rho ______ ____________________ ________________________ ____________________ _________________ ______ _______ 146.17 -0.91985 0.91683 0.00057696 7.9581e-05 -0.64817 0.64604 3.6848 0.60671 4.9043 -282.63 ```
```ans=1×7 table Price Delta Gamma Lambda Vega Theta Rho _____ ____________________ ________________________ ____________________ _________________ ______ _______ 159.2 -0.92024 0.91557 0.00042064 5.4001e-05 -0.59539 0.59237 2.7723 0.40502 5.3984 -331.26 ```
```ans=1×7 table Price Delta Gamma Lambda Vega Theta Rho ______ ____________________ ______________________ ____________________ _________________ ______ _______ 185.55 -0.92123 0.91439 0.000216 1.9895e-05 -0.51138 0.50758 1.4478 0.16988 6.3711 -424.75 ```

This example shows the workflow to price a commodity `Spread` instrument when you use a `BlackScholes` model and `Kirk` and `BjerksundStensland` analytic pricing methods.

In the petroleum industry, refiners are concerned about the difference between their input costs (crude oil) and output prices (refined products — gasoline, heating oil, diesel fuel, and so on). The differential between these two underlying commodities is referred to as a crack spread. It represents the profit margin between crude oil and the refined products.

A spread option is an option on the spread where the holder has the right, but not the obligation, to enter into a spot or forward spread contract. Crack spread options are often used to protect against declines in the crack spread or to monetize volatility or price expectations on the spread.

Define the Commodity

Assume that current gasoline prices are strong, and you want to model a crack spread option strategy to protect the gasoline margin. A crack spread option strategy is used to maintain profits for the following season. The WTI crude oil futures are at \$93.20 per barrel and RBOB gasoline futures contract are at \$2.85 per gallon.

```Strike = 20; Rate = 0.05; Settle = datetime(2020,1,1); Maturity = datemnth(Settle,3); % Price and volatility of RBOB gasoline PriceGallon1 = 2.85; % Dollars per gallon Price1 = PriceGallon1 * 42; % Dollars per barrel Vol1 = 0.29; % Price and volatility of WTI crude oil Price2 = 93.20; % Dollars per barrel Vol2 = 0.36; % Correlation between the prices of the commodities Corr = 0.42;```

Create `Spread` Instrument Object

Use `fininstrument` to create a `Spread` instrument object.

`SpreadOpt = fininstrument("Spread", 'ExerciseDate', Maturity, 'Strike', Strike,'ExerciseStyle',"european",'Name',"spread_instrument")`
```SpreadOpt = Spread with properties: OptionType: "call" Strike: 20 ExerciseStyle: "european" ExerciseDate: 01-Apr-2020 Name: "spread_instrument" ```

Create `BlackScholes` Model Object

Use `finmodel` to create a `BlackScholes` model object.

`BlackScholesModel = finmodel("BlackScholes", 'Volatility', [Vol1,Vol2], 'Correlation', [1 Corr; Corr 1]);`

Create `ratecurve` Object

Create a flat `ratecurve` object using `ratecurve`.

`ZeroCurve = ratecurve('zero', Settle, Maturity, Rate, 'Basis', 1);`

Create `BjerksundStensland` Pricer Object

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

`BJSPricer = finpricer("Analytic", 'Model', BlackScholesModel, 'SpotPrice', [Price1 , Price2], 'DiscountCurve', ZeroCurve,'PricingMethod', "BjerksundStensland");`

Create `Kirk` Pricer Object

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

`KirkPricer = finpricer("Analytic", 'Model', BlackScholesModel,'SpotPrice', [Price1 , Price2], 'DiscountCurve', ZeroCurve,'PricingMethod', "Kirk");`

Price `Spread` Instrument Using `BjerksundStensland` and `Kirk` Analytic Pricing Methods

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

```[PriceKirk, outPR_Kirk] = price(KirkPricer, SpreadOpt, "all"); [PriceBJS, outPR_BJS] = price(BJSPricer, SpreadOpt, "all"); [outPR_Kirk.Results; outPR_BJS.Results]```
```ans=2×7 table Price Delta Gamma Lambda Vega Theta Rho _____ ___________________ ____________________ _________________ ________________ _______ ______ 11.19 0.67224 -0.60665 0.019081 0.021662 7.1907 -6.4891 11.299 9.8869 -14.539 3.1841 11.2 0.67371 -0.60816 0.018992 0.021572 7.2003 -6.4997 11.198 9.9878 -14.555 3.1906 ```

This example shows the workflow to price a `Spread` instrument with an American option when using a `BlackScholes` model and an `AssetMonteCarlo` pricing method.

Create `Spread` Instrument Object

Use `fininstrument` to create a `Spread` instrument object.

`SpreadOpt = fininstrument("Spread",'Strike',100,'ExerciseDate',datetime(2021,9,15),'OptionType',"put",'ExerciseStyle',"American",'Name',"spread_option")`
```SpreadOpt = Spread with properties: OptionType: "put" Strike: 100 ExerciseStyle: "american" ExerciseDate: 15-Sep-2021 Name: "spread_option" ```

Create `BlackScholes` Model Object

Use `finmodel` to create a `BlackScholes` model object.

```Corr = 0.42; BlackScholesModel = finmodel("BlackScholes","Volatility",[0.3,0.1],"Correlation", [1 Corr;Corr 1])```
```BlackScholesModel = BlackScholes with properties: Volatility: [0.3000 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 `AssetMonteCarlo` Pricer Object

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

`outPricer = finpricer("AssetMonteCarlo","DiscountCurve",myRC,"Model",BlackScholesModel,'SpotPrice',[100,95],'simulationDates',datetime(2021,9,15),'dividendType',["continuous","continuous"],'dividendvalue',[0,0.01])`
```outPricer = GBMMonteCarlo with properties: DiscountCurve: [1x1 ratecurve] SpotPrice: [100 95] SimulationDates: 15-Sep-2021 NumTrials: 1000 RandomNumbers: [] Model: [1x1 finmodel.BlackScholes] DividendType: ["continuous" "continuous"] DividendValue: [0 0.0100] ```

Price `Spread` Instrument

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

`[Price, outPR] = price(outPricer,SpreadOpt,["all"])`
```Price = 95 ```
```outPR = priceresult with properties: Results: [1x7 table] PricerData: [1x1 struct] ```
`outPR.Results`
```ans=1×7 table Price Delta Gamma Lambda Rho Theta Vega _____ ________ _______________ __________________ ___ _____ ______ 95 -1 1 0 3.1492e-14 -1.0526 1 0 0 0 0 ```

This example shows the workflow to price a `Spread` instrument with an American option when using a `Bachelier` model and an `AssetMonteCarlo` pricing method.

Create `Spread` Instrument Object

Use `fininstrument` to create a `Spread` instrument object.

`SpreadOpt = fininstrument("Spread",'Strike',100,'ExerciseDate',datetime(2021,9,15),'OptionType',"put",'ExerciseStyle',"American",'Name',"spread_option")`
```SpreadOpt = Spread with properties: OptionType: "put" Strike: 100 ExerciseStyle: "american" ExerciseDate: 15-Sep-2021 Name: "spread_option" ```

Create `Bachelier` Model Object

Use `finmodel` to create a `Bachelier` model object.

```Corr = 0.42; BachelierModel = finmodel("BlackScholes","Volatility",[0.3,0.1],"Correlation", [1 Corr;Corr 1])```
```BachelierModel = BlackScholes with properties: Volatility: [0.3000 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 `AssetMonteCarlo` Pricer Object

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

`outPricer = finpricer("AssetMonteCarlo","DiscountCurve",myRC,"Model",BachelierModel,'SpotPrice',[100,95],'simulationDates',datetime(2021,9,15),'dividendType',["continuous","continuous"],'dividendvalue',[0,0.01])`
```outPricer = GBMMonteCarlo with properties: DiscountCurve: [1x1 ratecurve] SpotPrice: [100 95] SimulationDates: 15-Sep-2021 NumTrials: 1000 RandomNumbers: [] Model: [1x1 finmodel.BlackScholes] DividendType: ["continuous" "continuous"] DividendValue: [0 0.0100] ```

Price `Spread` Instrument

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

`[Price, outPR] = price(outPricer,SpreadOpt,["all"])`
```Price = 95 ```
```outPR = priceresult with properties: Results: [1x7 table] PricerData: [1x1 struct] ```
`outPR.Results`
```ans=1×7 table Price Delta Gamma Lambda Rho Theta Vega _____ ________ _______________ __________________ ___ _____ ______ 95 -1 1 0 3.1492e-14 -1.0526 1 0 0 0 0 ```