xirr
v1.1.0
Published
Compute the internal rate of return of a sequences of transactions made at irregular periods.
Downloads
23,149
Readme
Internal Rate of Return
The internal rate of return of an investment made at irregular intervals is the constant rate of return which would yield the equivalent value.
For example, suppose you purchased $1000 in a stock on January 15, then $2500 on February 8 and finally another $1000 on April 17. The value of the stock on August 24 is $5050. The internal rate of return could be computed by:
var xirr = require('xirr');
var rate = xirr([
{amount: -1000, when: new Date(2016, 0, 15)},
{amount: -2500, when: new Date(2016, 1, 8)},
{amount: -1000, when: new Date(2016, 3, 17)},
{amount: 5050, when: new Date(2016, 7, 24)},
]);
console.log(rate); // Prints 0.2504234710540838
This means annualized rate of return is 25.04%. That is, an equivalent investment would be a savings account of with an interest rate of 25.04%. (And if you happen to know of such a savings account, please let the author know immediately.)
This calculation can be used to compare disparate investments.
It doesn't converge?!
If your calculation doesn't converge, try defining different values for the guess
property in the options
argument. This is particularly likely to happen when the solution is near -1.
Pull requests with superior methods for determining the starting point for Newton's method are welcome.
API
require('xirr')(transactions [, options])
Given a sequence of transactions, computes the internal rate of return.
Parameters:
transations
: an array of objects with the following properties:amount
: the amount of the transactionwhen
: the Date when the transaction occurred
options
: Options to pass directly to the underlying Newton's method implementation,newton-raphson-method
. In addition, if theguess
property is defined, it will be used as the initial guess for the algorithm.
Returns: the annualized internal rate of return as a decimal in [-1,∞)
Throws:
- Error:
- when the
amount
s of the transactions are all the same sign - when there are fewer than two transactions
- when the transactions all occur on the same day (time is ignored)
- when the
newton-raphson-method
fails to converge
- when the
Implementation Details
To compute the irregular rate of return, you must find the constant rate of return which yields a present value of zero over the set of transactions. The present value of a transaction is determined by the formula A(1+r)Y, where A
is the amount
, Y
is the duration of the investment represented by the transaction in years and r
is the rate to solve for. The sum of the present values is the function for which we need to find the zero.
To find the zero of a function, we use Newton's method as implemented by the newton-raphson-method
module. To use Newton's method, we need the derivative of the present value with respect to r
. Fortunately this is easily determined using the power rule. The derivative is the sum of the terms AY(1+r)Y-1 for which Y
is not zero.
I had a very elegant proof of the above but unfortunately the margin is too small to contain it.