# CDSOption

`CDSOption` instrument object

## Description

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

1. Use `fininstrument` to create a `CDSOption` instrument object for one or more CDS Option instruments. By default, this creates a single-name CDS option. You can create a CDS index option by specifying the optional name-value argument `AdjustedForwardSpread`.

2. Use `finmodel` to specify a `CDSBlack` model for the `CDSoption` instrument object.

3. Use `finpricer` to specify a `CDSBlack` pricing method for one or more `CDSoption` instruments.

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

## Creation

### Syntax

``CDSOptionObj = fininstrument(InstrumentType,'ExerciseDate',exercise_date,'Strike',strike_value,'CDS',cds_obj)``
``CDSOptionObj = fininstrument(___,Name,Value)``

### Description

example

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

example

````CDSOptionObj = fininstrument(___,Name,Value)` sets optional properties using additional name-value pairs in addition to the required arguments in the previous syntax. For example, ```CDSOptionObj = fininstrument("CDSoption",'ExerciseDate',datetime(2019,1,30),'Strike',500,'CDS',cds_object,'Name',"cdsoption_instrument")``` creates a `CDSOption` instrument for a single-name CDS option with a strike of 500. You can specify multiple name-value pair arguments.```

### Input Arguments

expand all

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

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: ```CDSOptionObj = fininstrument("CDSoption",'ExerciseDate',datetime(2019,1,30),'Strike',500,'CDS',cds_object,'Name',"cdsoption_instrument")```

Required `CDSOption` Name-Value Pair Arguments

expand all

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.

To support existing code, `CDSOption` 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.

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

Data Types: `double`

`CDS` object, specified as the comma-separated pair consisting of `'CDS'` and a scalar `CDS` object or an `NINST`-by-`1` vector of `CDS` objects.

Data Types: `object`

Optional `CDSOption` Name-Value Pair Argument

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`

Flag indicating if option is knockout type, specified as the comma-separated pair consisting of `'Knockout'` and a scalar logical or an `NINST`-by-`1` vector of logical values.

Data Types: `logical`

Adjusted forward spread (in basis points) for pricing a CDS index option, specified as the comma-separated pair consisting of `'AdjustedForwardSpread'` and a scalar numeric or an `NINST`-by-`1` numeric vector. For more information on using `'AdjustedForwardSpread'` when pricing a CDS index option, see Price CDS Index Options Using CDS Black Model and CDS Black Pricer.

Data Types: `double`

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 exercise date, returned as a scalar datetime or an `NINST`-by-`1` vector of datetimes.

Data Types: `datetime`

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

Data Types: `double`

`CDS` object, returned as a scalar `CDS` object or an `NINST`-by-`1` vector of CDS objects.

Data Types: `object`

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

Data Types: `string`

Flag indicating if option is knockout type, returned as a scalar logical or an `NINST`-by-`1` vector of logicals.

Data Types: `logical`

Adjusted forward spread (in basis points) for pricing a CDS index option, returned as a scalar numeric or an `NINST`-by-`1` numeric vector.

Data Types: `double`

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 `CDSOption` instrument for a single-name CDS option when you use a `CDSBlack` model and a `CDSBlack` pricing method.

Create `CDS` Instrument Object

Use `fininstrument` to create the underlying `CDS` instrument object.

`CDSOpt = fininstrument("CDS",'Maturity',datetime(2021,9,15),'ContractSpread',150,'Notional',100,'Name',"CDS_option")`
```CDSOpt = CDS with properties: ContractSpread: 150 Maturity: 15-Sep-2021 Period: 4 Basis: 2 RecoveryRate: 0.4000 BusinessDayConvention: "actual" Holidays: NaT PayAccruedPremium: 1 Notional: 100 Name: "CDS_option" ```

Create `defprobcurve` Object

Create a `defprobcurve` object using `defprobcurve`.

```Settle = datetime(2020,9,20); DefProbTimes = [calmonths(6) calyears([1 2 3 4 5 7 10 20 30])]; DefaultProbabilities = [0.005 0.007 0.01 0.015 0.026 0.04 0.077 0.093 0.15 0.20]'; ProbDates = Settle + DefProbTimes; DefaultProbCurve = defprobcurve(Settle,ProbDates,DefaultProbabilities,'Basis',5)```
```DefaultProbCurve = defprobcurve with properties: Settle: 20-Sep-2020 Basis: 5 Dates: [10x1 datetime] DefaultProbabilities: [10x1 double] ```

