See also the time value of money for other related Matlab functions.
Download
nfvFlow.m
Introduction
The future value (FV) of a single lump sum of cash is its present value (PV, its value right now) plus interest earned over a period of time. The future value of a cash flow is the sum of the FVs of the money received (or spent) at each time period. As each time periods go by, the amount of periods over which a subsequent income can potentially earn interest reduces.
For an introduction to future values and simple and compound interest, and a simple Matlab function for calculating the future value of a lump sum, see this post.
nfvFlow.m is an alternative to Matlab's fvvar function in the financial toolbox. nfvFlow includes a flag that allows interest payments to be made in advance or in arrears (intPaid=1 for advance, or =0 for arrears). Payments (payments) and periods (periods) can be explicitly specified, or entered as a single value if regular (see below for examples). The interest rate (rate) should be a decimal value, not a percentage. The outputs give the overall net future value of the cash flow (nfv) and the future value of each payment made at each time point (fvAtPeriod).
[nfv, fvAtPeriod]= nfvFlow(payments, rate, periods, intPaid)
For example, for a regular payment of £2000, over 4 periods with a rate of 5% and interest paid at the end of time periods (see first example below for details):
[nfv, fvAtPeriod] = nfvFlow(2000, 0.05, 4, 0).
Regular payments
Imagine your savings account. You can save £2000 a year, how much will you have saved over 4 years, assuming a compounding annual interest rate of 5% and that interest is paid yearly? Note that you pay £2000 in to your account at the start of each year, and the interest is paid at the end of the year.
The equation to work out the FV of a lump sum is with compounding interest is
FV = PV * (1+r)^n,
where r = interest rate, n = number of time periods over which the money will earn interest and PV = the present value at the current time period. We need to work out the future value of each time period, then sum them. In this case remember that the interest will be paid at the end of the time period.
There are 4 years and hence 4 time periods to consider, starting from now, which is t=0, not t=1! The £2000 is invested at time t=0, and the first interest payment will be at t=1. This means the first £2000 will earn interest at t=1, t=2 and t=3. That's 3 time periods of interest it will earn over the 4 years, hence for this FV calculation, n1=3. The second £2000 will be paid at t=1 and will first earn interest at t=2. It will then also earn interest at t=3, meaning it earns interest at 2 of the time periods, so n2=3. The final £2000 will be paid at t=3 and will not earn interest until t=4, which is in 5 years time, so not relevant to the question.
FV of payment 1 = 2000 + interest at t=1, 2, 3 = 2000 * (1+0.05)^3 = £2315
FV of payment 2 = 2000 + interest at t=2, 3 = 2000 * (1+0.05)^2 = £2205
FV of payment 3 = 2000 + interest at t=3 = 2000 * (1+0.05)^1 = £2100
FV of payment 4 = 2000 + no interest = 2000 * (1+0.05)^0 = £2000
FV of the cash flow = 2315 + 2205 + 2100 + 2000 = £8620.
Therefore in 4 years time, your savings account will contain £8620. Using npvFlow, this question could be answered with the following code:
nfvFlow(2000, 0.05, 4, 0), or
nfvFlow([2000 2000 2000 2000], 0.05, [0 1 2 3], 0).
For completeness, let's also consider a case where the interest on payments is paid at the same time as the corresponding investment. This would be unusual for a savings account - it would mean that as soon as you put the first £2000 into your account, you would receive interest on it; ie. the first interest payment for the money put in the account at t=0 would occur at t=0 also. In the time period 0 to 3, it would earn interest at t=0, t=1, t=2, and t=3, which is 4 time periods (n=4 compared instead of n=3). Similarly for the second £2000 invested at t=1, the money earns interest for an additional time period; at t=1, t=2, and t=3 (n=3 compared to n=2). Overall, the calculations change as follows:
FV of payment 1 = 2000 + interest at t=0, 1, 2, 3 = 2000 * (1+0.05)^4 = £2431
FV of payment 2 = 2000 + interest at t=1, 2, 3 = 2000 * (1+0.05)^3 = £2315
FV of payment 3 = 2000 + interest at t=2, 3 = 2000 * (1+0.05)^2 = £2205
FV of payment 4 = 2000 + interest at t=3 = 2000 * (1+0.05)^1 = £2100
FV of the cash flow = 2431 + 2315 + 2205 + 2100 = £9051.
And the Matlab code would be basically the same, but with the last input (intPaid) =0, to tell nfvFlow to use advanced interest payments in its calculation.
nfvFlow(2000, 0.05, 4, 1), or
nfvFlow([2000 2000 2000 2000], 0.05, [0 1 2 3], 1).
Irregular flows
The FV of an irregular cash flow is calculated in exactly the same way as for a regular flow. For example, imagine you can buy an investment for £1000, that will return £700 after 1 year and £500 after 2 years. How much money will you have in 3 years time if the interest rate is 5% annually, but paid every 6 months?
This means the interest rate at each payment period is effectively 0.05%/12months * 6 months. Or simply, 0.05/2.
The timeline is as follows:
t=0 = £-1000
t=1 = £0 (remember, 6 month periods and payout is every 12 months)
t=2 = £700
t=3 = £0
t=4 = £500
FV of payment 1 @ t=0
= -1000 + lost interest at t=1, 2, 3, 4 = -1000 * (1+0.05/2)^4 = £-1104
FV of payment 2 @ t=2
= 700 + interest at t=3, 4 = 700 * (1+0.05/2)^2 = £735
FV of payment 3 @ t=4
= 500 + no interest = 500 * (1+0.05/2)^0 = £500
FV of the cash flow = -1104 + 735 + 500 = £131
Using nfvFlow, the periods/payments can be entered in two ways:
nfvFlow([-1000 0 700 0 500], 0.05/2, 5, 0), or
nfvFlow([-1000 700 500], 0.05/2, [0 2 4], 0).
Code run-through
function [nfv, fvAtPeriod]= nfvFlow(payments, rate, periods, intPaid)
nfvFlow takes 4 inputs: payments which can be a vector containing a cash flow, or just a single number if the cash flow is regular. rate, the decimal interest rate. periods, which can either be the number of periods, or a vector of periods, if irregular. intPaid is used to indicate if the interest should be credited in advance (=1) or in arrears (=0). If unsure about this, see the examples above, paying interest in arrears is more normal for savings accounts.
if isscalar(periods)
% Regular periods assumed
t = 0:periods-1;
else
% Vector of periods provided - should be same length of vector of
% payments already supplied/defined
t = periods;
end
First the function checks if periods has been input as a scaler or a vector using the isscalar function. If it is a scaler (eg. 3) it should be the number of periods, so it creates a vector of 1:number of periods (eg. [1, 2, 3]). If periods is already a vector then nothing is changed (it's just copied in to another variable, t, to reduce typing in the rest of the function).
if isscalar(payments);
% Payment is constant for each period
c = zeros(1,length(t));
c = c+payments;
else
% Vector of payments provided
c = payments;
end
Next the input payments is checked. If payments a scaler, the payment is assumed to be the same at each time period, and a vector is created with the payment for each time period (eg, if payments = 20 and periods = [1,2,3], then c = [20, 20, 20]).
if numel(c)~=numel(t)
disp('Error: Payment or period missing.')
return
end
r=rate;
At this point there's a check to make sure t and c are both the same length. They should be vectors of the same length at this point (or both scalers if there's only one period). If they aren't the same length an error is displayed indicating that there was an error with the inputs supplied to the function, The return command then exits the function and returns control to the command window (or the calling function, if applicable).
% Calculate
n=t(end:-1:1) + intPaid;
The vector t is reversed by being accessed with the index end:-1:1. This extracts the values from t starting with the last ("end") value, and continuing in steps of -1 to the first value, and stores them in n. This is because t contains an vector of time periods, for example, [0, 1, 2], but in the calculation we want to use the number of time periods over which each element of the cash flow can earn interest. If there's a total of 3 time periods, this means the first payment in the cash flow can earn interest at 2 or 3 periods depending on when the interest is paid. When intPaid=1 (advanced interest) this adds 1 to the number of time periods over which a payment can earn interest (see first example above). When intPaid=0, there's no shift, so t=[0, 1, 2] becomes n=[2, 1, 0].
fvPeriod = c .* (1+r).^n ;
nfv=sum(fvPeriod);
fvAtPeriod = [t', fvPeriod'];
Finally the calculation is done. Note that there's no loop, it works vector inputs (t and c) and gives a vector output (fvPeriod). Matlab does the calculation on each element of the vectors in turn (note the . before the * and ^ that denotes element-wise operations), in exactly the same way as if the process was implemented in a loop, just with less faffing. The sum of the fvPeriod vector gives the overall net future value of the cash flow and returns it in nfv. If requested, the future values at each period are also returned in fvAtPeriod(:,2), along with the time periods in fvAtPeriods(:,1).
No comments:
Post a Comment