instcbond

Construct CBond instrument for convertible bond

Syntax

ISet = instcbond(CouponRate,Settle,Maturity,ConvRatio)

ISet = instcbond(___,Name,Value)

ISet = instcbond(ISet,CouponRate,Settle,Maturity,ConvRatio)

ISet = instcbond(___,Name,Value)

[FieldList,ClassList,TypeString] = instcbond

Description

ISet = instcbond(CouponRate,Settle,Maturity,ConvRatio) creates a CBond instrument variable from data arrays.

ISet = instcbond(___,Name,Value) creates a CBond instrument variable from data arrays using optional name-value pair arguments.

ISet = instcbond(ISet,CouponRate,Settle,Maturity,ConvRatio) adds a CBond to an existing instrument set.

ISet = instcbond(___,Name,Value) adds a CBond instrument to an existing instrument set using optional name-value pair arguments.

[FieldList,ClassList,TypeString] = instcbond lists the field metadata for the CBond instrument.

Examples

Create a CBond Instrument

Create a CBond instrument.

CouponRate = 0.03;
Settle = 'Jan-1-2014';
Maturity = 'Jan-1-2016'; 
CallStrike = 125; 
CallExDates = [datenum('Jan-1-2015') datenum('Jan-1-2016')];

ConvRatio = 1.5;
Spread = 0.045;
 
InstSet = instcbond(CouponRate,Settle,Maturity,ConvRatio,...
'Spread',Spread,'CallExDates',CallExDates,'CallStrike',CallStrike,...
'AmericanCall', 1);

Display the InstSet for the convertible bond.

instdisp(InstSet)

Index Type  CouponRate Settle         Maturity       ConvRatio Period IssueDate FirstCouponDate LastCouponDate StartDate Face Spread CallStrike CallExDates                  AmericanCall PutStrike PutExDates AmericanPut ConvDates      DefaultProbability RecoveryRate
1     CBond 0.03       01-Jan-2014    01-Jan-2016    1.5       2      NaN       NaN             NaN            NaN       100  0.045  125        01-Jan-2015   01-Jan-2016    1            NaN       NaN        0           01-Jan-2016    NaN                NaN         
 

Add a CBond Instrument to an Existing Portfolio Set

Create a bond instrument using instbond.

CouponRate= [0.035;0.04];
Settle= 'Nov-1-2013';
Maturity = 'Nov-1-2014';
Period =1;

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

Add a CBond instrument to the existing portfolio set.

ConvRatio = 1.5;
InstSet = instadd(InstSet,'CBond',CouponRate,Settle,Maturity,ConvRatio);
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  CouponRate Settle         Maturity       ConvRatio Period IssueDate FirstCouponDate LastCouponDate StartDate Face Spread CallStrike CallExDates AmericanCall PutStrike PutExDates AmericanPut ConvDates      DefaultProbability RecoveryRate
3     CBond 0.035      01-Nov-2013    01-Nov-2014    1.5       2      NaN       NaN             NaN            NaN       100  NaN    NaN        NaN         0            NaN       NaN        0           01-Nov-2014    NaN                NaN         
4     CBond 0.04       01-Nov-2013    01-Nov-2014    1.5       2      NaN       NaN             NaN            NaN       100  NaN    NaN        NaN         0            NaN       NaN        0           01-Nov-2014    NaN                NaN         
 

[FieldList,ClassList,TypeString] = instcbond

FieldList = 20x1 cell
    {'CouponRate'        }
    {'Settle'            }
    {'Maturity'          }
    {'ConvRatio'         }
    {'Period'            }
    {'IssueDate'         }
    {'FirstCouponDate'   }
    {'LastCouponDate'    }
    {'StartDate'         }
    {'Face'              }
    {'Spread'            }
    {'CallStrike'        }
    {'CallExDates'       }
    {'AmericanCall'      }
    {'PutStrike'         }
    {'PutExDates'        }
    {'AmericanPut'       }
    {'ConvDates'         }
    {'DefaultProbability'}
    {'RecoveryRate'      }

ClassList = 20x1 cell
    {'cell'}
    {'date'}
    {'date'}
    {'dble'}
    {'dble'}
    {'date'}
    {'date'}
    {'date'}
    {'date'}
    {'cell'}
    {'dble'}
    {'dble'}
    {'date'}
    {'dble'}
    {'dble'}
    {'date'}
    {'dble'}
    {'date'}
    {'dble'}
    {'dble'}

