numpy.fv — Calculate the Future Value of an Investment in Python

by

NumPy is full of those little helper functions that boost your productivity and make coding a lot of fun. The NumPy’s fv() function is one of those helpers for financial analysis that will save you a lot of time if you’re working in the financial sector—or if you’re just using NumPy to analyze your own financial assets.

What’s the Purpose of the np.fv() Function?

It computes the future value of an asset assuming you know the growth rate of the asset (its return on investment), the size of your regular contributions, and the duration of the investment period.

How Does the numpy.fv() Function Work?

Let’s check out the specification with all arguments. We assume that you expect to earn a 9% stock market return over 30 years, starting with an initial $1,000 without any regular contributions.

numpy.fv(rate, nper, pmt, pv, when='end')
  • rate: your return on investment. For example, stocks may have a historic return on investment of 9%. As an input, you give the respective floating point value: a return of 9% becomes rate=0.09.
  • nper: the number of periods you compound your investment. For example, to calculate the 30-year return on investment, you’d use the input argument nper=30.
  • pmt: the additional payments you contribute during your investment period. If you want to calculate the future value of a one-time investment, you’d use the input argument pmt=0. If you want to calculate the future value of an investment where you contribute $1,000 per year, you’d use the input argument pmt=-1000. An important note is that the input argument is negative, per convention, as contributing money to your investment would incur a negative cash flow pattern from the perspective of your cash accounts.
  • pv: the present value of your investment or asset. This is the starting point that will get compounded over the number of periods. If you start with $1,000 as an initial investment, you’d use the input argument pv=-1000. Again, note that the input argument is negative because of the negative cash flow pattern you’ll experience when transferring cash into your investment.
  • when: represents when the payment is due—at the end of a period or at the beginning. If your payment is due at the beginning of a period, you’d use the input argument when='begin', otherwise you’d use when='end'. This argument is optional.

Here’s an example of how you can calculate the future value of an investment into the stock market earning 9% yearly return over 30 years starting with an initial investment of $1,000:

>>> np.fv(0.09, 30, 0, -1000)
13267.678469131277

Your initial $1,000 investment would result in a whopping $13,267.68—time to get your investments going!

Note that an equivalent way of calculating the same thing in Python would be the following:

>>> 1000 * (1+0.09)**30
13267.678469131277

The np.fv() function is just a convenient way of doing it. If you’ve got regular contributions, however, there’s no simple formula like this and I’d recommend you use the NumPy’s future value function np.fv().

How to Plot the Future Value of an Investment?

We used the following code to plot the future value of the initial investment over the next 30 years:

import numpy as np
import matplotlib.pyplot as plt


y = [np.fv(0.09, i, 0, -1000) for i in range(30)]

plt.plot(y)
plt.ylabel("Investment Value")
plt.xlabel("Years")
plt.savefig("return.jpeg")
plt.show()

You can try it yourself in our interactive Python shell:

What Errors You Can Get?

The investment rate of the NumPy future value function np.fv() cannot be zero. Otherwise, you’d get the following error:

import numpy as np


y = np.fv(0, 30, 0, -1000)
print(y)
"""
Warning (from warnings module):
  File "C:\Users\xcent\AppData\Local\Programs\Python\Python37\lib\site-packages\numpy\lib\financial.py", line 137
    (1 + rate*when)*(temp - 1)/rate)
RuntimeWarning: invalid value encountered in long_scalars
"""

Which Formula is Used to Calculate the Future Value?

NumPy solves the following equation to calculate the future value of the investment:

fv + pv*(1+rate)**nper + pmt*(1 + rate*when)/rate*((1 + rate)**nper - 1) == 0

Can you see why we use negative values for the initial investment pv and the regular payments pmt?