Documentation is confusing

[sethreidnz]

Hi,

I want to use this library to calculate for example how much interest is paid in the first year of a loan with determined interest rate, term and initial loan balance.

So for example I want to write some function that is like this:

function interestPaidInYear(loanBalance, termsLeftInLoan, interestRate, yearNumber){

  return InterstPaidInYearNumber;
}

So you could take a loan and figure out how much interest was paid in for example year 5, or year 6 or year 7. I can write the function but understanding the output of amortize is key and I don't quite get it.

What do the objects in the return value represent? Are they the total of the amount pain in the amortization period (ie the first year if you pass 12 as the amortize period) or is it the total amount of interest/principal/balance left in the loan after that period?

This looks great but I'm not sure what the actual result is and it is not really clearly described. I'd be happy to contrib to the docs and help explain it better if I understood what it was doing. going to start reading the source now but I thought some one who wrote the library would be able to help.

Thanks

[ascott1]

Thanks for reaching out and I apologize if the documentation is confusing @justsayno. We'd certainly welcome any contributions to improving the documentation.

The module accepts the total length of the loan term (in months) and the amortization term in months. From there it will return the interest paid to amortization point, the principal paid to the amortization, the remaining balance of the loan, and the monthly payment.

If you want to calculate the interest paid in a single year, you would need to calculate the interest paid up until that point and subtract it.

So it might look something like this (note that I changed the function parameters from your example, but those could be calculated out if need be):

function interestPaidInYear(totalLoanAmount, termsPaidInLoan, interestRate, totalLoanTerm){

  var totalAmortized = amortize({
    amount: totalLoanAmount,
    rate: interestRate,
    totalTerm: totalLoanTerm,
    amortizeTerm: termsPaidInLoan
  });

  var shorterAmortized = amortize({
    amount: totalLoanAmount,
    rate: interestRate,
    totalTerm: totalLoanTerm,
    amortizeTerm: termsPaidInLoan - 12
  });

  var InterstPaidInYearNumber = totalAmortized.interest - shorterAmortized.interest
  return InterstPaidInYearNumber;
}

I haven't tested the above, but based on my memory that should get what you're hoping to achieve. I'm more than happy to help hash it out further if need be.

[contolini]

cc @mthibos

[sethreidnz]

Hey thanks heaps for that, I managed to figure out that what you said above is exactly what I need to do. I will when I've got time do a pull request on the readme. Basically all I'm saying is fleshing out what you have to make it 100% clear what the return values represent. I was able to figure it out looking at the source but it could be clearer I think.

[ascott1]

@justsayno re-reading the README, I completely agree that it could be clearer. Glad you figured it out though!

I'm going to leave this issue open as a reminder for us to update the docs. We'd also welcome your contributions. Thanks!

[sethreidnz]

Hey I did a pull request but I think I am wrong about what I've said. If you could fix what it says to represent the truth would be great :-) I am still mildly confused about what the result object number represent but I think my pull request is a good format to explain, I just don't think I was right now that I think about it and might better you explain it.

[sethreidnz]

Okay so I think I'll explain my confusion as this calcaultion I've made is not returning what I think it should be. So if I do the following:

var totalAmortized  = amortize({
                                        amount: 400000,
                                        rate: 6,
                                        totalTerm: 360,
                                        amortizeTerm: 12
                                    });

var shorterAmortized  = amortize({
                                        amount: 400000,
                                        rate: 6,
                                        totalTerm: 360,
                                        amortizeTerm: 0
                                    });

I get these results:

totalAmortized = 
{
balance:395087.9531508928
balanceRound:"395087.95"
interest:23866.37835822523
interestRound:"23866.38"
payment:2398.202100611036
paymentRound:"2398.20"
principal:4912.046849107199
principalRound:"4912.05"
}

shorterAmortized =
{
balance:400000
balanceRound:"400000.00"
interest:0
interestRound:"0.00"
payment:2398.202100611036
paymentRound:"2398.20"
principal:0
principalRound:"0.00"
}

Now my confusion is that 'interest' in totalAmortized is 23,866. Which seems huge. So is the interest in that value there the interest remaining or the interest paid in that peroid? My assumption was it was interest paid in that peroid but that cannot be the case if in the first year of a 30 year loan you pay 23,000...

Thanks heaps for your help!

[ascott1]

I think that may be right, as a borrower is primarily paying interest up front and principal increases over the life of the loan.

Here's a loan amortization table with your specifics from another site, which may be useful. In each payment period you can see the amount of principal and interest paid. The $23,866.38 matches the interest paid at the 12 month period on that table as well.

From our AskCFPB tool:

Amortization describes the process of gradual payment of the amount on your loan. For each of your monthly payments, a portion is applied towards the amount of the loan – the principal – and a portion of the payment is applied towards paying the finance charge – the interest.

A greater percentage of your monthly payment is applied to interest early in the life of the loan, and a greater percentage is applied to the principal at the end. Thus, the principal balance decreases slowly at first and more quickly closer to the end of the loan term. So if you default early in the life of the loan, you will still owe a significant amount on the principal because only a relatively small percentage of your monthly payments were applied to the principal.

[mthibos]

@justsayno

Actually, your calculation is correct, and the code is returning correctly. It just happens to be the case that the amount of interest you pay in year 1 of a 30-year loan is, in fact, a lot more than what you might think. The way amortization works, your monthly payment is the same each month, but in the beginning, most of that payment goes to interest. As you pay down the loan, you pay increasingly more principal each month and increasingly less interest.

Here's the first year of an amortization table for your scenario. You can see that you don't pay much principal in year 1 of a 30 year loan. Your payments are mostly going to interest. By the end of the year, you've paid $23,866.38 in interest, and not even $5,000 in principal.

Here's the same loan in year 5. Still mostly interest:

And here's the last year of the loan. Now it's almost all principal, because the remaining loan amount is very small.

[ascott1]

Thanks for chiming in @mthibos!

[sethreidnz]

Oh cool so my pull request is correct. That makes a lot of sense actually and I completely understand now. Thanks so much guys! I think if you just included something like my pull request it would make it a lot easier to figure out.

[ascott1]

@justsayno excellent! Happy to help. I'll be including your pull request and plan on adding a higher level description of amortization as well.

[sethreidnz]

Just out of interest have you considered reaching out to the financejs (http://financejs.org/) guys and getting them to use your amortization calculation? It's better than theirs and I'm currently using their library as well as yours.

[ascott1]

We have not, but thanks for the tip. We probably should as it looks like their module just returns a monthly payment. Also, we'd love to see what you build with our module when it's complete!

I'm going to close this issue, but feel free to post more or to reach out directly.