instoptbnd

Construct bond option

Syntax

InstSet = instoptbnd(BondIndex,OptSpec,Strike,ExerciseDates)

InstSet = instoptbnd(InstSet,BondIndex,OptSpec,Strike,ExerciseDates)

InstSet = instoptbnd(___,AmericanOpt)

[FieldList,ClassList,TypeString] = instoptbnd

Description

InstSet = instoptbnd(BondIndex,OptSpec,Strike,ExerciseDates) creates a new instrument set containing Bond option instruments.

InstSet = instoptbnd(InstSet,BondIndex,OptSpec,Strike,ExerciseDates) adds Bond option instruments to an existing instrument set.

InstSet = instoptbnd(___,AmericanOpt) adds an optional argument.

[FieldList,ClassList,TypeString] = instoptbnd lists field meta-data for the Bond option instrument.

Examples

Create a Bond Option Instrument

Create a new instrument variable with the following information:

BondIndex = 1;
OptSpec = 'call';
Strike= 85;
ExerciseDates = datetime(2014,11,1); 
AmericanOpt = 1;
CouponRate= [0.035;0.04];
Settle= datetime(2013,11,1); 
Maturity = datetime(2014,11,1); 
Period =1;

Create the instrument portfolio with two bonds.

InstSet = instbond(CouponRate, Settle, Maturity, ...
Period)

InstSet = struct with fields:
        FinObj: 'Instruments'
    IndexTable: [1×1 struct]
          Type: {'Bond'}
     FieldName: {{11×1 cell}}
    FieldClass: {{11×1 cell}}
     FieldData: {{11×1 cell}}

Create an option on the first bond

InstSet = instoptbnd(InstSet, BondIndex, OptSpec, Strike, ExerciseDates, AmericanOpt)

InstSet = struct with fields:
        FinObj: 'Instruments'
    IndexTable: [1×1 struct]
          Type: {2×1 cell}
     FieldName: {2×1 cell}
    FieldClass: {2×1 cell}
     FieldData: {2×1 cell}

Display the instrument set.

instdisp(InstSet)

Index Type CouponRate Settle         Maturity       Period Basis EndMonthRule IssueDate FirstCouponDate LastCouponDate StartDate Face
1     Bond 0.035      01-Nov-2013    01-Nov-2014    1      0     1            NaN       NaN             NaN            NaN       100 
2     Bond 0.04       01-Nov-2013    01-Nov-2014    1      0     1            NaN       NaN             NaN            NaN       100 
 
Index Type    UnderInd OptSpec Strike ExerciseDates  AmericanOpt
3     OptBond 1        call    85     01-Nov-2014    1          
 

Input Arguments

InstSet — Instrument variable

structure

Instrument variable, specified only when adding Bond option instruments to an existing instrument set. For more information on the InstSet variable, see instget.

Data Types: struct

BondIndex — Number of Bond instruments

vector

Number of Bond instruments, specified as a scalar or an NINST-by-1 vector of indices pointing to underlying instruments of Type 'Bond' which are stored in InstSet. See instbond for information on specifying the bond data.

Data Types: double

OptSpec — Definition of option

character vector with value 'call' or 'put' | cell array of character vectors with values 'call' or 'put'

Definition of option, specified as a scalar 'call' or 'put' using a character vector or an NINST-by-1 cell array of character vectors for 'call' or 'put'.

Data Types: char | cell

Strike — Option strike price value

matrix of nonnegative integers | vector of nonnegative integers

Option strike price value, specified as a scalar nonnegative integer or an NINST-by-1 vector of strike price values for a European option, an NINST by number of strikes (NSTRIKES) matrix of strike price values for a Bermuda option, or an NINST-by-1 vector of strike price values for each American option. Each row is the schedule for one option. If an option has fewer than NSTRIKES exercise opportunities, the end of the row is padded with NaNs.

Note

The interpretation of the Strike and ExerciseDates depends upon the setting of the AmericanOpt. If AmericanOpt = 0, NaN, or is unspecified, the option is a European or Bermuda option. If AmericanOpt = 1, the option is an American option.

Data Types: double

ExerciseDates — Option exercise dates

datetime array | string array | date character vector

Option exercise dates, specified as a scalar or an NINST-by-2 vector using a datetime array, string array, or date character vectors of exercise date boundaries. For each instrument, the option can be exercised on any coupon 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 underlying bond Settle and the single listed exercise date.

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

AmericanOpt — Option type

0 European (default) | integer with values 0 or 1

(Optional) Option type, specified as a scalar or an NINST-by-1 integer flags with values:

• 0 — European

• 1 — American

Data Types: single | double

Output Arguments

InstSet — Variable containing a collection of instruments

structure

Variable containing a collection of instruments, returned as a structure. Instruments are broken down by type and each type can have different data fields. Each stored data field has a row vector or string for each instrument. For more information on the InstSet variable, see instget.

FieldList — Name of each data field for Bond option instrument

cell array of character vectors

Name of each data field for a Bond option instrument, returned as an NFIELDS-by-1 cell array of character vectors.

ClassList — Data class for each field

cell array of character vectors

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

TypeString — Type of instrument

character vector

Type of instrument, returned as a character vector. For a Bond option instrument, TypeString = 'OptBond'.

More About

Bond Option

A bond option gives the holder the right to sell a bond back to the issuer (put) or to redeem a bond from its current owner (call) at a specific price and on a specific date.

Financial Instruments Toolbox™ supports three types of put and call options on bonds:

• American option: An option that you exercise any time until its expiration date.

• European option: An option that you exercise only on its expiration date.

• Bermuda option: A Bermuda option resembles a hybrid of American and European options. You can exercise it on predetermined dates only, usually monthly.

For more information, see Bond Options.

Version History

Introduced before R2006a

R2022b: Serial date numbers not recommended

Although instoptbnd 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.