TypeString = 
'CBond'

Input Arguments

CouponRate — Bond coupon rate

positive decimal value

Bond coupon rate, specified as an NINST-by-1 positive decimal annual rate or an NINST-by-1 cell array, where each element is a NumDates-by-2 cell array. The first column of the NumDates-by-2 cell array is dates and the second column is associated rates. The date indicates the last day that the coupon rate is valid.

Data Types: double | cell

Settle — Settlement date

scalar for serial nonnegative date number | scalar for date character vector

Settlement date, specified as an NINST-by-1 scalar using a serial nonnegative date number or date character vector.

Note

The Settle date for every convertible bond is set to the ValuationDate of the stock tree. The bond argument, Settle, is ignored.

Data Types: double | char

Maturity — Maturity date

scalar for serial nonnegative date number | scalar for date character vector

Maturity date, specified as an NINST-by-1 scalar using a serial nonnegative date number or date character vector.

Data Types: double | char

ConvRatio — Number of shares convertible to one bond

nonnegative scalar

Number of shares convertible to one bond, specified as an NINST-by-1 nonnegative scalar.

Data Types: double

ISet — Variable containing a collection of instruments

structure

Variable containing a collection of instruments, specified as a structure. Use thus argument to add a CBond (convertible bond) to an existing instrument set (ISet). Instruments within ISet are broken down by type, and each type can have different data fields. For more information on theISet variable, see instget.

Data Types: struct

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: InstSet = instcbond(CouponRate,Settle,Maturity,ConvRatio,'Spread',Spread,'CallExDates',CallExDates,'CallStrike',CallStrike,'AmericanCall', 1)

'Period' — Coupons per year

2 per year (default) | vector

Coupons per year, specified as the comma-separated pair consisting of 'Period' and a NINST-by-1 vector.

Data Types: double

'IssueDate' — Bond issue date

scalar for serial date number | scalar for date character vector

Bond issue date, specified as the comma-separated pair consisting of 'IssueDate' and a NINST-by-1 scalar using a serial date number or date character vector.

Data Types: double | char

'FirstCouponDate' — Irregular first coupon date

scalar for serial date number | scalar for date character vector

Irregular first coupon date, specified as the comma-separated pair consisting of 'FirstCouponDate' and a NINST-by-1 scalar using a serial date number or date character vector.

Data Types: double | char

'LastCouponDate' — Irregular last coupon date

scalar for serial date number | scalar for date character vector

Irregular last coupon date, specified as the comma-separated pair consisting of 'LastCouponDate' and a NINST-by-1 scalar using a serial date number or date character vector.

Data Types: double | char

'Face' — Face value

100 (default) | scalar of nonnegative value | cell array of nonnegative values

Face value, specified as the comma-separated pair consisting of 'Face' and a NINST-by-1 scalar of nonnegative face values or an NINST-by-1 cell array, where each element is a NumDates-by-2 cell array. The first column of the NumDates-by-2 cell array is dates and the second column is the associated face value. The date indicates the last day that the face value is valid.

Data Types: cell | double

'Spread' — Number of basis points over the reference rate

0 (default) | vector

Number of basis points over the reference rate, specified as the comma-separated pair consisting of 'Spread' and a NINST-by-1 vector.

Data Types: double

'CallStrike' — Call strike price for European, Bermuda, or American option

nonnegative integer | vector of nonnegative integers

Call strike price for European, Bermuda, or American option, specified as the comma-separated pair consisting of 'CallStrike' and one of the following values:

• For a European call option — NINST-by-1 vector of nonnegative integers

• For a Bermuda call option — NINST-by-NSTRIKES matrix of strike price values, where each row is the schedule for one call option. If a call option has fewer than NSTRIKES exercise opportunities, the end of the row is padded with NaNs.

• For an American call option — NINST-by-1 vector of strike price values for each call option.

Data Types: single | double

'CallExDates' — Call exercise date for European, Bermuda, or American option

serial date number | vector of serial date numbers | date character vector | cell array of date character vectors

Call exercise date for European, Bermuda, or American option, specified as the comma-separated pair consisting of 'CallExDates' and one of the following values:

• For a European option — NINST-by-1 vector of serial date numbers or date character vectors.

• For a Bermuda option — NINST-by-NSTRIKES matrix of exercise dates, where each row is the schedule for one call option. For a European option, there is only one CallExDate on the option expiry date.

• For an American option — NINST-by-1 or NINST-by-2 matrix of exercise date boundaries. For each instrument, the call option can be exercised on any tree date between or including the pair of dates on that row. If CallExDates is NINST-by-1, the call option can be exercised between the ValuationDate of the stock tree and the single listed CallExDate.

Data Types: double | char | cell

'AmericanCall' — Call option type indicator

0 if AmericanCall is NaN or not entered (default) | scalar | vector of positive integers[0,1]

Call option type, specified as the comma-separated pair consisting of 'AmericanCall' and a NINST-by-1 positive integer scalar flags with values 0 or 1.

• For a European or Bermuda option — AmericanCall is 0 for each European or Bermuda option.

• For an American option — AmericanCall is 1 for each American option. The AmericanCall argument is required to invoke American exercise rules.

Data Types: single | double

'PutStrike' — Put strike values for European, Bermuda, or American option

scalar | vector of positive integers[0,1]

Put strike values for a European, Bermuda, or American option, specified as the comma-separated pair consisting of 'PutStrike' and one of the following values:

• For a European put option — NINST-by-1 vector of nonnegative integers

• For a Bermuda put option — NINST-by-NSTRIKES matrix of strike price values, where each row is the schedule for one put option. If a put option has fewer than NSTRIKES exercise opportunities, the end of the row is padded with NaNs.

• For an American put option — NINST-by-1 vector of strike price values for each put option.

Data Types: single | double

'PutExDates' — Put exercise date for European, Bermuda, or American option

serial date number | vector of serial date numbers | date character vector | cell array of date character vectors

Put exercise date for a European, Bermuda, or American option, specified as the comma-separated pair consisting of 'PutExDates' and one of the following values:

• For a European option — NINST-by-1 vector serial date numbers or date character vectors.

• For a Bermuda option — NINST-by-NSTRIKES matrix of exercise dates, where each row is the schedule for one put option. For a European option, there is only one PutExDate on the option expiry date.

• For an American option — NINST-by-1 or NINST-by-2 matrix of exercise date boundaries. For each instrument, the put option can be exercised on any tree date between or including the pair of dates on that row. If PutExDates is NINST-by-1, the put option can be exercised between the ValuationDate of the stock tree and the single listed PutExDate.

Data Types: double | char | cell

'AmericanPut' — Put option type indicator

0 if AmericanPut is NaN or not entered (default) | scalar | vector of positive integers[0,1]

Put option type, specified as the comma-separated pair consisting of 'AmericanPut' and a NINST-by-1 positive integer scalar flags with values 0 or 1.

• For a European or Bermuda option — AmericanPut is 0 for each European or Bermuda option.

• For an American option — AmericanPut is 1 for each American option. The AmericanPut argument is required to invoke American exercise rules.

Data Types: single | double

'ConvDates' — Convertible dates

MaturityDate (default) | scalar for serial date number | scalar for date character vector

Convertible dates, specified as the comma-separated pair consisting of 'ConvDates' and a NINST-by-1 or NINST-by-2 matrix of serial nonnegative date numbers or date character vectors. If ConvDates is not specified, the bond is always convertible until maturity.

For each instrument, the bond can be converted on any tree date between or including the pair of dates on that row.

If ConvDates is NINST-by-1, the bond can be converted between the ValuationDate of the stock tree and the single listed ConvDates.

Data Types: single | double | char

Output Arguments

ISet — Variable containing a collection of instruments

character vector | row vector

Variable containing a collection of instruments, returned as a row vector or character vector for each instrument. Instruments are broken down by type and each type can have different data fields. For more information on theISet variable, see instget.

FieldList — Name of each data field for instrument type

cell array of character vectors

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

ClassList — Data class of each field

cell array of character vectors with valid values of 'dble', 'date', and 'char'

Data class of each field, returned as an NFIELDS-by-1 cell array of character vectors with valid character vector values of 'dble', 'date', and 'char'.

TypeString — Type of instrument added

character vector

Type of instrument added, returned as character vector. When adding a CBond, the TypeString = 'CBond'.