Create `ratecurve` Object

Create a `ratecurve` object using `ratecurve`.

```Settle = datetime(2020,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-2020 InterpMethod: "linear" ShortExtrapMethod: "next" LongExtrapMethod: "previous" ```

Create `CDSOption` Instrument Object

Use `fininstrument` to create a `CDSOption` instrument object for a single-name CDS option.

`CDSOptionInst = fininstrument("CDSOption",'ExerciseDate',datetime(2021,8,15),'Strike',20,'CDS',CDSOpt,'OptionType',"put",'Knockout',true,'Name',"CDSOption_option")`
```CDSOptionInst = CDSOption with properties: OptionType: "put" Strike: 20 Knockout: 1 AdjustedForwardSpread: NaN ExerciseDate: 15-Aug-2021 CDS: [1x1 fininstrument.CDS] Name: "CDSOption_option" ```

Create `CDSBlack` Model Object

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

`CDSBlackModel = finmodel("CDSBlack",'SpreadVolatility',.2)`
```CDSBlackModel = CDSBlack with properties: SpreadVolatility: 0.2000 ```

Create `CDSBlack` Pricer Object

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

`outPricer = finpricer("analytic",'Model',CDSBlackModel,'DefaultProbabilityCurve',DefaultProbCurve,'DiscountCurve',myRC)`
```outPricer = CDSBlack with properties: Model: [1x1 finmodel.CDSBlack] DiscountCurve: [1x1 ratecurve] DefaultProbabilityCurve: [1x1 defprobcurve] ```

Price `CDSOption` Instrument

Use `price` to compute the price for the `CDSOption` instrument for a single-name CDS option.

`Price = price(outPricer,CDSOptionInst)`
```Price = 3.3016e-04 ```

This example shows the workflow to price multiple `CDSOption` instruments when you use a `CDSBlack` model and a `CDSBlack` pricing method.

Create `CDS` Instrument Object

Use `fininstrument` to create the underlying `CDS` instrument object for three CDS Option instruments.

`CDSOpt = fininstrument("CDS",'Maturity',datetime([2021,9,15 ; 2021,10,15 ; 2021,11,15]),'ContractSpread',150,'Notional',[10000 ; 20000 ; 30000],'Name',"CDS_option")`
```CDSOpt=3×1 object 3x1 CDS array with properties: ContractSpread Maturity Period Basis RecoveryRate BusinessDayConvention Holidays PayAccruedPremium Notional Name ```

Create `defprobcurve` Object

Create a `defprobcurve` object using `defprobcurve`.

```Settle = datetime(2020,9,20); DefProbTimes = [calmonths(6) calyears([1 2 3 4 5 7 10 20 30])]; DefaultProbabilities = [0.005 0.007 0.01 0.015 0.026 0.04 0.077 0.093 0.15 0.20]'; ProbDates = Settle + DefProbTimes; DefaultProbCurve = defprobcurve(Settle,ProbDates,DefaultProbabilities,'Basis',5)```
```DefaultProbCurve = defprobcurve with properties: Settle: 20-Sep-2020 Basis: 5 Dates: [10x1 datetime] DefaultProbabilities: [10x1 double] ```

Create `ratecurve` Object

Create a `ratecurve` object using `ratecurve`.

```Settle = datetime(2020,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-2020 InterpMethod: "linear" ShortExtrapMethod: "next" LongExtrapMethod: "previous" ```

Create `CDSOption` Instrument Object

Use `fininstrument` to create a `CDSOption` instrument object for three single-name CDS options.

`CDSOptionInst = fininstrument("CDSOption",'ExerciseDate',datetime(2021,8,15),'Strike',20,'CDS',CDSOpt,'OptionType',"put",'Knockout',true,'Name',"CDSOption_option")`
```CDSOptionInst=3×1 object 3x1 CDSOption array with properties: OptionType Strike Knockout AdjustedForwardSpread ExerciseDate CDS Name ```

Create `CDSBlack` Model Object

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

`CDSBlackModel = finmodel("CDSBlack",'SpreadVolatility',.2)`
```CDSBlackModel = CDSBlack with properties: SpreadVolatility: 0.2000 ```

Create `CDSBlack` Pricer Object

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

