np.pmt documentation is misleading on calculating monthly rate

[kigawas]

Documentation

To calculate the monthly rate, you should calculate as (1 + annual_rate) ** (1/12) - 1 rather than simply divide it by 12.

    Examples
    --------
    >>> import numpy_financial as npf

    What is the monthly payment needed to pay off a $200,000 loan in 15
    years at an annual interest rate of 7.5%?

    >>> npf.pmt(0.075/12, 12*15, 200000)
    -1854.0247200054619

    In order to pay-off (i.e., have a future-value of 0) the $200,000 obtained
    today, a monthly payment of $1,854.02 would be required.  Note that this
    example illustrates usage of `fv` having a default value of 0.

Should be rephrased to

    Examples
    --------
    >>> import numpy_financial as npf

    What is the monthly payment needed to pay off a $200,000 loan in 15
    years at an annual interest rate of 7.5%?

    >>> npf.pmt(1.075**(1/12) - 1, 12*15, 200000)
    -1826.1657857130267

    In order to pay-off (i.e., have a future-value of 0) the $200,000 obtained
    today, a monthly payment of $1,826.17 would be required.  Note that this
    example illustrates usage of `fv` having a default value of 0.

https://github.com/numpy/numpy-financial/blob/master/numpy_financial/_financial.py#L220-L232

[charris]

Financial has been removed from NumPy and made a separate project at https://github.com/numpy/numpy-financial. Please open your issue there.

[kigawas]

@charris

Can you transfer this issue to that repository?

[charris]

Done.

[kigawas]

Thanks!

[garfieldthecat]

@kigawas You are wrong. You are not the first one to make this error, but it remains an error.
If you take a 100 loan (I am intentionally ignoring the currency as it's irrelevant) from the bank at 12% per annum with monthly payments, your first interest payment (let's ignore day count conventions for a sec and implicitly assume 30/360) after one month will be = 100 * 12% /12 = 1 , NOT to 100 * ( 1 + 0.12) ** (1/12) !! By the way, it is easy to see that 12% / 12 > 1.12**(1/12) -1 (1% > 0.95%) , ie that the simple rate is, in this case, higher than the compounded one.

You can easily check this with one of the many mortgage or loan calculators easily available online.

Or on Microsoft's official documentation page for its pmt function in Excel : https://support.microsoft.com/en-us/office/pmt-function-0214da64-9a63-4996-bc20-214433fa6441

Or in the appendix to the book "Consumer Credit fundamentals", freely available (the appendix) from the publisher's website (Springer) https://link.springer.com/content/pdf/bbm%3A978-0-230-50234-5%2F1.pdf
https://link.springer.com/book/10.1057/9780230502345#toc

[kigawas]

@kigawas You are wrong. You are not the first one to make this error, but it remains an error.
If you take a 100 loan (I am intentionally ignoring the currency as it's irrelevant) from the bank at 12% per annum with monthly payments, your first interest payment (let's ignore day count conventions for a sec and implicitly assume 30/360) after one month will be = 100 * 12% /12 = 1 , NOT to 100 * ( 1 + 0.12) ** (1/12) !! By the way, it is easy to see that 12% / 12 > 1.12**(1/12) -1 (1% > 0.95%) , ie that the simple rate is, in this case, higher than the compounded one.

You can easily check this with one of the many mortgage or loan calculators easily available online.

Or on Microsoft's official documentation page for its pmt function in Excel : https://support.microsoft.com/en-us/office/pmt-function-0214da64-9a63-4996-bc20-214433fa6441

Or in the appendix to the book "Consumer Credit fundamentals", freely available (the appendix) from the publisher's website (Springer) https://link.springer.com/content/pdf/bbm%3A978-0-230-50234-5%2F1.pdf
https://link.springer.com/book/10.1057/9780230502345#toc

Your appendix does use compound interest on page 217.

Well, this calculation might be too difficult for those who didn't attend proper calculus class in university.

[garfieldthecat]

Well, to be fair, the formula is not calculus - it is basic algebra (just fractions and powers), of the kind which tends to be taught between the ages of 13 and 16 in most countries.

Formla (5) on page 217 of the appendix is the exact same formula as that used by numpy_financial (in the special case when fv =0 and when =0, ie payments at the end), as you can see starting from line 235 of the code.

