MATLAB Examples

# CFEVALDEMO2

Function cfeval calculates cash flows of fixed-income portfolios and structured products, given a quasi-symbolic, Matlab-syntax, typically recursive description of principal and coupon dynamics. Combined, these descriptions are passed to cfsim in cell arrays of strings, whose rows correspond to securities, and columns to periods.

## Contents

Examples below replicate exhibits in Fixed Income Analysis for the Chartered Financial Analyst Program, 2nd ed., edited by Frank Fabozzi.

```help cfeval ```
``` CFEVAL Evaluate portfolio cash flows given their symbolic definitions INPUTS : N*T cell arrays of strings, where cell (i,t) contains definition of .. on security i in period t: pofun - principal outstanding cpfun - coupon payment psfun - scheduled principal repayment ppfun - unscheduled principal repayment par - parameter structure, available to calculations defined in pofun, cpfun, psfun, ppfun OUTPUTS : N*T arrays, where element (i,t) contains value of .. on security i in period t: cfval - total cash flow (sum of cfval, psval and ppval) poval - principal outstanding cpval - coupon payment psval - scheduled principal repayment ppval - unscheduled principal repayment NOTES : Cells of input arrays are evaluated sequentially, iterating over * periods: t = 1,..,T * securities: i = 1,..,N * input arrays: pofun, cpfun, psfun, ppfun Computing xval(i,t) - note that xfun arrays definitions must use indexes i and t - one can reference already-evaluated quantities EXAMPLE : See CFEVALDEMO AUTHOR : Dimitri Shvorob, dimitri.shvorob@vanderbilt.edu, 9/25/07 ```

## Example 1. Residential mortgage

a) set up security definitions

```y = 30; T = 12*y; par.S = 1e5; % loaned amount par.m = T; % mortgage term par.r = 0.08125; % mortgage rate ```
```[pofun,cpfun,psfun,ppfun] = deal(cell(1,T)); ```
• Principal outstanding: initially 100,000, reduced by principal repayments
```pofun{1} = 'par.S'; [pofun{2:T}] = deal('poval(i,t-1) - psval(i,t-1)'); ```
• Interest: 8.125%, paid out monthly
```[cpfun{:}] = deal('poval(i,t)*par.r/12'); ```
• Principal repayment: scheduled only, no prepayment. Function mgpmt computes (constant) amount of monthly payment on a level-payment, fixed-rate, fully amortized mortgage.
```[psfun{:}] = deal('poval(i,1)*mgpmt(par.r,par.m) - cpval(i,t)'); ```
```[ppfun{:}] = deal('0'); ```

b) calculate total payment, interest and principal-repayment series

```[cfval,poval,cpval,psval] = cfeval(pofun,cpfun,psfun,ppfun,par); %#ok ```

c) plot interest and principal-repayment series

```figure colormap autumn area([cpval' psval']) title('Interest and principal repayment as parts of mortgage payment') xlabel('Month'), ylabel('\$') legend('Interest','Principal repaid') set(gcf,'Color','w') ```

d) recalculate cfval using mbscfamounts of Fixed-Income Toolbox

• cfeval calculation
```cfval(1) %#ok ```
```ans = 742.50 ```
• mbscfamounts calculation
```t0 = today; t1 = addtodate(t0,T/12,'year'); [cf,d,t,f] = mbscfamounts(t0,t1,t0,par.r,par.r,0,0); %#ok par.S*cf(2) %#ok ```
```ans = 742.50 ```

## Example 2. Mortgage passthrough

• backed by loans of the type described in Example 1
• WAM = 357 months
• 100 PSA prepayment a) set up security definitions
```y = 30; T = 12*y; par.S = 4e8; % passthrough notional amount par.m = T; % mortgage term par.r = 0.08125; % mortgage rate par.c = 0.075; % coupon rate par.psa = 100; % prepayment scenario ```
```[pofun,cpfun,psfun,ppfun] = deal(cell(1,T)); ```
• Principal: 400,000,000 in period 4 - note that loans are seasoned by 3 months - reduced by principal repayments. We are interested in cash flows in periods 4-360.
```[pofun{:}] = deal('poval(i,t-1) - psval(i,t-1) - ppval(i,t-1)'); [pofun{1:4}] = deal('par.S'); ```
• Coupon payment: 7.5%, paid monthly
```[cpfun{:}] = deal('poval(i,t)*par.c/12'); ```
• Principal repayment: scheduled, plus prepayment 100 PSA

