MathWorks Machine Translation
The automated translation of this page is provided by a general purpose third party translator tool.
MathWorks does not warrant, and disclaims all liability for, the accuracy, suitability, or fitness for purpose of the translation.
Cash flow and time mapping for bond portfolio
In R2017b, the specification of optional input arguments has changed. While the
previous ordered inputs syntax is still supported, it may no longer be supported in
a future release. Use the optional namevalue pair inputs:
Period
, Basis
,
EndMonthRule
,
IssueDate
,FirstCouponDate
,
LastCouponDate
,
StartDate
,Face
,
AdjustCashFlowsBasis
,
BusinessDayConvention
,
CompoundingFrequency
, DiscountBasis
,
Holidays
, and PrincipalType
.
[CFlowAmounts,CFlowDates,TFactors,CFlowFlags,CFPrincipal] = cfamounts(CouponRate,Settle,Maturity)
[CFlowAmounts,CFlowDates,TFactors,CFlowFlags,CFPrincipal] = cfamounts(___,Name,Value)
[
returns matrices of cash flow amounts, cash flow dates, time factors, and cash
flow flags for a portfolio of CFlowAmounts
,CFlowDates
,TFactors
,CFlowFlags
,CFPrincipal
] = cfamounts(CouponRate
,Settle
,Maturity
)NUMBONDS
fixedincome
securities.
The elements contained in the cfamounts
outputs for the
cash flow matrix, time factor matrix, and cash flow flag matrix correspond to
the cash flow dates for each security. The first element of each row in the cash
flow matrix is the accrued interest payable on each bond. This accrued interest
is zero in the case of all zero coupon bonds. cfamounts
determines all cash flows and time mappings for a bond whether or not the coupon
structure contains odd first or last periods. All output matrices are padded
with NaN
s as necessary to ensure that all rows have the same
number of elements.
[
adds optional namevalue arguments. CFlowAmounts
,CFlowDates
,TFactors
,CFlowFlags
,CFPrincipal
] = cfamounts(___,Name,Value
)
This example shows how to compute the cash flow structure and time factors for a bond portfolio that contains a corporate bond paying interest quarterly and a Treasury bond paying interest semiannually.
Settle = '01Nov1993'; Maturity = ['15Dec1994';'15Jun1995']; CouponRate= [0.06; 0.05]; Period = [4; 2]; Basis = [1; 0]; [CFlowAmounts, CFlowDates, TFactors, CFlowFlags] = ... cfamounts(CouponRate,Settle, Maturity, Period, Basis)
CFlowAmounts =
0.7667 1.5000 1.5000 1.5000 1.5000 101.5000
1.8989 2.5000 2.5000 2.5000 102.5000 NaN
CFlowDates =
728234 728278 728368 728460 728552 728643
728234 728278 728460 728643 728825 NaN
TFactors =
0 0.2404 0.7403 1.2404 1.7403 2.2404
0 0.2404 1.2404 2.2404 3.2404 NaN
CFlowFlags =
0 3 3 3 3 4
0 3 3 3 4 NaN
CFlowDates
This example shows how to compute the cash flow structure and time factors for a bond portfolio that contains a corporate bond paying interest quarterly and a Treasury bond paying interest semiannually and CFlowDates
is returned as a datatime array.
Settle = datetime('01Nov1993','Locale','en_US'); Maturity = ['15Dec1994';'15Jun1995']; CouponRate= [0.06; 0.05]; Period = [4; 2]; Basis = [1; 0]; [CFlowAmounts, CFlowDates, TFactors, CFlowFlags] = cfamounts(CouponRate,... Settle, Maturity, Period, Basis)
CFlowAmounts =
0.7667 1.5000 1.5000 1.5000 1.5000 101.5000
1.8989 2.5000 2.5000 2.5000 102.5000 NaN
CFlowDates = 2x6 datetime array
Columns 1 through 5
01Nov1993 15Dec1993 15Mar1994 15Jun1994 15Sep1994
01Nov1993 15Dec1993 15Jun1994 15Dec1994 15Jun1995
Column 6
15Dec1994
NaT
TFactors =
0 0.2404 0.7403 1.2404 1.7403 2.2404
0 0.2404 1.2404 2.2404 3.2404 NaN
CFlowFlags =
0 3 3 3 3 4
0 3 3 3 4 NaN
This example shows how to compute the cash flow structure and time factors for a bond portfolio that contains a corporate bond paying interest quarterly and a Treasury bond paying interest semiannually. This example uses the following NameValue pairs for Period
, Basis
, BusinessDayConvention
, and AdjustCashFlowsBasis
.
Settle = '01Jun2010'; Maturity = ['15Dec2011';'15Jun2012']; CouponRate= [0.06; 0.05]; Period = [4; 2]; Basis = [1; 0]; [CFlowAmounts, CFlowDates, TFactors, CFlowFlags] = ... cfamounts(CouponRate,Settle, Maturity, 'Period',Period, ... 'Basis', Basis, 'AdjustCashFlowsBasis', true,... 'BusinessDayConvention','modifiedfollow')
CFlowAmounts =
Columns 1 through 7
1.2667 1.5000 1.5000 1.5000 1.5000 1.5000 1.5000
2.3077 2.4932 2.5068 2.4932 2.5000 102.5000 NaN
Column 8
101.5000
NaN
CFlowDates =
Columns 1 through 6
734290 734304 734396 734487 734577 734669
734290 734304 734487 734669 734852 735035
Columns 7 through 8
734761 734852
NaN NaN
TFactors =
Columns 1 through 7
0 0.0778 0.5778 1.0778 1.5778 2.0778 2.5778
0 0.0769 1.0769 2.0769 3.0769 4.0769 NaN
Column 8
3.0778
NaN
CFlowFlags =
0 3 3 3 3 3 3 4
0 3 3 3 3 4 NaN NaN
cfamounts
With a CouponRate
ScheduleThis example shows how to use cfamounts
with a CouponRate
schedule. For CouponRate
and Face
that change over the life of the bond, schedules for CouponRate
and Face
can be specified with an NINST
by1 cell array, where each element is a NumDates
by2 matrix where the first column is dates and the second column is associated rates.
CouponSchedule = {[datenum('15Mar2012') .04;datenum('15 Mar 2013') .05;... datenum('15 Mar 2015') .06]}
CouponSchedule = 1x1 cell array
{3x2 double}
cfamounts(CouponSchedule,'01Mar2011','15Mar2015' )
ans =
Columns 1 through 7
1.8453 2.0000 2.0000 2.0000 2.5000 2.5000 3.0000
Columns 8 through 10
3.0000 3.0000 103.0000
cfamounts
With a Face
ScheduleThis example shows how to use cfamounts
with a Face
schedule. For CouponRate
and Face
that change over the life of the bond, schedules for CouponRate
and Face
can be specified with an NINST
by1 cell array, where each element is a NumDates
by2 matrix where the first column is dates and the second column is associated rates.
FaceSchedule = {[datenum('15Mar2012') 100;datenum('15 Mar 2013') 90;... datenum('15 Mar 2015') 80]}
FaceSchedule = 1x1 cell array
{3x2 double}
cfamounts(.05,'01Mar2011','15Mar2015', 'Face', FaceSchedule)
ans =
Columns 1 through 7
2.3066 2.5000 2.5000 12.5000 2.2500 12.2500 2.0000
Columns 8 through 10
2.0000 2.0000 82.0000
cfamounts
to Generate the Cash Flows for a Sinking BondThis example shows how to use cfamounts
to generate the cash flows for a sinking bond.
[CFlowAmounts,CFDates,TFactors,CFFlags,CFPrincipal] = cfamounts(.05,'04Nov2010',... {'15Jul2014';'15Jul2015'},'Face',{[datenum('15Jul2013') 100;datenum('15Jul2014')... 90;datenum('15Jul2015') 80]})
CFlowAmounts =
Columns 1 through 7
1.5217 2.5000 2.5000 2.5000 2.5000 2.5000 12.5000
1.5217 2.5000 2.5000 2.5000 2.5000 2.5000 12.5000
Columns 8 through 11
2.2500 92.2500 NaN NaN
2.2500 12.2500 2.0000 82.0000
CFDates =
Columns 1 through 6
734446 734518 734699 734883 735065 735249
734446 734518 734699 734883 735065 735249
Columns 7 through 11
735430 735614 735795 NaN NaN
735430 735614 735795 735979 736160
TFactors =
Columns 1 through 7
0 0.3913 1.3913 2.3913 3.3913 4.3913 5.3913
0 0.3913 1.3913 2.3913 3.3913 4.3913 5.3913
Columns 8 through 11
6.3913 7.3913 NaN NaN
6.3913 7.3913 8.3913 9.3913
CFFlags =
0 3 3 3 3 3 13 3 4 NaN NaN
0 3 3 3 3 3 13 3 13 3 4
CFPrincipal =
0 0 0 0 0 0 10 0 90 NaN NaN
0 0 0 0 0 0 10 0 10 0 80
CouponRate
— Annual percentage rate used to determine coupons payable on a bondAnnual percentage rate used to determine the coupons payable on a
bond, specified as decimal using a scalar or a
NBONDS
by1
vector.
CouponRate
is 0
for zero coupon
bonds.
CouponRate
and Face
can
change over the life of the bond. Schedules for
CouponRate
and Face
can
be specified with an
NBONDS
by1
cell array,
where each element is a
NumDates
by2
matrix or
cell array, where the first column is dates (serial date numbers or
character vectors) and the second column is associated rates. The
date indicates the last day that the coupon rate or face value is
valid.
Data Types: double
 cell
 char
