Structured Securities - Amortized Example

Overview


This example examines a simple security that is structured like an amortized loan and backed by a pool of assets. In this example, the security has a stated principal and interest rate, and pays fixed payments.

See Full code for a complete listing of the code in this example.

  • Start date is 2020-01-31
  • The number of payments is 120 (10 years, one payment per month)
  • Payments occur following the end of month rule, that is if a calculated payment extends into the next month, it is pushed back to the end of the month. (see end of month rule)
  • Principal is $100,000
  • Interest Rate is 5%

Calculating the Fixed Payments


The contractual structure of the security specifies that the payments are fixed, like an amortized loan. The following code utilizes the payments library to calculate the payments required by the above specifications. 


let pm = await import('/lib/finance/fixed-income/v1.0.0/payments.mjs');

let start = '2020-01-31';
let number = 12*10;
let period=12;
let endOfMonth = true;
let principal = 100000;
let rate = 0.05;

let payments = pm.amortized(start, principal, rate, number, period, endOfMonth);
let paymentMap = $group(payments, p=>p.date)();
Try it!

Asset Cash Flows


The assets that back the structure will generate their own cash flows. For this example, we include a hard coded array of cash flows. (these will typically be forecast using the cash flow forecasting tools) 


let flows = [{date:'2010-01-01', value:10},{date:'2010-01-01', value:10},
  {date:'2010-01-07', value:10},{date:'2010-01-10', value:10},
  {date:'2010-08-07', value:10},{date:'2010-09-10', value:10},
  {date:'2011-01-07', value:10},{date:'2011-01-10', value:10}
];


Next, we put the asset cash flows into the same array as the calculated payments. We use the $group api to create a date record for each date where an asset cash flow or a payment occurs. Each record will have the following properties.

  • value - the cash flow generated on the given date by the assets backing the structure
  • payment - the contractual payment of the structure



flows = [...flows, ...payments]
let cashFlows = $group(flows, p=>p.date).map((keys, values)=>{
    let item = {
        date:keys[0],
        value : $list(values).filter(p=>p.value !== undefined).map(p=>p.value).sum(),
        payment:$list(values).filter(p=>p.payment !== undefined).map(p=>p.payment).sum(),
    }
    return item;
}).values();

Calculating Cash


The final step is to keep a running total of the amount of available cash in the structure. Whenever a cash flow occurs from an asset in the pool, the cash value is increased. Whenever a payment needs to occur, the cash value is decreased by the relevant amount. 


let st = await import('/lib/sort/v1.0.0/sort.mjs');

let cash = 0;
for(let item of st.sort(cashFlows, p=>p.date)){
    
  //increase the cash available by 
  cash += item.value;
  cash -= item.payment;
  if(item.date in paymentMap){
    item.fees = 10;
    cash -= item.fees;
  }
  item.cash = cash;
}

Contents