# cmoseqcf

Generate cash flows for sequential collateralized mortgage obligation (CMO)

## Syntax

``[Balance,Principal,Interest] = cmoseqcf(PrincipalPayments,TranchePrincipalsTrancheCoupons)``
``[Balance,Principal,Interest] = cmoseqcf(___,HasZ)``

## Description

example

````[Balance,Principal,Interest] = cmoseqcf(PrincipalPayments,TranchePrincipalsTrancheCoupons)` generates cash flows for a sequential CMO without a Z-bond, given the underlying mortgage pool payments.```

example

````[Balance,Principal,Interest] = cmoseqcf(___,HasZ)` generates cash flows for a sequential CMO with a Z-bond, given the underlying mortgage pool payments, by adding an additional optional input for `HasZ`.```

## Examples

collapse all

Define the mortgage pool under consideration for CMO structuring using `mbscfamounts` or `mbspassthrough` and calculate the cash flows with an A and B tranche for a sequential CMO.

```MortgagePrincipal = 1000000; Coupon = 0.12; Terms = 6; % months % Calculate underlying mortgage cash flows [PrincipalBalance, MonthlyPayments, SchedPrincipalPayments, ... InterestPayments, Prepayments] = ... mbspassthrough(MortgagePrincipal, Coupon, Terms, Terms, 0, []); PrincipalPayments = SchedPrincipalPayments.' + Prepayments.'```
```PrincipalPayments = 1×6 105 × 1.6255 1.6417 1.6582 1.6747 1.6915 1.7084 ```

Define CMO tranches, A and B.

```TranchePrincipals = [500000; 500000]; TrancheCoupons = [0.12; 0.12];```

Calculate cash flows for each tranche.

```[Balance, Principal, Interest] = ... cmoseqcf(PrincipalPayments, TranchePrincipals, TrancheCoupons, false)```
```Balance = 2×6 105 × 3.3745 1.7328 0.0746 0 0 0 5.0000 5.0000 5.0000 3.3999 1.7084 0.0000 ```
```Principal = 2×6 105 × 1.6255 1.6417 1.6582 0.0746 0 0 0 0 0 1.6001 1.6915 1.7084 ```
```Interest = 2×6 103 × 5.0000 3.3745 1.7328 0.0746 0 0 5.0000 5.0000 5.0000 5.0000 3.3999 1.7084 ```

## Input Arguments

collapse all

Number of terms remaining for underlying principal payments, specified as a matrix of size `1`-by-`NUMTERMS`, where `NUMTERMS` is the number of terms remaining. Each column contains the underlying principal payment for the time period corresponding to the row number. Calculate underlying principal payments using `mbscfamounts` or `mbspassthrough`. The underlying principal payments can also be outputs from other CMO cash flow functions.

Data Types: `double`

Initial principal for each tranche, specified as a matrix of size `NUMTRANCHES`-by-`1`, where `NUMTRANCHES` is the number of tranches in the sequential CMO. Each element of the matrix represents the initial principal for each tranche. If the sequential CMO includes a Z-bond (`HasZ` is `true`), the last element of this matrix is the principal of the Z-bond.

Data Types: `double`

Coupon for each tranche, specified as a matrix of size `NUMTRANCHES`-by-`1`, where `NUMTRANCHES` is the number of tranches in the sequential CMO. Each element of the matrix represents the coupon for each tranche. If the sequential CMO includes a Z-bond (`HasZ` is `true`), the last element of this matrix is the coupon of the Z-bond. The weighted average coupon for the CMO should not exceed the coupon of the underlying mortgage.

Data Types: `double`

(Optional) Indicates that the sequential CMO contains a Z-bond, specified as a Boolean (`true` or `false`). A value of `true` indicates that the sequential CMO contains a Z-bond, and the last element of `TranchePrincipals` and `TrancheCoupons` is treated as that of the Z-bond. A value of `false` indicates that there is no Z-bond in the sequential CMO, and the last element of `TranchePrincipals` and `TrancheCoupons` is treated as an ordinary tranche.

Data Types: `logical`

## Output Arguments

collapse all

Principal balance for time period and tranche, returned as a matrix of size `NUMTRANCHES`-by-`NUMTERMS`, where `NUMTRANCHES` is the number of terms remaining and `NUMTRANCHES` is the number of tranches. Each element represents the principal balance at the time period corresponding to the column, and for the tranche corresponding to the row.

Principal payments for time period and tranche, returned as a matrix of size `NUMTRANCHES`-by-`NUMTERMS`, where `NUMTRANCHES` is the number of terms remaining and `NUMTRANCHES` is the number of tranches. Each element represents the principal payments made at the time period corresponding to the column, and to the tranche corresponding to the row.

Interest payments for time period and tranche, returned as a matrix of size `NUMTRANCHES`-by-`NUMTERMS`, where `NUMTRANCHES` is the number of terms remaining and `NUMTRANCHES` is the number of tranches. Each element represents the interest payments made at the time period corresponding to the column, and to the tranche corresponding to the row.

collapse all

### Sequential Pay CMO

A sequential pay CMO involves tranches that pay off principal sequentially.

For example, consider the following case, where all principal from the underlying mortgage pool is repaid on tranche A first, then tranche B, then tranche C. Interest is paid on each tranche as long as the principal for the tranche has not been retired.

### CMO Tranche

Tranche is a term often used to describe a specific class of bonds within an offering wherein each tranche offers varying degrees of risk to the investor.

 Hayre, Lakhbir, ed. Salomon Smith Barney Guide to Mortgage-Backed and Asset-Backed Securities. John Wiley and Sons, New York, 2001.

 Lyuu, Yuh-Dah. Financial Engineering and Computation. Cambridge University Press, 2004.