[CFlowAmounts, CFlowDates, TFactors, CFlowFlags, CFPrincipal] = cfamounts(CouponRate, Settle, Maturity) returns
matrices of cash flow amounts, cash flow dates, time factors, and
cash flow flags for a portfolio of NUMBONDS fixed-income
securities.
[CFlowAmounts, CFlowDates, TFactors, CFlowFlags, CFPrincipal] = cfamounts(CouponRate, Settle, Maturity, Period, Basis, EndMonthRule, IssueDate, FirstCouponDate, LastCouponDate,
StartDate, Face) returns matrices of cash flow amounts,
cash flow dates, time factors, and cash flow flags for a portfolio
of NUMBONDS fixed-income securities defined using
required and optional inputs.
[CFlowAmounts, CFlowDates, TFactors, CFlowFlags, CFPrincipal] = cfamounts(CouponRate, Settle, Maturity, 'ParameterName', 'ParameterValue ...) accepts
optional inputs as one or more comma-separated parameter/value pairs. 'ParameterName' is
the name of the parameter inside single quotes. ParameterValue is
the value corresponding to 'ParameterName'.
Specify parameter/value pairs in any order. Names are case-insensitive.
Input Arguments
CouponRate
Decimal number indicating the annual percentage rate used to
determine the coupons payable on a bond. CouponRate is 0 for
zero coupon bonds.
Note:CouponRate and Face can
change over the life of the bond. Schedules for CouponRate and Face can
be specified with an NINST-by-1 cell
array, where each element is a NumDates-by-2 matrix
or cell array, where the first column is dates and the second column
is associated rates. The date indicates the last day that the coupon
rate or face value is valid.
Settle
Settlement date. A vector of serial date numbers or date strings. Settle must
be earlier than Maturity.
Maturity
Maturity date. A vector of serial date numbers or date strings.
Ordered Input or Parameter–Value Pairs
Enter the following inputs using an ordered syntax or as parameter/value
pairs. You cannot mix ordered syntax with parameter/value pairs.
Period
Coupons per year of the bond. A vector of integers. Values are
0, 1, 2, 3, 4, 6, and 12.
Default: 2
Basis
Day-count basis of the instrument. A vector of integers.
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 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.
Default: 1
IssueDate
Issue date for a bond.
Default: If you do not specify an IssueDate, the
cash flow payment dates are determined from other inputs.
FirstCouponDate
Date when a bond makes its first coupon payment; used when bond
has an irregular first coupon period. When FirstCouponDate and LastCouponDate are
both specified, FirstCouponDate takes precedence
in determining the coupon payment structure.
Default: If you do not specify a FirstCouponDate,
the cash flow payment dates are determined from other inputs.
LastCouponDate
Last coupon date of a bond before the maturity date; used when
bond has an irregular last coupon period. In the absence of a specified FirstCouponDate,
a specified LastCouponDate determines the coupon
structure of the bond. The coupon structure of a bond is truncated
at the LastCouponDate, regardless of where it falls,
and is followed only by the bond's maturity cash flow date.
Default: If you do not specify a LastCouponDate,
the cash flow payment dates are determined from other inputs.
StartDate
Date when a bond actually starts (the date from which a bond
cash flow is considered). To make an instrument forward-starting,
specify this date as a future date.
Default: If you do not specify StartDate, the effective
start date is the Settle date.
Face
Face or par value.
Note:CouponRate and Face can
change over the life of the bond. Schedules for CouponRate and Face can
be specified with an NINST-by-1 cell
array where each element is a NumDates-by-2 matrix
or cell array, where the first column is dates and the second column
is associated rates. The date indicates the last day that the coupon
rate or face value is valid.
Default: 100
Parameter–Value Pairs
Enter the following inputs only as parameter/value pairs.
AdjustCashFlowsBasis
Adjust the cash flows based on the actual period day count. NINST-by-1 of
logicals.
Default: False
BusinessDayConvention
Require payment dates to be business dates. NINST-by-1 cell
array with possible choices of business day convention:
actual
follow
modifiedfollow
previous
modifiedprevious
Default: actual
CompoundingFrequency
Compounding frequency for yield calculation.
Default: SIA bases (0-7) and BUS/252 use a semiannual compounding
convention and ISMA bases (8-12) use an annual compounding convention.
DiscountBasis
Basis used to compute the discount factors for computing the
yield. If you use ISMA day counts and BUS/252, the specified basis
are used.
Default: SIA bases use the actual/actual day count
to compute discount factors.
Holidays
Holidays used for business day convention. NHOLIDAYS-by-1 of MATLAB^{®} date
numbers.
Default: If no dates are specified, holidays.m is
used.
PrincipalType
Type of principal for case when a Face schedule
is specified. The principal type is either sinking or bullet.
If sinking, principal cash flows are returned
throughout the life of the bond. If bullet, principal
cash flow is only returned at maturity.
Default: sinking
Output Arguments
CFlowAmounts
Cash flow matrix of a portfolio of bonds. Each row represents
the cash flow vector of a single bond. Each element in a column represents
a specific cash flow for that bond.
CFlowDates
Cash flow date matrix of a portfolio of bonds. Each row represents
a single bond in the portfolio. Each element in a column represents
a cash flow date of that bond.
TFactors
Matrix of time factors for a portfolio of bonds. 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 help determine the present value of a
stream of cash flows. The term time factor refers
to the exponent TF in the discounting equation
Risk-adjusted 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 2 for Basis values 0 to 7 and 13 and 1 for Basis values 8 to 12.
The default can be overridden by specifying the CompoundingFrequency name/value
pair.
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: CompoundingFrequency default
is 2 for Basis values 0 to 7 and 13 and 1 for Basis values 8 to 12. DiscountBasis is 0 for Basis values 0 to 7 and 13 and
the input Basis for Basis values 8 to 12.
Note:
The Basis is always used to compute accrued
interest.
CFlowFlags
Matrix of cash flow flags for a portfolio of bonds. 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
0
Accrued interest due on a bond at settlement.
1
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.
2
Larger than normal initial cash flow amount because the
first coupon period is longer than normal.
3
Nominal coupon cash flow amount.
4
Normal maturity cash flow amount (face value plus the
nominal coupon amount).
5
End "stub" coupon amount (last coupon period
is abnormally short and actual maturity cash flow is smaller than
normal).
6
Larger than normal maturity cash flow because the last
coupon period longer than normal.
7
Maturity cash flow on a coupon bond when the bond has
less than one coupon period to maturity.
8
Smaller than normal maturity cash flow when the bond
has less than one coupon period to maturity.
9
Larger than normal maturity cash flow when the bond has
less than one coupon period to maturity.
10
Maturity cash flow on a zero coupon bond.
11
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.
12
Sinking principal and larger than normal initial cash
flow amount because the first coupon period is longer than normal.
13
Sinking principal and nominal coupon cash flow amount.
CFPrincipal
CFPrincipal contains the principal cash flows.
If PrincipalType is bullet, CFPrincipal is
all zeros and, at Maturity, the appropriate Face value.
Definitions
The elements contained in the cfamounts
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 NaNs
as necessary to ensure that all rows have the same number of elements.
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 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 Name-Value pairs for Period, Basis, BusinessDayConvention, and AdjustCashFlowsBasis.
This 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-by-1 cell array, where each element is a NumDates-by-2 matrix where the first column is dates and the second column is associated rates.
CouponSchedule = {[datenum('15-Mar-2012') .04;datenum('15- Mar -2013') .05;...
datenum('15- Mar -2015') .06]}
cfamounts(CouponSchedule,'01-Mar-2011','15-Mar-2015' )
CouponSchedule =
[3x2 double]
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
This 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-by-1 cell array, where each element is a NumDates-by-2 matrix where the first column is dates and the second column is associated rates.
FaceSchedule = {[datenum('15-Mar-2012') 100;datenum('15- Mar -2013') 90;...
datenum('15- Mar -2015') 80]}
cfamounts(.05,'01-Mar-2011','15-Mar-2015', 'Face', FaceSchedule)
FaceSchedule =
[3x2 double]
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