cbondbycrr

Price convertible bonds from CRR binomial tree

collapse all in page

Syntax

Price = cbondbycrr(CRRTree,CouponRate,Settle,Maturity,ConvRatio)
[Price,PriceTree] = cbondbycrr(CRRTree,CouponRate,Settle,Maturity,ConvRatio)
[Price,PriceTree,EquityTree,DebtTree] = cbondbycrr(___,Name,Value)

Description

Price = cbondbycrr(CRRTree,CouponRate,Settle,Maturity,ConvRatio) prices convertible bonds from a CRR binomial tree using the Tsiveriotis and Fernandes method.

Note

Alternatively, you can use the ConvertibleBond instrument object to price a convertible bond. For more information, see Get Started with Workflows Using Object-Based Framework for Pricing Financial Instruments.

example

[Price,PriceTree] = cbondbycrr(CRRTree,CouponRate,Settle,Maturity,ConvRatio) prices convertible bonds from a CRR binomial tree using the Tsiveriotis and Fernandes method.

example

[Price,PriceTree,EquityTree,DebtTree] = cbondbycrr(___,Name,Value) prices convertible bonds from a CRR binomial tree using a credit spread or incorporating the risk of bond default.

To incorporate the risk in the form of credit spread (Tsiveriotis-Fernandes method), use the optional name-value pair input argument Spread. To incorporate default risk into the algorithm, specify the optional name-value pair input arguments DefaultProbability and RecoveryRate.

example

Examples

collapse all

Open Live Script

Price a convertible bond using the following data for the interest-rate term structure: 

StartDates = datetime(2014,1,1); 
EndDates = datetime(2015,1,1); 
Rates = 0.1; 
Basis = 1;

Create the RateSpec and StockSpec. 

Sigma = 0.3;
Price = 50;

RateSpec = intenvset('ValuationDate',StartDates,'StartDates',StartDates,'EndDates',EndDates,...
'Rates',Rates,'Compounding',-1,'Basis',Basis)
RateSpec = struct with fields:
           FinObj: 'RateSpec'
      Compounding: -1
             Disc: 0.9048
            Rates: 0.1000
         EndTimes: 1
       StartTimes: 0
         EndDates: 735965
       StartDates: 735600
    ValuationDate: 735600
            Basis: 1
     EndMonthRule: 1


StockSpec = stockspec(Sigma,Price)
StockSpec = struct with fields:
             FinObj: 'StockSpec'
              Sigma: 0.3000
         AssetPrice: 50
       DividendType: []
    DividendAmounts: 0
    ExDividendDates: []

Create the CRR tree for the equity. 

Settle = datetime(2014,1,1);
Maturity = datetime(2014,10,1);
NumSteps = 3; 
TimeSpec = crrtimespec(Settle,Maturity,NumSteps);
CRRT = crrtree(StockSpec,RateSpec,TimeSpec)
CRRT = struct with fields:
       FinObj: 'BinStockTree'
       Method: 'CRR'
    StockSpec: [1×1 struct]
     TimeSpec: [1×1 struct]
     RateSpec: [1×1 struct]
         tObs: [0 0.2491 0.4982 0.7473]
         dObs: [735600 735691 735782 735873]
        STree: {[50]  [58.0757 43.0472]  [67.4558 50.0000 37.0613]  [78.3509 58.0757 43.0472 31.9077]}
      UpProbs: [0.5465 0.5465 0.5465]

Define and price the convertible bond. 

CouponRate = 0;
Period = 1;
ConvRatio = 2;
CallExDates = datetime(2014,10,1);
CallStrike = 115;
AmericanCall = 1;
Spread = 0.05;

[Price,PriceTree,EqtTree,DbtTree] = cbondbycrr(CRRT,CouponRate,Settle,Maturity,ConvRatio,...
'Period',Period,'Spread',Spread,'CallExDates',CallExDates,'CallStrike',CallStrike,'AmericanCall',AmericanCall)
Price = 
104.9490

PriceTree = struct with fields:
    FinObj: 'BinPriceTree'
     PTree: {[104.9490]  [116.1515 98.0892]  [134.9117 105.6029 96.3327]  [156.7019 116.1515 100.0000 100.0000]}
      tObs: [0 0.2491 0.4982 0.7473]
      dObs: [735600 735691 735782 735873]


EqtTree = struct with fields:
    FinObj: 'BinPriceTree'
     PTree: {[76.5211]  [116.1515 33.0103]  [134.9117 61.9209 0]  [156.7019 116.1515 0 0]}
      tObs: [0 0.2491 0.4982 0.7473]
      dObs: [735600 735691 735782 735873]


