numpy / numpy/numpy-financial

np.pmt documentation is misleading on calculating monthly rate

Open
#34 13 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
409
Forks
98
Avg merge
10h 43m
Merged PRs (30d)
12

Description

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

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Read the npf.pmt documentation example in numpy_financial/_financial.py around lines 220-232. Update the monthly-rate calculation, payment result, and explanatory wording to match the corrected example; done means the docstring no longer recommends dividing the annual rate by 12.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
1/5
Estimated time
Under an hour
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
50/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.