(PSA-benchmarked single month mortality rates are computed with function smmpsa )

```[psfun{:}] = deal('poval(i,t)*(mgpmt(par.r,par.m + 1 - t) - par.r/12)'); ```
```[ppfun{:}] = deal('poval(i,t)*smmpsa(t,par.psa)'); ```

b) calculate total cash flow

```[cfval,poval,cpval,psval,ppval] = cfeval(pofun,cpfun,psfun,ppfun,par); %#ok cfval100 = cfval(4:end); prval100 = psval(4:end) + ppval(4:end); ```

c) examine the effect of a change in prepayment behavior

```par.psa = 165; ```
```[cfval,poval,cpval,psval,ppval] = cfeval(pofun,cpfun,psfun,ppfun,par); %#ok cfval165 = cfval(4:end); prval165 = psval(4:end) + ppval(4:end); ```
• plot cash flow dynamics
```figure colormap autumn t = 1:357; plot(t,cfval100,'y--', ... t,cfval165,'r--') axis([4 360 0 6e6]) legend('PSA 100', 'PSA 165') xlabel('Month'), ylabel('\$') title('Passthrough cash flows under alternative prepayment scenarios') set(gcf,'Color','w') ```
• compute average lives
```al100 = sum(t.*prval100)/(12*par.S) %#ok al165 = sum(t.*prval165)/(12*par.S) %#ok ```
```al100 = 11.66 al165 = 8.77 ```

## Example 3. Collateralized mortgage obligation

• backed by loans of the type described in Example 5
• WAM = 357 months
• 165 PSA prepayment
• 4 sequential pay tranches

a) set up security definitions

```y = 30; T = 12*y; par.S = [194.5 36 96.5 73]*1e6; % tranche par amounts par.m = T; % mortgage term par.r = 0.08125; % mortgage rate par.c = 0.075; % coupon rate par.psa = 165; % prepayment scenario ```
```[pofun,cpfun,psfun,ppfun] = deal(cell(5,T)); ```

First row of input and output arrays will refer to the entire portfolio, i.e. sum of all tranches

• Principal: 400,000,000, split between four tranches, in period 4 - note that loans are seasoned by 3 months - reduced by principal repayments. We are interested in cash flows in periods 4-360.
```[pofun{:,1:4}] = deal('sum(par.S)'); [pofun{1,5:end}] = deal('sum(poval(2:5,t-1) - psval(2:5,t-1) - ppval(2:5,t-1))'); [pofun{2:5,4}] = deal('par.S(i-1)'); [pofun{2:5,5:end}] = deal('poval(i,t-1) - psval(i,t-1) - ppval(i,t-1)'); ```
• Interest payment: 7.5% for each tranche, paid monthly
```[cpfun{:}] = deal('poval(i,t)*par.c/12'); ```
• Principal repayment: scheduled, plus prepayment 165 PSA

(PSA-benchmarked single month mortality rates are computed with function smmpsa )

```[psfun{1,:}] = deal('(poval(1,t)*(mgpmt(par.r,par.m + 1 - t) - par.r/12))'); [psfun{2:5,:}] = deal('min(poval(i,t), psval(1,t)- sum(psval(2:(i-1),t)) )'); ```
```[ppfun{1,:}] = deal('smmpsa(t,par.psa)*(poval(1,t) - psval(1,t))'); [ppfun{2:5,:}] = deal('min(poval(i,t) - psval(i,t), ppval(1,t)- sum(ppval(2:(i-1),t)) )'); ```

b) calculate total cash flow and principal repayment

```[cfval,poval,cpval,psval,ppval] = cfeval(pofun,cpfun,psfun,ppfun,par); %#ok ```
```name = {'Cash flow (interest and principal)', ... 'Principal outstanding', ... 'Scheduled principal repayment', ... 'Unscheduled principal repayment (prepayment)'}; ```
```data = {cfval,poval,psval,ppval}; ```
```for i = 1:4 figure colormap autumn x = data{i}; bar(x(2:5,4:end)','stacked'); title(name{i}) set(gcf,'Color','w') end ```
```close all ```