If you read the example on the same page, it talks about a loan with monthly payments, and, you are right, it uses compounding, which is WRONG - I had missed that, sorry.

Let's try the repayment calculator of CitiBank USA and calculate the repayments for borrowing 250,000 at 2% over 25 years:
https://online.citi.com/US/JRS/portal/template.do?ID=mortgage_mortgage_calculator

The monthly repayment is 1,059.64, which is the result of -pmt(0.02/12, 25*12, 250000)
If you had compounded the 2% rate, to get to 1.02**(1/12) - 1 = 0.16516% and used that in the pmt formula, the result would have been 1,057, not 1059.64.

You get the same results using the calculator of HSBC UK: https://www.hsbc.co.uk/mortgages/repayment-calculator/

The difference is of course greater with a bigger interest rate. Let's try 10%: the monthly payment goes up to 2,272. If you compounded the rate as you suggest, it would be 2,196.

What does this mean? In theory, in an abstract world, a loan might potentially work as you describe. In the real world, it doesn't - I have yet to see a single example where it does - AFAIK that would be illegal in most, if not all, countries!

I hope that this clarifies the matter and the issue can be closed. If you have any more questions, just ask.

PS Depending on the country, the applicable law and what was negotiated, there will be cases where a borrower pays interest on unpaid interest - but that is a completely separate matter.

[kigawas]

Well, to be fair, the formula is not calculus - it is basic algebra (just fractions and powers), of the kind which tends to be taught between the ages of 13 and 16 in most countries.

Formla (5) on page 217 of the appendix is the exact same formula as that used by numpy_financial (in the special case when fv =0 and when =0, ie payments at the end), as you can see starting from line 235 of the code.

If you read the example on the same page, it talks about a loan with monthly payments, and, you are right, it uses compounding, which is WRONG - I had missed that, sorry.

Let's try the repayment calculator of CitiBank USA and calculate the repayments for borrowing 250,000 at 2% over 25 years:
https://online.citi.com/US/JRS/portal/template.do?ID=mortgage_mortgage_calculator

The monthly repayment is 1,059.64, which is the result of -pmt(0.02/12, 25*12, 250000)
If you had compounded the 2% rate, to get to 1.02**(1/12) - 1 = 0.16516% and used that in the pmt formula, the result would have been 1,057, not 1059.64.

You get the same results using the calculator of HSBC UK: https://www.hsbc.co.uk/mortgages/repayment-calculator/

The difference is of course greater with a bigger interest rate. Let's try 10%: the monthly payment goes up to 2,272. If you compounded the rate as you suggest, it would be 2,196.

What does this mean? In theory, in an abstract world, a loan might potentially work as you describe. In the real world, it doesn't - I have yet to see a single example where it does - AFAIK that would be illegal in most, if not all, countries!

I hope that this clarifies the matter and the issue can be closed. If you have any more questions, just ask.

PS Depending on the country, the applicable law and what was negotiated, there will be cases where a borrower pays interest on unpaid interest - but that is a completely separate matter.

Can't agree.

This is how they trick you, especially when the interest rate is not trivial.

You need some critical thinking.

[garfieldthecat]

I don't follow - you can't agree on what? And why?

Critical thinking? What do you mean?

[ZachariahRosenberg]

@kigawas maybe it's an attempt at trickery - it would be simpler if the rate quoted matched the compounding duration - but these days the annual percentage rate, APR, has largely become the conventional way to quote rates; even though they typically compound monthly.

Another area where you end up paying more, which @garfieldthecat alluded to, is in the type of accrual method. 30/360, vs Actual/360 vs Actual/Actual also has an effect on your overall payment. Sometimes the options chosen for a loan product are a matter of profitability, sometimes simplicity, and other times, consistency. So it goes.

@garfieldthecat I enjoyed your explanation. That was kind of you to take the time to write a thoughtful response.

This issue ought to be closed.

[kigawas]

@ZachariahRosenberg

It might be simpler for calculating, but make sure you understand what compound interest is. Don't make the so-called simplicity an excuse for your misunderstanding - that's what I wanted to say

[garfieldthecat]

@kigawas Dude, you are wrong. No ifs, no buts, no maybes. Accept it, be thankful for the detailed explanation, and move on.