# cftimes

Time factors corresponding to bond cash flow dates

## Syntax

``TFactors = cftimes(Settle,Maturity)``
``TFactors = cftimes(___,Name,Value)``

## Description

````TFactors = cftimes(Settle,Maturity)` determines the time factors corresponding to the cash flows of a bond or set of bonds.`cftimes` computes the time factor of a cash flow, which is the difference between the settlement date and the cash flow date, in units of semiannual coupon periods. In computing time factors, use SIA actual/actual day count conventions for all time factor calculations.```

example

````TFactors = cftimes(___,Name,Value)` specifies options using one or more name-value pair arguments in addition to the input arguments in the previous syntax. ```

example

## Examples

collapse all

This example shows how to calculate a cash flow time factor.

```Settle = datetime(1997,3,15); Maturity = datetime(1999,9,1); Period = 2; TFactors = cftimes(Settle, Maturity, Period)```
```TFactors = 1×5 0.9239 1.9239 2.9239 3.9239 4.9239 ```

## Input Arguments

collapse all

Settlement date, specified as an `NINST`-by-`1` vector using a datetime array, string array, or date character vectors. `Settle` must be earlier than `Maturity`.

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

Data Types: `char` | `string` | `datetime`

Maturity date, specified as an `NINST`-by-`1` vector using a datetime array, string array, or date character vectors. The `Settle` date is the date on which the cash flows are priced.

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

Data Types: `char` | `string` | `datetime`

### Name-Value Arguments

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: ``` TFactors = cftimes(Settle,Maturity,'Period',4)```

Number of coupon payments per year, specified as the comma-separated pair consisting of `'Period'` and a scalar or a `NUMBONDS`-by-`1` or `1`-by-`NUMBONDS` vector using the values: `0`, `1`, `2`, `3`, `4`, `6`, or `12`.

Data Types: `double`

Day-count basis, specified as the comma-separated pair consisting of `'Basis'` and a positive integer using a `NINST`-by-`1` vector.

• 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

Data Types: `double`

End-of-month rule flag, specified as the comma-separated pair consisting of `'EndMonthRule'` and a scalar or a `NUMBONDS`-by-`1` or `1`-by-`NUMBONDS` 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.

Data Types: `logical`

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

If you do not specify an `IssueDate`, the cash flow payment dates are determined from other inputs.

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

Data Types: `char` | `string` | `datetime`

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

If you do not specify a `FirstCouponDate`, the cash flow payment dates are determined from other inputs.

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

Data Types: `char` | `string` | `datetime`

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

If you do not specify a `LastCouponDate`, the cash flow payment dates are determined from other inputs.

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

Data Types: `char` | `string` | `datetime`

Forward starting date of payments, specified as the comma-separated pair consisting of `'StartDate'` and a scalar or a `NUMBONDS`-by-`1` or `1`-by-`NUMBONDS` vector using a datetime array, string array, or date character vectors. The `StartDate` is 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.

If you do not specify a `StartDate`, the effective start date is the `Settle` date.

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

Data Types: `char` | `string` | `datetime`

Compounding frequency for yield calculation, specified as the comma-separated pair consisting of `'CompundingFrequency'` and a scalar or a `NUMBONDS`-by-`1` or `1`-by-`NUMBONDS` vector.

• `1` — Annual compounding

• `2` — Semiannual compounding

• `3` — Compounding three times per year

• `4` — Quarterly compounding

• `6` — Bimonthly compounding

• `12` — Monthly compounding

Note

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`

Basis used to compute the discount factors for computing the yield, specified as the comma-separated pair consisting of `'DiscountBasis'` and a scalar or a `NUMBONDS`-by-`1` or `1`-by-`NUMBONDS` 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

Note

If a SIA day-count 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 day-count 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`

## Output Arguments

collapse all

Time to cash flow, returned as an `NUMBONDS` rows. The number of columns is determined by the maximum number of cash flow payment dates required to hold the bond portfolio. `NaN`s are padded for bonds which have less than the maximum number of cash flow payment dates.

## References

[1] Krgin, Dragomir. Handbook of Global Fixed Income Calculations. John Wiley & Sons, 2002.

[2] Mayle, Jan. “Standard Securities Calculations Methods: Fixed Income Securities Formulas for Analytic Measures.” SIA, Vol 2, Jan 1994.

[3] Stigum, Marcia, and Franklin Robinson. Money Market and Bond Calculations. McGraw-Hill, 1996.

## Version History

Introduced before R2006a

expand all