instbarrier

Construct barrier option

Syntax

InstSet = instbarrier(OptSpec,Strike,Settle,ExerciseDates,AmericanOpt,BarrierSpec,Barrier,Rebate)

InstSet = instbarrier(InstSetOld,OptSpec,Strike,Settle,ExerciseDates,AmericanOpt,BarrierSpec,Barrier,Rebate)

[FieldList,ClassList,TypeString] = instbarrier

Description

InstSet = instbarrier(OptSpec,Strike,Settle,ExerciseDates,AmericanOpt,BarrierSpec,Barrier,Rebate) constructs a barrier instrument.

Data arguments are NINST-by-1 vectors, scalar, or empty. Fill in unspecified entries vectors with NaN. Only one data argument is required to create the instrument. The others can be omitted or passed as empty matrices [].

InstSet = instbarrier(InstSetOld,OptSpec,Strike,Settle,ExerciseDates,AmericanOpt,BarrierSpec,Barrier,Rebate) adds barrier options to an existing instrument variable InstSetOld).

[FieldList,ClassList,TypeString] = instbarrier lists field metadata for the barrier instrument.

Examples

Create Two Barrier Option Instruments

Create an instrument set of two barrier options with the following data:

OptSpec = {'put';'call'};
Strike = 112;
Settle = datetime(2012,1,1);
ExerciseDates = datetime(2015,1,1);
BarrierSpec = {'do';'ui'};
Barrier = [101;102];
AmericanOpt = 0;

Create the instrument set (InstSet) for the two barrier options.

InstSet = instbarrier(OptSpec, Strike, Settle, ExerciseDates,AmericanOpt, BarrierSpec, Barrier);

Display the instrument set.

instdisp(InstSet)

Index Type    OptSpec Strike Settle         ExerciseDates  AmericanOpt BarrierSpec Barrier Rebate
1     Barrier put     112    01-Jan-2012    01-Jan-2015    0           do          101     0     
2     Barrier call    112    01-Jan-2012    01-Jan-2015    0           ui          102     0     
 

Input Arguments

OptSpec — Definition of option

character vector with values 'call' or 'put'

Definition of an option as 'call' or 'put', specified as a NINST-by-1 list of character vector values.

Data Types: char

Strike — Option strike price value

integer

Option strike price value, specified as an NINST-by-1 vector of strike values. Each row is the schedule for one option.

Data Types: double

Settle — Settlement or trade date

datetime array | string array | date character vector

Settlement date for the barrier option, specified as a NINST-by-1 vector using a datetime array, string array, or date character vectors.

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

ExerciseDates — Option exercise dates

datetime array | string array | date character vector

Option exercise dates, specified as a datetime array, string array, or date character vectors:

• For a European option (AmericanOpt = 0), specified as a NINST-by-1 matrix of exercise dates. Each row is the schedule for one option. For a European option, there is only one exercise date, the option expiry date.

• For an American option (AmericanOpt = 1), specified as a NINST-by-2 vector of exercise date boundaries. For each instrument, the option can be exercised on any tree date between or including the pair of dates on that row. If only one non-NaN date is listed, or if ExerciseDates is NINST-by-1, the option can be exercised between the valuation date of the stock tree and the single listed exercise date.

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

AmericanOpt — Flag for American option

integer with values 0 or 1

Flag for American option, specified as an integer with values 0 or 1. If AmericanOpt = 0, NaN, or is unspecified, the option is a European option. If AmericanOpt = 1, the option is an American option.

Data Types: logical

BarrierSpec — Barrier option type

character vector with values: 'UI', 'UO', 'DI', 'DO'

Barrier option type, specified as a character vector with the following values:

• 'UI' — Up Knock In

  This option becomes effective when the price of the underlying asset passes above the barrier level. It gives the option holder the right, but not the obligation, to buy/sell (call/put) the underlying security at the strike price if the underlying asset goes above the barrier level during the life of the option.

• 'UO' — Up Knock Out

  This option gives the option holder the right, but not the obligation, to buy/sell (call/put) the underlying security at the strike price as long as the underlying asset does not go above the barrier level during the life of the option. This option terminates when the price of the underlying asset passes above the barrier level. Usually, with an up-and-out option, the rebate is paid if the spot price of the underlying reaches or exceeds the barrier level.

• 'DI' — Down Knock In

  This option becomes effective when the price of the underlying stock passes below the barrier level. It gives the option holder the right, but not the obligation, to buy/sell (call/put) the underlying security at the strike price if the underlying security goes below the barrier level during the life of the option. With a down-and-in option, the rebate is paid if the spot price of the underlying does not reach the barrier level during the life of the option.

• 'DO' — Down Knock Up

  This option gives the option holder the right, but not the obligation, to buy/sell (call/put) the underlying asset at the strike price as long as the underlying asset does not go below the barrier level during the life of the option. This option terminates when the price of the underlying security passes below the barrier level. Usually the option holder receives a rebate amount if the option expires worthless.

Option	Barrier Type	Payoff if Barrier Crossed	Payoff if Barrier not Crossed
Call/Put	Down Knock-out	Worthless	Standard Call/Put
Call/Put	Down Knock-in	Call/Put	Worthless
Call/Put	Up Knock-out	Worthless	Standard Call/Put
Call/Put	Up Knock-in	Standard Call/Put	Worthless

Data Types: char

Barrier — Barrier value

integer

Barrier value, specified as a vector of values.

Data Types: double

Rebate — Rebate value

integer

(Optional) Rebate value, specified as a vector of values.

Data Types: double

InstSetOld — Instrument variable

structure

(Optional) Instrument variable, this argument is specified only when adding barrier instruments to an existing instrument set. See instget for more information on the InstSet variable.

Data Types: struct

Output Arguments

InstSet — Instrument variable for barrier option

structure

Instrument variable for barrier option, returned as a structure. See instget for more information on the InstSet variable.

FieldList — Fields in InstSet instrument

cell array of character vectors

Fields in InstSet instrument are returned as a (NFIELDS-by-1) cell array of character vectors listing the name of each data field for this instrument type.

ClassList — Data class of each field in InstSet instrument

cell array of character vectors

Data class of each field in InstSet instrument, returned as an NFIELDS-by-1 cell array of character vectors listing the data class of each field. The class determines how arguments are parsed. Valid character vectors are 'dble', 'date', and 'char'.

TypeString — Type of instrument added to InstSet instrument

character vector

Type of instrument added to InstSet instrument, returned as a character vector specifying the type of instrument added. For a barrier option instrument, TypeString = 'Barrier'.

More About

Barrier Option

A barrier option has not only a strike price but also a barrier level and sometimes a rebate.

A rebate is a fixed amount that is paid if the option cannot be exercised because the barrier level has been reached or not reached. The payoff for this type of option depends on whether the underlying asset crosses the predetermined trigger value (barrier level), indicated by Barrier, during the life of the option.

Version History

Introduced before R2006a

R2022b: Serial date numbers not recommended

Although instbarrier supports serial date numbers, datetime values are recommended instead. The datetime data type provides flexible date and time formats, storage out to nanosecond precision, and properties to account for time zones and daylight saving time.

To convert serial date numbers or text to datetime values, use the datetime function. For example:

t = datetime(738427.656845093,"ConvertFrom","datenum");
y = year(t)

y =

        2021

There are no plans to remove support for serial date number inputs.