Fixed-Income Toolbox™

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 or equal to `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`. See Note below.
`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/360 3 = actual/365 4 = 30/360 (PSA) 5 = 30/360 (ISDA) 6 = 30/360 (European) 7 = actual/365 (Japanese) 8 = actual/actual (ISMA) 9 = actual/360 (ISMA) 10 = actual/365 (ISMA) 11 = 30/360E (ISMA) 12 = actual/365 (ISDA)
`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.

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

Note 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

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 to 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).

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')

stepcpncfamounts - Cash flow amounts and times for bonds and stepped coupons

Syntax

Arguments

Description

Examples

See Also