add `XFV` function

[yonil7]

Add XFV function or add description on how it can be calculated using the existing XIRR and XNPV

[Anexen]

Hi, @yonil7. I did some search and didn't find a good description of XFV function. Could you, please, describe your input data? Did you just mean a FV of uneven Cash Flows?

The useful links I found so far:

• http://westclintech.com/SQL-Server-Financial-Functions/SQL-Server-XFV-function
• http://www.teachmefinance.com/futurevalueofanunevencashflow.html
• https://www.youtube.com/watch?v=775ljhriB8U Hope this help.

I can implement XFV and XNFV from the first article if it suites your needs.

[yonil7]

Hi @Anexen. Yes I meant the equivalent of FV for uneven cash flows. (as we have XIRR that eXtends IRR and XNPV that eXtends NPV)

[Anexen]

@yonil7 , according to this video, the logic is pretty simple:

1. Calculate Present Value using (X)NPV and the interest rate: NPV for regular cash flows, XNPV for irregular cash flows. The negative values are "deposits", the positive values are "income".

2. Use the calculated present value in FV function.

Here is an example:

from pyxirr import xnpv, fv

interest_rate = <interest rate>
periods = <compound periods>
cash_flows = <your input is here>
net_present_value = xnpv(interest_rate, cash_flows)  # discount_rate = interest_rate
# pv must be negative
fv(interest_rate, periods, pmt=0, pv=-net_present_value)

[Anexen]

I believe we should distinguish XFV and XNFV functions. The first one (XFV) should work with uneven payments and regular periods. The second one (XNFV) should work with uneven payments and irregular periods. @yonil7 , what do you think?

[yonil7]

For consistency, we can have "regular" functions set (IRR, NPV, FV) and "extended" functions set (XIRR, XNPV, XFV)

The "regular" functions set gets the cash flow series by 2 scalars:

nper: int, # Number of compounding periods
pmt: Amount, # Payment

The "extended" functions set gets the cash flow series by 1 or 2 iterables:

amounts # mandatory. iterable or dict-like
dates # optional. iterable

• In case dates iterable is not passed the function will use "regular periods"
• For passing these 2 iterables by single argument instead of passing 2 arguments, the user can pass dict or a pd.Series (or any other dict-like object) to amounts (in this case dates will be ignored)

[Anexen]

@yonil7 added XFV function in 0.6 release. Docs. If you have an idea for improvement or you encounter a bug, please create a new issue.