DbtTree = struct with fields:
    FinObj: 'BinPriceTree'
     PTree: {[28.4278]  [0 65.0790]  [0 43.6821 96.3327]  [0 0 100.0000 100.0000]}
      tObs: [0 0.2491 0.4982 0.7473]
      dObs: [735600 735691 735782 735873]
Open Live Script

Create the interest-rate term structure RateSpec. 

StartDates = 'Jan-1-2014'; 
EndDates = 'Jan-1-2016'; 
Rates = 0.025; 
Basis = 1; 
RateSpec = intenvset('ValuationDate',StartDates,'StartDates',...
StartDates,'EndDates',EndDates,'Rates',Rates,'Compounding',-1,'Basis',Basis)
RateSpec = struct with fields:
           FinObj: 'RateSpec'
      Compounding: -1
             Disc: 0.9512
            Rates: 0.0250
         EndTimes: 2
       StartTimes: 0
         EndDates: 736330
       StartDates: 735600
    ValuationDate: 735600
            Basis: 1
     EndMonthRule: 1

Create the StockSpec. 

AssetPrice = 110; 
Sigma = 0.22; 
Div = 0.02; 
StockSpec = stockspec(Sigma,AssetPrice,'continuous',Div)
StockSpec = struct with fields:
             FinObj: 'StockSpec'
              Sigma: 0.2200
         AssetPrice: 110
       DividendType: {'continuous'}
    DividendAmounts: 0.0200
    ExDividendDates: []

Create the CRR tree for the equity. 

Settle = '1-Jan-2014';
Maturity = '1-Oct-2014';
NumSteps = 3;
TimeSpec = crrtimespec(Settle,Maturity,NumSteps);
CRRT = crrtree(StockSpec,RateSpec,TimeSpec)
CRRT = struct with fields:
       FinObj: 'BinStockTree'
       Method: 'CRR'
    StockSpec: [1×1 struct]
     TimeSpec: [1×1 struct]
     RateSpec: [1×1 struct]
         tObs: [0 0.2491 0.4982 0.7473]
         dObs: [735600 735691 735782 735873]
        STree: {[110]  [122.7658 98.5616]  [137.0132 110.0000 88.3127]  [152.9140 122.7658 98.5616 79.1295]}
      UpProbs: [0.4782 0.4782 0.4782]

Define and price the convertible bond using the optional DefaultProbability and RecoveryRate arguments. 

CouponRate = 0;
Period = 1;
ConvRatio = 2;
CallExDates = '1-Oct-2014';
CallStrike = 115;
AmericanCall = 1;
DefaultProbability = .30;
RecoveryRate = .82;

[Price,PriceTree,EqtTree,DbtTree] = cbondbycrr(CRRT,CouponRate,Settle,Maturity,ConvRatio,...
'Period',Period,'CallExDates',CallExDates,'CallStrike',CallStrike,'AmericanCall',AmericanCall,...
'DefaultProbability',DefaultProbability,'RecoveryRate',RecoveryRate)
Price = 
220

PriceTree = struct with fields:
    FinObj: 'BinPriceTree'
     PTree: {[220]  [245.5317 197.1233]  [274.0263 220.0000 176.6254]  [305.8279 245.5317 197.1233 158.2589]}
      tObs: [0 0.2491 0.4982 0.7473]
      dObs: [735600 735691 735782 735873]


EqtTree = struct with fields:
    FinObj: 'BinPriceTree'
     PTree: {[220]  [245.5317 197.1233]  [274.0263 220.0000 176.6254]  [305.8279 245.5317 197.1233 158.2589]}
      tObs: [0 0.2491 0.4982 0.7473]
      dObs: [735600 735691 735782 735873]


DbtTree = struct with fields:
    FinObj: 'BinPriceTree'
     PTree: {[0]  [0 0]  [0 0 0]  [0 0 0 0]}
      tObs: [0 0.2491 0.4982 0.7473]
      dObs: [735600 735691 735782 735873]

Input Arguments

collapse all

Stock tree structure, specified by using crrtree.

Data Types: struct

Bond coupon rate, specified as an NINST-by-1 decimal annual rate or 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

Settlement date, specified as an NINST-by-1 vector using a datetime array, string array, or date character vectors.

Note

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

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

Maturity date, specified as an NINST-by-1 vector using a datetime array, string array, or date character vectors.

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

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

Data Types: double

Name-Value Arguments

collapse all

