Merge pull request #14508 from Kai-Striega/financial_review

DOC: Add warning to NPV function

2 files changed, 33 insertions, 6 deletions

diff --git a/numpy/lib/financial.py b/numpy/lib/financial.py
index 216687475..d72384e99 100644
--- a/numpy/lib/financial.py
+++ b/numpy/lib/financial.py
@@ -715,8 +715,6 @@ def irr(values):
     >>> round(np.irr([-5, 10.5, 1, -8, 1]), 5)
     0.0886
 
-    (Compare with the Example given for numpy.lib.financial.npv)
-
     """
     # `np.roots` call is why this function does not support Decimal type.
     #
@@ -763,6 +761,15 @@ def npv(rate, values):
         The NPV of the input cash flow series `values` at the discount
         `rate`.
 
+    Warnings
+    --------
+    ``npv`` considers a series of cashflows starting in the present (t = 0).
+    NPV can also be defined with a series of future cashflows, paid at the
+    end, rather than the start, of each period. If future cashflows are used,
+    the first cashflow `values[0]` must be zeroed and added to the net
+    present value of the future cashflows. This is demonstrated in the
+    examples.
+
     Notes
     -----
     Returns the result of: [G]_
@@ -776,10 +783,24 @@ def npv(rate, values):
 
     Examples
     --------
-    >>> np.npv(0.281,[-100, 39, 59, 55, 20])
-    -0.0084785916384548798 # may vary
-
-    (Compare with the Example given for numpy.lib.financial.irr)
+    Consider a potential project with an initial investment of $40 000 and
+    projected cashflows of $5 000, $8 000, $12 000 and $30 000 at the end of
+    each period discounted at a rate of 8% per period. To find the project's
+    net present value:
+
+    >>> rate, cashflows = 0.08, [-40_000, 5_000, 8_000, 12_000, 30_000]
+    >>> np.npv(rate, cashflows).round(5)
+    3065.22267
+
+    It may be preferable to split the projected cashflow into an initial
+    investment and expected future cashflows. In this case, the value of
+    the initial cashflow is zero and the initial investment is later added
+    to the future cashflows net present value:
+
+    >>> initial_cashflow = cashflows[0]
+    >>> cashflows[0] = 0
+    >>> np.round(np.npv(rate, cashflows) + initial_cashflow, 5)
+    3065.22267
 
     """
     values = np.asarray(values)
diff --git a/numpy/lib/tests/test_financial.py b/numpy/lib/tests/test_financial.py
index 524915041..21088765f 100644
--- a/numpy/lib/tests/test_financial.py
+++ b/numpy/lib/tests/test_financial.py
@@ -9,6 +9,12 @@ from numpy.testing import (
 
 
 class TestFinancial(object):
+    def test_npv_irr_congruence(self):
+        # IRR is defined as the rate required for the present value of a
+        # a series of cashflows to be zero i.e. NPV(IRR(x), x) = 0
+        cashflows = np.array([-40000, 5000, 8000, 12000, 30000])
+        assert_allclose(np.npv(np.irr(cashflows), cashflows), 0, atol=1e-10, rtol=0)
+
     def test_rate(self):
         assert_almost_equal(
             np.rate(10, 0, -3500, 10000),