Settle
— Settlement date of bondSettlement date of the bond, specified as a scalar or a
NBONDS
by1
vector using
serial date numbers, date character vectors, or datetime arrays. The
Settle
date must be before the
Maturity
date.
Data Types: double
 char
 datetime
Maturity
— Maturity date of bondMaturity date of the bond, specified as a scalar or a
NBONDS
by1
vector using
serial date numbers, date character vectors, or datetime arrays.
Data Types: double
 char
 datetime
Specify optional
commaseparated pairs of Name,Value
arguments. Name
is
the argument name and Value
is the corresponding value.
Name
must appear inside single quotes (' '
). You can
specify several name and value pair arguments in any order as
Name1,Value1,...,NameN,ValueN
.
[CFlowAmounts, CFlowDates, TFactors, CFlowFlags] = ...
cfamounts(CouponRate,Settle,
Maturity,'Period',4,'Basis',3,'AdjustCashFlowsBasis',true,'BusinessDayConvention','modifiedfollow')
'Period'
— Number of coupon payments per year for bond2
(default)  numeric with values 0
, 1
,
2
, 3
,
4
, 6
or
12
Number of coupon payments per year for the bond, specified as
scalar or a NBONDS
by1
vector
using the values: 0
, 1
,
2
, 3
,
4
, 6
, or
12
.
Data Types: double
'Basis'
— Daycount basis of bond0
(default)  numeric values: 0
,1
,
2
, 3
,
4
, 6
, 7
,
8
, 9
,
10
, 11
,
12
, 13
Daycount basis of the bond, specified as scalar or a
NBONDS
by1
vector using a
supported value:
0 = actual/actual
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 (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.
Data Types: double
'EndMonthRule'
— Endofmonth rule flag1
(in effect) (default)  nonnegative integer 0
or
1
Endofmonth rule flag, specified as a scalar or a
NBONDS
by1
vector. This
rule applies only when Maturity
is an
endofmonth date for a month having 30 or fewer days.
0
= Ignore rule, meaning that a
bond coupon payment date is always the same numerical
day of the month.
1
= Set rule on, meaning that a
bond coupon payment date is always the last actual day
of the month.
Data Types: logical
'IssueDate'
— Bond issue dateBond issue date (the date the bond begins to accrue interest),
specified as a scalar or a
NBONDS
by1
vector using
serial date numbers, date character vectors, or datetime arrays. The
IssueDate
cannot be after the
Settle
date.
If you do not specify an IssueDate
, the cash
flow payment dates are determined from other inputs.
Data Types: double
 char
 datetime
'FirstCouponDate'
— Irregular or normal first coupon dateIrregular or normal first coupon date, specified as a scalar or a
NBONDS
by1
vector using
serial date numbers, date character vectors, or datetime arrays.
If you do not specify a FirstCouponDate
, the
cash flow payment dates are determined from other inputs.
Data Types: double
 char
 datetime
'LastCouponDate'
— Irregular or normal last coupon dateIrregular or normal last coupon date, specified as a scalar or a
NBONDS
by1
vector using
serial date numbers, date character vectors, or datetime arrays.
If you do not specify a LastCouponDate
, the
cash flow payment dates are determined from other inputs.
Data Types: double
 char
 datetime
'StartDate'
— Forward starting date of coupon paymentsForward starting date of coupon payments after the
Settle
date, specified as a scalar or a
NBONDS
by1
vector using
serial date numbers, date character vectors, or datetime arrays.
To make an instrument forward starting, specify
StartDate
as a future date.
If you do not specify a StartDate
, the
effective start date is the Settle
date.
Data Types: double
 char
 datetime
'Face'
— Face value of bond100
(default)  numericFace value of the bond, specified as a scalar or a
NBONDS
by1
vector.
CouponRate
and Face
can change over the life of the bond. Schedules for
CouponRate
and Face
can be specified with an
NBONDS
by1
cell array
where each element is a
NumDates
by2
matrix
or cell array, where the first column is dates (serial date
numbers or character vectors) and the second column is
associated rates. The date indicates the last day that the
coupon rate or face value is valid.
Data Types: double
 cell
 char
'AdjustCashFlowsBasis'
— Adjusts cash flows according to accrual amount based on actual period day count0
(false) (default)  nonnegative integer 0
or
1
Adjusts cash flows according to the accrual amount based on the
actual period day count, specified as a scalar or a
NBONDS
by1
vector.
Data Types: logical
'BusinessDayConvention'
— Business day conventions'actual'
(default)  character vector with values'actual'
,
'follow'
,
'modifiedfollow'
, 'previous'
or
'modifiedprevious'
Business day conventions, specified as a scalar or
NBONDS
by1
cell array of
character vectors of business day conventions to be used in
computing payment dates. The selection for business day convention
determines how nonbusiness days are treated. Nonbusiness days are
defined as weekends plus any other date that businesses are not open
(for example, statutory holidays). Values are:
'actual'
— Nonbusiness days
are effectively ignored. Cash flows that fall on
nonbusiness days are assumed to be distributed on the
actual date.
'follow'
— Cash flows that
fall on a nonbusiness day are assumed to be distributed
on the following business day.
'modifiedfollow'
— Cash
flows that fall on a nonbusiness day are assumed to be
distributed on the following business day. However if
the following business day is in a different month, the
previous business day is adopted instead.
'previous'
— Cash flows that
fall on a nonbusiness day are assumed to be distributed
on the previous business day.
'modifiedprevious'
— Cash
flows that fall on a nonbusiness day are assumed to be
distributed on the previous business day. However if the
previous business day is in a different month, the
following business day is adopted instead.
Data Types: char
 cell
'CompoundingFrequency'
— Compounding frequency for yield calculation2
, ICMA uses
1
(default)  integer with value of 1
, 2
,
3
, 4
,
6
, or 12
Compounding frequency for yield calculation, specified as a scalar
or a NBONDS
by1
vector.
Values are:
1
— Annual
compounding
2
— Semiannual compounding
3
— Compounding three times
per year
4
— Quarterly
compounding
6
— Bimonthly
compounding
12
— Monthly
compounding
By default, SIA bases
(0
7
) and
BUS/252
use a semiannual compounding
convention and ICMA bases
(8
12
) use an
annual compounding convention.
Data Types: double
'DiscountBasis'
— Basis used to compute the discount factors for computing the yield0
(default)  integers of the set [0...13]
 vector of integers of the set [0...13]
Basis used to compute the discount factors for computing the
yield, specified as a scalar or a
NBONDS
by1
vector. Values
are:
0 = actual/actual
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 (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.
If a SIA daycount basis is defined in the
Basis
input argument and there is
no value assigned for DiscountBasis
, the
default behavior is for SIA bases to use the
actual/actual
day count to compute
discount factors.
If an ICMA daycount basis or BUS/252 is defined in the
Basis
input argument and there is
no value assigned for DiscountBasis
, the
specified bases from the Basis
input
argument are used.
Data Types: double
'Holidays'
— Dates for holidaysholidays.m
used (default)Dates for holidays, specified as
NHOLIDAYS
by1
vector of
MATLAB^{®} dates using serial date numbers, date character
vectors, or datetime arrays. Holidays are used in computing business
days.
Data Types: double
 char
 datetime
'PrincipalType'
— Type of principal when a Face
schedule is specifiedsinking
(default)  character vector with values 'sinking'
or
'bullet'
Type of principal when a Face
schedule is
specified. PrincipalType
is specified as
'sinking'
or 'bullet'
using a scalar or a
NBONDS
by1
vector.
If 'sinking'
, principal cash flows are returned
throughout the life of the bond.
If 'bullet'
, principal cash flow is only
returned at maturity.
Data Types: char
 cell
CFlowAmounts
— Cash flow amountsCash flow amounts, returned as a
NBONDS
byNCFS
(number of cash
flows) matrix. The first entry in each row vector is the accrued
interest due at settlement. This amount could be zero, positive or
negative. If no accrued interest is due, the first column is zero. If
the bond is trading excoupon then the accrued interest is
negative.
CFlowDates
— Cash flow dates for a portfolio of bondsCash flow dates for a portfolio of bonds, returned as a
NBONDS
byNCFS
matrix. Each
row represents a single bond in the portfolio. Each element in a column
represents a cash flow date of that bond.
If all the above inputs (Settle
,
Maturity
, IssueDate
,
FirstCouponDate
,
LastCouponDate
, and
StartDate
) are either serial date numbers or
date character vectors, then CFlowDates
is returned
as a serial date number. If any of these inputs are datetime arrays,
then CFlowDates
is returned as a datetime
array.
TFactors
— Matrix of time factors for a portfolio of bondsMatrix of time factors for a portfolio of bonds, returned as a
NBONDS
byNCFS
matrix. Each
row corresponds to the vector of time factors for each bond. Each
element in a column corresponds to the specific time factor associated
with each cash flow of a bond.
Time factors are for price/yield conversion and time factors are in units of whole semiannual coupon periods plus any fractional period using an actual day count. For more information on time factors, see Time Factors.
CFlowFlags
— Cash flow flags for a portfolio of bondsCash flow flags for a portfolio of bonds, returned as a
NBONDS
byNCFS
matrix. Each
row corresponds to the vector of cash flow flags for each bond. Each
element in a column corresponds to the specific flag associated with
each cash flow of a bond. Flags identify the type of each cash flow (for
example, nominal coupon cash flow, front, or end partial, or "stub"
coupon, maturity cash flow).
Flag 
Cash Flow Type 


Accrued interest due on a bond at settlement. 

Initial cash flow amount smaller than normal due to a “stub” coupon period. A stub period is created when the time from issue date to first coupon date is shorter than normal. 

Larger than normal initial cash flow amount because the first coupon period is longer than normal. 

Nominal coupon cash flow amount. 

Normal maturity cash flow amount (face value plus the nominal coupon amount). 

End “stub” coupon amount (last coupon period is abnormally short and actual maturity cash flow is smaller than normal). 

Larger than normal maturity cash flow because the last coupon period longer than normal. 

Maturity cash flow on a coupon bond when the bond has less than one coupon period to maturity. 

Smaller than normal maturity cash flow when the bond has less than one coupon period to maturity. 

Larger than normal maturity cash flow when the bond has less than one coupon period to maturity. 

Maturity cash flow on a zero coupon bond. 

Sinking principal and initial cash flow amount smaller than normal due to a "stub" coupon period. A stub period is created when the time from issue date to first coupon date is shorter than normal. 

Sinking principal and larger than normal initial cash flow amount because the first coupon period is longer than normal. 

Sinking principal and nominal coupon cash flow amount. 
CFPrincipal
— Principal cash flowsPrincipal cash flows, returned as a
NBONDS
byNCFS
matrix.
If PrincipalType
is 'sinking'
,
CFPrincipal
output indicates when the principal
is returned.
If PrincipalType
is 'bullet'
,
CFPrincipal
is all zeros and, at
Maturity
, the appropriate
Face
value.
Time factors help determine the present value of a stream of cash flows.
The term time factors refer to the exponent TF in the discounting equation
$$PV={\displaystyle \sum _{i=1}^{n}\left(\frac{CF}{{(1+\frac{z}{f})}^{TF}}\right)},$$
where:
PV = 
Present value of a cash flow. 
CF = 
Cash flow amount. 
z = 
Riskadjusted annualized rate or yield corresponding to a given cash flow. The yield is quoted on a semiannual basis. 
f = 
Frequency of quotes for the yield. Default is

TF = 
Time factor for a given cash flow. The time factor is
computed using the compounding frequency and the
discount basis. If these values are not specified, then
the defaults are as follows:

The Basis
is always used to compute accrued
interest.
[1] Krgin, D. Handbook of Global Fixed Income Calculations. Wiley, 2002.
[2] Mayle, J. "Standard Securities Calculations Methods: Fixed Income Securities Formulas for Analytic Measures." SIA, Vol 2, Jan 1994.
[3] Stigum, M., Robinson, F. Money Market and Bond Calculation. McGrawHill, 1996.
accrfrac
 cfdates
 cftimes
 cpncount
 cpndaten
 cpndatenq
 cpndatep
 cpndatepq
 cpndaysn
 cpndaysp
 datetime
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
You can also select a location from the following list: