Documentation

stepcpncfamounts

Cash flow amounts and times for bonds and stepped coupons

Syntax

[CFlows,CDates,CTimes] = stepcpncfamounts(Settle,Maturity,ConvDates,CouponRates,Period,Basis,EndMonthRule,Face)

Arguments

 Settle Settlement date. A scalar or vector of serial date numbers. Settle must be earlier than Maturity. Maturity Maturity date. A scalar or vector of serial date numbers. ConvDates Matrix of serial date numbers representing conversion dates after Settle. Size = number of instruments by maximum number of conversions. Fill unspecified entries with NaN. CouponRates Matrix indicating the coupon rates for each bond in decimal form. Size = number of instruments by maximum number of conversions + 1. First column of this matrix contains rates applicable between Settle and the first conversion date (date in the first column of ConvDates). Fill unspecified entries with NaN. ConvDates has the same number of rows as CouponRates to reflect the same number of bonds. However, ConvDates has one less column than CouponRates. This situation is illustrated by Settle---------ConvDate1-----------ConvDate2------------Maturity Rate1               Rate2                 Rate3 Period (Optional) Coupons per year of the bond. A vector of integers. Allowed values are 0, 1, 2, 3, 4, 6, and 12. Default = 2. Basis (Optional) Day-count basis of the instrument. A vector of integers. 0 = actual/actual (default)1 = 30/360 (SIA)2 = actual/3603 = actual/3654 = 30/360 (BMA)5 = 30/360 (ISDA)6 = 30/360 (European)7 = actual/365 (Japanese)8 = actual/actual (ICMA)9 = actual/360 (ICMA)10 = actual/365 (ICMA)11 = 30/360E (ICMA) 12 = actual/365 (ISDA)13 = BUS/252 For more information, see Basis. EndMonthRule (Optional) End-of-month rule. A vector. This rule applies only when Maturity is an end-of-month date for a month having 30 or fewer days. 0 = ignore rule, meaning that a bond's coupon payment date is always the same numerical day of the month. 1 = set rule on (default), meaning that a bond's coupon payment date is always the last actual day of the month. Face (Optional) Face value of each bond in the portfolio. Default = 100.

Note

All arguments must be scalars or number of bonds (NUMBONDS)-by-1 vectors, except for ConvDates and CouponRates.

Description

[CFlows,CDates,CTimes] = stepcpncfamounts(Settle,Maturity,ConvDates,CouponRates,Period,Basis,EndMonthRule,Face) returns matrices of cash flow amounts, cash flow dates, and time factors for a portfolio of NUMBONDS stepped-coupon bonds.

CFlows is a matrix of cash flow amounts. The first entry in each row vector is a negative number indicating the accrued interest due at settlement. If no accrued interest is due, the first column is 0.

CDates is a matrix of cash flow dates in serial date number form. At least two columns are always present, one for settlement and one for maturity.

CTimes is a matrix of time factors for the SIA semiannual price/yield conversion.

DiscountFactor = (1 + Yield/2).^(-TFactor)

Time factors are in units of semiannual coupon periods. In computing time factors, use SIA actual/actual conventions for all time factor calculations.

Note

For bonds with fixed coupons, use cfamounts. If you use a fixed-coupon bond with stepcpncfamounts, MATLAB® software generates an error.

Examples

This example generates stepped cash flows for three different bonds, all paying interest semiannually. Their life span is about 18–19 years each:

• Bond A has two conversions, but the first one occurs on the settlement date and immediately expires.

• Bond B has three conversions, with conversion dates exactly on the coupon dates.

• Bond C has three conversions, with some conversion dates not on the coupon dates. It has the longest maturity. This case illustrates that only cash flows for full periods after conversion dates are affected, as illustrated below. The following table illustrates the interest rate characteristics of this bond portfolio.

Bond A Dates

Bond A Rates

Bond B Dates

Bond B Rates

Bond C Dates

Bond C Rates

Settle (02-Aug-92)

7.5%

Settle (02-Aug-92)

7.5%

Settle (02-Aug-92)

2.5%

First Conversion (02-Aug-92)

8.875%

First Conversion (15-Jun-97))

8.875%

First Conversion (14-Jun-97))

5.0%

Second Conversion (15-Jun-03)

9.25%

Second Conversion (15-Jun-01)

9.25%

Second Conversion (14-Jun-01)

7.5%

Maturity (15-Jun-10)

NaN

Third Conversion (15-Jun-05)

10.0%

Third Conversion (14-Jun-05)

10.0%

Maturity (15-Jun-10)

NaN

Maturity (15-Jun-11)

NaN

Settle   = datenum('02-Aug-1992');

ConvDates = [datenum('02-Aug-1992'), datenum('15-Jun-2003'),...
nan;
datenum('15-Jun-1997'), datenum('15-Jun-2001'),...
datenum('15-Jun-2005');
datenum('14-Jun-1997'), datenum('14-Jun-2001'),...
datenum('14-Jun-2005')];

Maturity = [datenum('15-Jun-2010');
datenum('15-Jun-2010');
datenum('15-Jun-2011')];

CouponRates = [0.075 0.08875 0.0925 nan;
0.075 0.08875 0.0925 0.1;
0.025 0.05    0.0750 0.1];
Basis = 1;
Period = 2;
EndMonthRule = 1;
Face = 100;

Call stepcpncfamounts to compute cash flows and timings.

[CFlows, CDates, CTimes] = stepcpncfamounts(Settle, Maturity, ...
ConvDates, CouponRates);

Visualize the third bond cash flows (2.5 - 5 - 7.5 - 10) using the cfplot function.

cfplot(CDates(3,:),CFlows(3,:));
xlabel('Dates in Serial Number Format')
ylabel('Relative Amounts of Cash Flows')
title('CashFlow of 2.5 - 5 - 7.5 - 10 Stepped Coupon Bond') 