From f145b667ca40b64112c5d8b007c263110a6cf585 Mon Sep 17 00:00:00 2001 From: RVitalii Date: Sat, 25 Nov 2023 15:02:01 +0100 Subject: [PATCH 1/3] Updating mirr docstring v2 [issue76] --- numpy_financial/_financial.py | 59 +++++++++++++++++++++++++++++------ 1 file changed, 49 insertions(+), 10 deletions(-) diff --git a/numpy_financial/_financial.py b/numpy_financial/_financial.py index 8bd280e..a90c899 100644 --- a/numpy_financial/_financial.py +++ b/numpy_financial/_financial.py @@ -904,29 +904,68 @@ def npv(rate, values): def mirr(values, finance_rate, reinvest_rate, *, raise_exceptions=False): - r"""Return the modified internal rate of return. + r""" + Return the Modified Internal Rate of Return (MIRR). + + MIRR is a financial metric that takes into account both the cost of + the investment and the return on reinvested cash flows. It is useful + for evaluating the profitability of an investment with multiple cash + inflows and outflows. Parameters ---------- values : array_like - Cash flows (must contain at least one positive and one negative - value) or nan is returned. The first value is considered a sunk - cost at time zero. + Cash flows, where the first value is considered a sunk cost at time zero. + It must contain at least one positive and one negative value. finance_rate : scalar - Interest rate paid on the cash flows + Interest rate paid on the cash flows. reinvest_rate : scalar - Interest rate received on the cash flows upon reinvestment + Interest rate received on the cash flows upon reinvestment. raise_exceptions: bool, optional - Flag to raise an exception when the mirr cannot be computed due to - having all cashflows of the same sign (NoRealSolutionException). - Set to False as default, thus returning NaNs in the previous - case. + Flag to raise an exception when the MIRR cannot be computed due to + having all cash flows of the same sign (NoRealSolutionException). + Set to False as default,thus returning NaNs in the previous case. Returns ------- out : float Modified internal rate of return + Notes + ----- + The MIRR formula is as follows: + + .. math:: + + MIRR = \\left( \\frac{{FV_{positive}}}{{PV_{negative}}} \\right)^{\\frac{{1}}{{n-1}}} * (1+r) - 1 + + where: + - \(FV_{positive}\) is the future value of positive cash flows, + - \(PV_{negative}\) is the present value of negative cash flows, + - \(n\) is the number of periods. + - \(r\) is the reinvestment rate. + + Examples + -------- + >>> import numpy_financial as npf + + Consider a project with an initial investment of -$100 + and projected cash flows of $50, -$60, and $70 at the end of each period. + The project has a finance rate of 10% and a reinvestment rate of 12%. + + >>> npf.mirr([-100, 50, -60, 70], 0.1, 0.12) + -0.03909366594356467 + + Now, let's consider the scenario where all cash flows are negative. + + >>> npf.mirr([-100, -50, -60, -70], 0.1, 0.12) + nan + + Finally, let's explore the situation where all cash flows are positive, and the `raise_exceptions` parameter is set to True. + + >>> npf.mirr([100, 50, 60, 70], 0.1, 0.12, raise_exceptions=True) + NoRealSolutionError: No real solution exists for MIRR since all cashflows are of the same sign. + """ values = np.asarray(values) n = values.size From b04ad78ddac6712e577e3b3d13d8e074406f535d Mon Sep 17 00:00:00 2001 From: RVitalii Date: Sat, 25 Nov 2023 15:02:01 +0100 Subject: [PATCH 2/3] Updating mirr docstring v2 [issue76] --- numpy_financial/_financial.py | 62 +++++++++++++++++++++++++++++------ 1 file changed, 52 insertions(+), 10 deletions(-) diff --git a/numpy_financial/_financial.py b/numpy_financial/_financial.py index 8bd280e..221dec5 100644 --- a/numpy_financial/_financial.py +++ b/numpy_financial/_financial.py @@ -904,29 +904,71 @@ def npv(rate, values): def mirr(values, finance_rate, reinvest_rate, *, raise_exceptions=False): - r"""Return the modified internal rate of return. + r""" + Return the Modified Internal Rate of Return (MIRR). + + MIRR is a financial metric that takes into account both the cost of + the investment and the return on reinvested cash flows. It is useful + for evaluating the profitability of an investment with multiple cash + inflows and outflows. Parameters ---------- values : array_like - Cash flows (must contain at least one positive and one negative - value) or nan is returned. The first value is considered a sunk - cost at time zero. + Cash flows, where the first value is considered a sunk cost at time zero. + It must contain at least one positive and one negative value. finance_rate : scalar - Interest rate paid on the cash flows + Interest rate paid on the cash flows. reinvest_rate : scalar - Interest rate received on the cash flows upon reinvestment + Interest rate received on the cash flows upon reinvestment. raise_exceptions: bool, optional - Flag to raise an exception when the mirr cannot be computed due to - having all cashflows of the same sign (NoRealSolutionException). - Set to False as default, thus returning NaNs in the previous - case. + Flag to raise an exception when the MIRR cannot be computed due to + having all cash flows of the same sign (NoRealSolutionException). + Set to False as default,thus returning NaNs in the previous case. Returns ------- out : float Modified internal rate of return + Notes + ----- + The MIRR formula is as follows: + + .. math:: + + MIRR = \\left( \\frac{{FV_{positive}}}{{PV_{negative}}} \\right)^{\\frac{{1}}{{n-1}}} + * (1+r) - 1 + + where: + - \(FV_{positive}\) is the future value of positive cash flows, + - \(PV_{negative}\) is the present value of negative cash flows, + - \(n\) is the number of periods. + - \(r\) is the reinvestment rate. + + Examples + -------- + >>> import numpy_financial as npf + + Consider a project with an initial investment of -$100 + and projected cash flows of $50, -$60, and $70 at the end of each period. + The project has a finance rate of 10% and a reinvestment rate of 12%. + + >>> npf.mirr([-100, 50, -60, 70], 0.10, 0.12) + -0.03909366594356467 + + Now, let's consider the scenario where all cash flows are negative. + + >>> npf.mirr([-100, -50, -60, -70], 0.10, 0.12) + nan + + Finally, let's explore the situation where all cash flows are positive, + and the `raise_exceptions` parameter is set to True. + + >>> npf.mirr([100, 50, 60, 70], 0.10, 0.12, raise_exceptions=True) + NoRealSolutionError: No real solution exists for MIRR since all + cashflows are of the same sign. + """ values = np.asarray(values) n = values.size From 4fa06edf4bea8dd3193dcfc6404e5430898b2772 Mon Sep 17 00:00:00 2001 From: RVitalii Date: Mon, 27 Nov 2023 11:35:12 +0100 Subject: [PATCH 3/3] Updating mirr docstring v3 [issue 76] --- numpy_financial/_financial.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/numpy_financial/_financial.py b/numpy_financial/_financial.py index 221dec5..50728d8 100644 --- a/numpy_financial/_financial.py +++ b/numpy_financial/_financial.py @@ -937,8 +937,9 @@ def mirr(values, finance_rate, reinvest_rate, *, raise_exceptions=False): .. math:: - MIRR = \\left( \\frac{{FV_{positive}}}{{PV_{negative}}} \\right)^{\\frac{{1}}{{n-1}}} - * (1+r) - 1 + MIRR = + \\left( \\frac{{FV_{positive}}}{{PV_{negative}}} \\right)^{\\frac{{1}}{{n-1}}} + * (1+r) - 1 where: - \(FV_{positive}\) is the future value of positive cash flows,