Specify 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: [Price,PriceTree,EquityTree,DebtTree] = cbondbycrr(CRRT,CouponRate,Settle, Maturity, ConvRatio,'Spread',Spread,'CallExDates',CallExDates,'CallStrike',CallStrike,'AmericanCall',1)

Number of basis points over the reference rate, specified as the comma-separated pair consisting of 'Spread' and a NINST-by-1 vector. For example, if the reference rate is 2% and spread is 4%, then the Spread value in basis points would be 0.04.

Note

To incorporate the risk in the form of credit spread (Tsiveriotis-Fernandes method), use the optional input argument Spread. To incorporate default risk into the algorithm, specify the optional input arguments DefaultProbability and RecoveryRate. Do not use Spread with DefaultProbability and RecoveryRate.

Data Types: double

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

Data Types: double

Bond issue date, specified as the comma-separated pair consisting of 'IssueDate' and a NINST-by-1 vector using a datetime array, string array, or date character vectors.

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

Irregular first coupon date, specified as the comma-separated pair consisting of 'FirstCouponDate' and a NINST-by-1 vector using a datetime array, string array, or date character vectors.

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

Irregular last coupon date, specified as the comma-separated pair consisting of 'LastCouponDate' and a NINST-by-1 vector using a datetime array, string array, or date character vectors.

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

Face value, specified as the comma-separated pair consisting of 'Face' and a NINST-by-1 vector of nonnegative face values or a 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

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 call 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 option.

Data Types: single | double

Call exercise date for European, Bermuda, or American option, specified as the comma-separated pair consisting of 'CallExDates' and a datetime array, string array, or date character vectors for the following values:

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

  • For a Bermuda option — NINST-by-NSTRIKES matrix of exercise dates, where each row is the schedule for one 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 option can be exercised between the ValuationDate of the CRR stock tree and the single listed CallExDate.

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

Call option type, specified as the comma-separated pair consisting of 'AmericanCall' and a NINST-by-1 vector of positive integer 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

Put strike values for 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 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 option.

Data Types: single | double

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

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

  • For a Bermuda option — NINST-by-NSTRIKES matrix of exercise dates where each row is the schedule for one 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 CRR stock tree and the single listed PutExDate.

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

Put option type, specified as the comma-separated pair consisting of 'AmericanPut' and a NINST-by-1 vector of positive integer 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: double

Convertible dates, specified as the comma-separated pair consisting of 'ConvDates' and a NINST-by-1 or NINST-by-2 vector using a datetime array, string array, or date character vectors. If ConvDates is not specified, the bond is always convertible until maturity.

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

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 CRR stock tree and the single listed ConvDates.

Annual probability of default rate, specified as the comma-separated pair consisting of 'DefaultProbability' and a NINST-by-1 nonnegative decimal value.

Note

To incorporate default risk into the algorithm, specify the optional input arguments DefaultProbability and RecoveryRate. To incorporate the risk in the form of credit spread (Tsiveriotis-Fernandes method), use the optional input argument Spread. Do not use DefaultProbability and RecoveryRate with Spread.

Data Types: double

Recovery rate, specified as the comma-separated pair consisting of 'RecoveryRate' and a NINST-by-1 nonnegative decimal.

Note

To incorporate default risk into the algorithm, specify the optional input arguments DefaultProbability and RecoveryRate. To incorporate the risk in the form of credit spread (Tsiveriotis-Fernandes method), use the optional input argument Spread. Do not use DefaultProbability and RecoveryRate with Spread.

Data Types: double

Output Arguments

collapse all

Expected price at time 0, returned as an NINST-by-1 array.

Structure with a vector of convertible bond prices at each node, returned as a tree structure.

Structure with a vector of convertible bond equity component at each node, returned as a tree structure.

Structure with a vector of convertible bond debt component at each node, returned as a tree structure.

More About

collapse all

Algorithms

cbondbycrr, cbondbyeqp, cbondbyitt, and cbondbystt return price information in the form of a price vector and a price tree. These functions implement the risk in the form of either a credit spread or incorporating the risk of bond default. To incorporate the risk in the form of credit spread (Tsiveriotis-Fernandes method), use the optional name-value pair argument Spread. To incorporate default risk into the algorithm, specify the optional name-value pair arguments DefaultProbability and RecoveryRate.

References

[1] Tsiveriotis, K., and C. Fernandes. “Valuing Convertible Bonds with Credit Risk.” Journal of Fixed Income. Vol. 8, 1998, pp. 95–102.

[2] Hull, J. Options, Futures and Other Derivatives. Fourth Edition. Prentice Hall, 2000, pp. 646–649.

Version History

Introduced in R2015a

expand all

See Also

| | | | | | | | |

Topics