`outPricer = finpricer("analytic",'Model',CDSBlackModel,'DefaultProbabilityCurve',DefaultProbCurve,'DiscountCurve',myRC)`
```outPricer = CDSBlack with properties: Model: [1x1 finmodel.CDSBlack] DiscountCurve: [1x1 ratecurve] DefaultProbabilityCurve: [1x1 defprobcurve] ```

Price `CDSOption` Instruments

Use `price` to compute the prices for the three `CDSOption` instruments.

`Price = price(outPricer,CDSOptionInst)`
```Price = 3×1 0.0003 0.0384 0.5941 ```

This example shows the workflow to use a `CDSOption` instrument to price CDS index options when you use a `CDSBlack` model and a `CDSBlack` pricing method.

Set Up Data for CDS Index

```% CDS index and option data Recovery = .4; Basis = 2; Period = 4; CDSMaturity = datetime(2017,6,20); ContractSpread = 100; IndexSpread = 140; BusDayConvention = 'follow'; Settle = datetime(2012,4,13); OptionMaturity = datetime(2012,6,20); OptionStrike = 140; SpreadVolatility = .69;```

Create `ratecurve` Object for Zero Curve Using `irbootstrap`

Create `ratecurve` object for a zero curve using `irbootstrap`.

```% Zero curve data DepRates = [0.004111 0.00563 0.00757 0.01053]'; DepTimes = calmonths([1 2 3 6]'); DepDates = Settle + DepTimes; nDeposits = length(DepTimes); SwapRates = [0.01387 0.01035 0.01145 0.01318 0.01508 0.01700 0.01868 ... 0.02012 0.02132 0.02237 0.02408 0.02564 0.02612 0.02524]'; SwapTimes = calyears([1 2 3 4 5 6 7 8 9 10 12 15 20 30]'); SwapDates = Settle + SwapTimes; nSwaps = length(SwapTimes); nInst = nDeposits + nSwaps; BootInstruments(nInst,1) = fininstrument.FinInstrument; for ii=1:length(DepDates) BootInstruments(ii) = fininstrument("deposit","Maturity",DepDates(ii),"Rate",DepRates(ii)); end for ii=1:length(SwapDates) BootInstruments(ii+nDeposits) = fininstrument("swap","Maturity",SwapDates(ii),"LegRate",[SwapRates(ii) 0]); end ZeroCurve = irbootstrap(BootInstruments,Settle)```
```ZeroCurve = ratecurve with properties: Type: "zero" Compounding: -1 Basis: 0 Dates: [18x1 datetime] Rates: [18x1 double] Settle: 13-Apr-2012 InterpMethod: "linear" ShortExtrapMethod: "next" LongExtrapMethod: "previous" ```

Bootstrap Default Probability Curve

Use `defprobstrip` to bootstrap default probability curve assuming a flat index spread.

```ProbDates = datemnth(OptionMaturity,(0:5*12)'); MarketCDSInstruments = fininstrument("cds", ... 'ContractSpread', ContractSpread, 'Maturity', CDSMaturity); DefaultProbCurve = defprobstrip(ZeroCurve, MarketCDSInstruments, IndexSpread, 'ProbDates', ProbDates)```
```DefaultProbCurve = defprobcurve with properties: Settle: 13-Apr-2012 Basis: 2 Dates: [61x1 datetime] DefaultProbabilities: [61x1 double] ```

Compute Spot and Forward RPV01s

Compute the spot and forward RPV01s using `cdsrpv01`.

```ProbData = [datenum(DefaultProbCurve.Dates) DefaultProbCurve.DefaultProbabilities]; % RPV01(t,T) RPV01_CDSMaturity = cdsrpv01(ZeroCurve,ProbData,Settle,CDSMaturity)```
```RPV01_CDSMaturity = 4.7853 ```
```% RPV01(t,t_E,T) RPV01_OptionExpiryForward = cdsrpv01(ZeroCurve,ProbData,Settle,CDSMaturity,... 'StartDate',OptionMaturity)```
```RPV01_OptionExpiryForward = 4.5972 ```
```% RPV01(t,t_E) = RPV01(t,T) - RPV01(t,t_E,T) RPV01_OptionExpiry = RPV01_CDSMaturity - RPV01_OptionExpiryForward```
```RPV01_OptionExpiry = 0.1882 ```

Compute the spot spreads using `cdsspread`.

