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
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
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
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
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
While working as a researcher in distributed systems, Dr. Christian Mayer found his love for teaching computer science students.
To help students reach higher levels of Python success, he founded the programming education website Finxter.com that has taught exponential skills to millions of coders worldwide. He’s the author of the best-selling programming books Python One-Liners (NoStarch 2020), The Art of Clean Code (NoStarch 2022), and The Book of Dash (NoStarch 2022). Chris also coauthored the Coffee Break Python series of self-published books. He’s a computer science enthusiast, freelancer, and owner of one of the top 10 largest Python blogs worldwide.
His passions are writing, reading, and coding. But his greatest passion is to serve aspiring coders through Finxter and help them to boost their skills. You can join his free email academy here.