```% S(t,t_E) Spread_OptionExpiry = cdsspread(ZeroCurve,ProbData,Settle,OptionMaturity,... 'Period',Period,'Basis',Basis,'BusDayConvention',BusDayConvention,... 'PayAccruedPremium',true,'recoveryrate',Recovery)```
```Spread_OptionExpiry = 139.8995 ```
```% S(t,T) Spread_CDSMaturity = cdsspread(ZeroCurve,ProbData,Settle,CDSMaturity,... 'Period',Period,'Basis',Basis,'BusDayConvention',BusDayConvention,... 'PayAccruedPremium',true,'recoveryrate',Recovery)```
```Spread_CDSMaturity = 139.9999 ```

Compute the forward spread using the spot spreads and RPV01s.

```% F = S(t,t_E,T) ForwardSpread = (Spread_CDSMaturity.*RPV01_CDSMaturity - Spread_OptionExpiry.*RPV01_OptionExpiry)./RPV01_OptionExpiryForward```
```ForwardSpread = 140.0040 ```

Compute Front-End Protection

Compute the front-end protection (FEP).

`FEP = 10000*(1-Recovery)*ZeroCurve.discountfactors(OptionMaturity)*DefaultProbCurve.DefaultProbabilities(1)`
```FEP = 26.3108 ```

Compute the adjusted forward spread to use when creating an `CDSOption` instrument.

`AdjustedForwardSpread = ForwardSpread + FEP./RPV01_OptionExpiryForward`
```AdjustedForwardSpread = 145.7273 ```

Compute CDS Option Prices with Adjusted Forward Spread

Use `fininstrument` to create the underlying `CDS` instrument object for the two CDS Option instruments.

`CDS = fininstrument("cds",'ContractSpread', ContractSpread, 'Maturity', CDSMaturity)`
```CDS = CDS with properties: ContractSpread: 100 Maturity: 20-Jun-2017 Period: 4 Basis: 2 RecoveryRate: 0.4000 BusinessDayConvention: "actual" Holidays: NaT PayAccruedPremium: 1 Notional: 10000000 Name: "" ```

Use `fininstrument` to create a `CDSOption` instrument for two CDS index option instruments.

```CDSCallOption = fininstrument("cdsoption", 'Strike', OptionStrike, ... 'ExerciseDate', OptionMaturity, 'OptionType', 'call', 'CDS', CDS, ... 'Knockout',true, 'AdjustedForwardSpread', AdjustedForwardSpread)```
```CDSCallOption = CDSOption with properties: OptionType: "call" Strike: 140 Knockout: 1 AdjustedForwardSpread: 145.7273 ExerciseDate: 20-Jun-2012 CDS: [1x1 fininstrument.CDS] Name: "" ```
```CDSPutOption = fininstrument("cdsoption", 'Strike', OptionStrike, ... 'ExerciseDate', OptionMaturity, 'OptionType', 'put', 'CDS', CDS, ... 'Knockout',true, 'AdjustedForwardSpread', AdjustedForwardSpread)```
```CDSPutOption = CDSOption with properties: OptionType: "put" Strike: 140 Knockout: 1 AdjustedForwardSpread: 145.7273 ExerciseDate: 20-Jun-2012 CDS: [1x1 fininstrument.CDS] Name: "" ```

Create `CDSBlack` Model Object

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

`CDSOptionModel = finmodel("cdsblack",'SpreadVolatility',SpreadVolatility)`
```CDSOptionModel = CDSBlack with properties: SpreadVolatility: 0.6900 ```

Create `CDSBlack` Pricer Object

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

`CDSOptionpricer = finpricer("analytic",'Model',CDSOptionModel,'DiscountCurve',ZeroCurve,'DefaultProbabilityCurve',DefaultProbCurve)`
```CDSOptionpricer = CDSBlack with properties: Model: [1x1 finmodel.CDSBlack] DiscountCurve: [1x1 ratecurve] DefaultProbabilityCurve: [1x1 defprobcurve] ```

Price CDS Index Options

Use `price` to compute the price for the two CDS index options.

```outPrice = price(CDSOptionpricer, [CDSCallOption;CDSPutOption]); fprintf(' Payer: %.0f Receiver: %.0f \n',outPrice(1),outPrice(2));```
``` Payer: 92 Receiver: 66 ```

expand all

## References

[1] O'Kane, D. Modelling Single-name and Multi-name Credit Derivatives. Wiley, 2008, pp. 156–169.

## Version History

Introduced in R2020a

expand all