;update CLI usage texts
This commit is contained in:
Simon Michael
parent
d53dc46a5a
commit
0295be5553
@ -17,10 +17,234 @@ At a minimum, you need to supply a query (which could be just an account
|
|||||||
name) to select your investments with --inv, and another query to
|
name) to select your investments with --inv, and another query to
|
||||||
identify your profit and loss transactions with --pnl.
|
identify your profit and loss transactions with --pnl.
|
||||||
|
|
||||||
It will compute and display the internalized rate of return (IRR) and
|
This command will compute and display the internalized rate of return
|
||||||
time-weighted rate of return (TWR) for your investments for the time
|
(IRR) and time-weighted rate of return (TWR) for your investments for
|
||||||
period requested. Both rates of return are annualized before display,
|
the time period requested. Both rates of return are annualized before
|
||||||
regardless of the length of reporting interval.
|
display, regardless of the length of reporting interval.
|
||||||
|
|
||||||
An example:
|
Note, in some cases this report can fail, for these reasons:
|
||||||
https://github.com/simonmichael/hledger/blob/master/examples/roi-unrealised.ledger
|
|
||||||
|
- Error (NotBracketed): No solution for Internal Rate of Return (IRR).
|
||||||
|
Possible causes: IRR is huge (>1000000%), balance of investment
|
||||||
|
becomes negative at some point in time.
|
||||||
|
- Error (SearchFailed): Failed to find solution for Internal Rate of
|
||||||
|
Return (IRR). Either search does not converge to a solution, or
|
||||||
|
converges too slowly.
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
|
||||||
|
- Using roi to report unrealised gains:
|
||||||
|
https://github.com/simonmichael/hledger/blob/master/examples/roi-unrealised.ledger
|
||||||
|
|
||||||
|
More background:
|
||||||
|
|
||||||
|
"ROI" stands for "return on investment". Traditionally this was computed
|
||||||
|
as a difference between current value of investment and its initial
|
||||||
|
value, expressed in percentage of the initial value.
|
||||||
|
|
||||||
|
However, this approach is only practical in simple cases, where
|
||||||
|
investments receives no in-flows or out-flows of money, and where rate
|
||||||
|
of growth is fixed over time. For more complex scenarios you need
|
||||||
|
different ways to compute rate of return, and this command implements
|
||||||
|
two of them: IRR and TWR.
|
||||||
|
|
||||||
|
Internal rate of return, or "IRR" (also called "money-weighted rate of
|
||||||
|
return") takes into account effects of in-flows and out-flows. Naively,
|
||||||
|
if you are withdrawing from your investment, your future gains would be
|
||||||
|
smaller (in absolute numbers), and will be a smaller percentage of your
|
||||||
|
initial investment, and if you are adding to your investment, you will
|
||||||
|
receive bigger absolute gains (but probably at the same rate of return).
|
||||||
|
IRR is a way to compute rate of return for each period between in-flow
|
||||||
|
or out-flow of money, and then combine them in a way that gives you an
|
||||||
|
annual rate of return that investment is expected to generate.
|
||||||
|
|
||||||
|
As mentioned before, in-flows and out-flows would be any cash that you
|
||||||
|
personally put in or withdraw, and for the "roi" command, these are
|
||||||
|
transactions that involve account(s) matching --inv argument and NOT
|
||||||
|
involve account(s) matching --pnl argument.
|
||||||
|
|
||||||
|
Presumably, you will also record changes in the value of your
|
||||||
|
investment, and balance them against "profit and loss" (or "unrealized
|
||||||
|
gains") account. Note that in order for IRR to compute the precise
|
||||||
|
effect of your in-flows and out-flows on the rate of return, you will
|
||||||
|
need to record the value of your investement on or close to the days
|
||||||
|
when in- or out-flows occur.
|
||||||
|
|
||||||
|
Implementation of IRR in hledger should match the XIRR formula in Excel.
|
||||||
|
|
||||||
|
Second way to compute rate of return that roi command implements is
|
||||||
|
called "time-weighted rate of return" or "TWR". Like IRR, it will also
|
||||||
|
break the history of your investment into periods between in-flows and
|
||||||
|
out-flows to compute rate of return per each period and then a compound
|
||||||
|
rate of return. However, internal workings of TWR are quite different.
|
||||||
|
|
||||||
|
In technical terms, IRR uses the same approach as computation of net
|
||||||
|
present value, and tries to find a discount rate that makes net present
|
||||||
|
value of all the cash flows of your investment to add up to zero. This
|
||||||
|
could be hard to wrap your head around, especially if you haven't done
|
||||||
|
discounted cash flow analysis before.
|
||||||
|
|
||||||
|
TWR represents your investment as an imaginary "unit fund" where
|
||||||
|
in-flows/ out-flows lead to buying or selling "units" of your investment
|
||||||
|
and changes in its value change the value of "investment unit". Change
|
||||||
|
in "unit price" over the reporting period gives you rate of return of
|
||||||
|
your investment.
|
||||||
|
|
||||||
|
References: * Explanation of rate of return * Explanation of IRR *
|
||||||
|
Explanation of TWR * Examples of computing IRR and TWR and discussion of
|
||||||
|
the limitations of both metrics
|
||||||
|
|
||||||
|
More examples:
|
||||||
|
|
||||||
|
Lets say that we found an investment in Snake Oil that is proising to
|
||||||
|
give us 10% annually:
|
||||||
|
|
||||||
|
2019-01-01 Investing in Snake Oil
|
||||||
|
assets:cash -$100
|
||||||
|
investment:snake oil
|
||||||
|
|
||||||
|
2019-12-24 Recording the growth of Snake Oil
|
||||||
|
investment:snake oil = $110
|
||||||
|
equity:unrealized gains
|
||||||
|
|
||||||
|
For now, basic computation of the rate of return, as well as IRR and
|
||||||
|
TWR, gives us the expected 10%:
|
||||||
|
|
||||||
|
$ hledger roi -Y --inv investment --pnl "unrealized"
|
||||||
|
+---++------------+------------++---------------+----------+-------------+-----++--------+--------+
|
||||||
|
| || Begin | End || Value (begin) | Cashflow | Value (end) | PnL || IRR | TWR |
|
||||||
|
+===++============+============++===============+==========+=============+=====++========+========+
|
||||||
|
| 1 || 2019-01-01 | 2019-12-31 || 0 | 100 | 110 | 10 || 10.00% | 10.00% |
|
||||||
|
+---++------------+------------++---------------+----------+-------------+-----++--------+--------+
|
||||||
|
|
||||||
|
However, lets say that shorty after investing in the Snake Oil we
|
||||||
|
started to have second thoughs, so we prompty withdrew $90, leaving only
|
||||||
|
$10 in. Before Christmas, though, we started to get the "fear of mission
|
||||||
|
out", so we put the $90 back in. So for most of the year, our investment
|
||||||
|
was just $10 dollars, and it gave us just $1 in growth:
|
||||||
|
|
||||||
|
2019-01-01 Investing in Snake Oil
|
||||||
|
assets:cash -$100
|
||||||
|
investment:snake oil
|
||||||
|
|
||||||
|
2019-01-02 Buyers remorse
|
||||||
|
assets:cash $90
|
||||||
|
investment:snake oil
|
||||||
|
|
||||||
|
2019-12-30 Fear of missing out
|
||||||
|
assets:cash -$90
|
||||||
|
investment:snake oil
|
||||||
|
|
||||||
|
2019-12-31 Recording the growth of Snake Oil
|
||||||
|
investment:snake oil = $101
|
||||||
|
equity:unrealized gains
|
||||||
|
|
||||||
|
Now IRR and TWR are drastically different:
|
||||||
|
|
||||||
|
$ hledger roi -Y --inv investment --pnl "unrealized"
|
||||||
|
+---++------------+------------++---------------+----------+-------------+-----++-------+-------+
|
||||||
|
| || Begin | End || Value (begin) | Cashflow | Value (end) | PnL || IRR | TWR |
|
||||||
|
+===++============+============++===============+==========+=============+=====++=======+=======+
|
||||||
|
| 1 || 2019-01-01 | 2019-12-31 || 0 | 100 | 101 | 1 || 9.32% | 1.00% |
|
||||||
|
+---++------------+------------++---------------+----------+-------------+-----++-------+-------+
|
||||||
|
|
||||||
|
Here, IRR tells us that we made close to 10% on the $10 dollars that we
|
||||||
|
had in the account most of the time. And TWR is ... just 1%? Why?
|
||||||
|
|
||||||
|
Based on the transactions in our journal, TWR "think" that we are buying
|
||||||
|
back $90 worst of Snake Oil at the same price that it had at the
|
||||||
|
beginning of they year, and then after that our $100 investment gets $1
|
||||||
|
increase in value, or 1% of $100. Let's take a closer look at what is
|
||||||
|
happening here by asking for quarterly reports instead of annual:
|
||||||
|
|
||||||
|
$ hledger roi -Q --inv investment --pnl "unrealized"
|
||||||
|
+---++------------+------------++---------------+----------+-------------+-----++--------+-------+
|
||||||
|
| || Begin | End || Value (begin) | Cashflow | Value (end) | PnL || IRR | TWR |
|
||||||
|
+===++============+============++===============+==========+=============+=====++========+=======+
|
||||||
|
| 1 || 2019-01-01 | 2019-03-31 || 0 | 10 | 10 | 0 || 0.00% | 0.00% |
|
||||||
|
| 2 || 2019-04-01 | 2019-06-30 || 10 | 0 | 10 | 0 || 0.00% | 0.00% |
|
||||||
|
| 3 || 2019-07-01 | 2019-09-30 || 10 | 0 | 10 | 0 || 0.00% | 0.00% |
|
||||||
|
| 4 || 2019-10-01 | 2019-12-31 || 10 | 90 | 101 | 1 || 37.80% | 4.03% |
|
||||||
|
+---++------------+------------++---------------+----------+-------------+-----++--------+-------+
|
||||||
|
|
||||||
|
Now both IRR and TWR are thrown off by the fact that all of the growth
|
||||||
|
for our investment happens in Q4 2019. This happes because IRR
|
||||||
|
computation is still yielding 9.32% and TWR is still 1%, but this time
|
||||||
|
these are rates for three month period instead of twelve, so in order to
|
||||||
|
get an annual rate they should be multiplied by four!
|
||||||
|
|
||||||
|
Let's try to keep a better record of how Snake Oil grew in value:
|
||||||
|
|
||||||
|
2019-01-01 Investing in Snake Oil
|
||||||
|
assets:cash -$100
|
||||||
|
investment:snake oil
|
||||||
|
|
||||||
|
2019-01-02 Buyers remorse
|
||||||
|
assets:cash $90
|
||||||
|
investment:snake oil
|
||||||
|
|
||||||
|
2019-02-28 Recording the growth of Snake Oil
|
||||||
|
investment:snake oil
|
||||||
|
equity:unrealized gains -$0.25
|
||||||
|
|
||||||
|
2019-06-30 Recording the growth of Snake Oil
|
||||||
|
investment:snake oil
|
||||||
|
equity:unrealized gains -$0.25
|
||||||
|
|
||||||
|
2019-09-30 Recording the growth of Snake Oil
|
||||||
|
investment:snake oil
|
||||||
|
equity:unrealized gains -$0.25
|
||||||
|
|
||||||
|
2019-12-30 Fear of missing out
|
||||||
|
assets:cash -$90
|
||||||
|
investment:snake oil
|
||||||
|
|
||||||
|
2019-12-31 Recording the growth of Snake Oil
|
||||||
|
investment:snake oil
|
||||||
|
equity:unrealized gains -$0.25
|
||||||
|
|
||||||
|
Would our quartery report look better now? Almost:
|
||||||
|
|
||||||
|
$ hledger roi -Q --inv investment --pnl "unrealized"
|
||||||
|
+---++------------+------------++---------------+----------+-------------+------++--------+--------+
|
||||||
|
| || Begin | End || Value (begin) | Cashflow | Value (end) | PnL || IRR | TWR |
|
||||||
|
+===++============+============++===============+==========+=============+======++========+========+
|
||||||
|
| 1 || 2019-01-01 | 2019-03-31 || 0 | 10 | 10.25 | 0.25 || 9.53% | 10.53% |
|
||||||
|
| 2 || 2019-04-01 | 2019-06-30 || 10.25 | 0 | 10.50 | 0.25 || 10.15% | 10.15% |
|
||||||
|
| 3 || 2019-07-01 | 2019-09-30 || 10.50 | 0 | 10.75 | 0.25 || 9.79% | 9.78% |
|
||||||
|
| 4 || 2019-10-01 | 2019-12-31 || 10.75 | 90 | 101.00 | 0.25 || 8.05% | 1.00% |
|
||||||
|
+---++------------+------------++---------------+----------+-------------+------++--------+--------+
|
||||||
|
|
||||||
|
Something is still wrong with TWR computation for Q4, and if you have
|
||||||
|
been paying attention you know what it is already: big $90 buy-back is
|
||||||
|
recorded prior to the only transaction that captures the change of value
|
||||||
|
of Snake Oil that happened in this time period. Lets combine
|
||||||
|
transactions from 30th and 31st of Dec into one:
|
||||||
|
|
||||||
|
2019-12-30 Fear of missing out and growth of Snake Oil
|
||||||
|
assets:cash -$90
|
||||||
|
investment:snake oil
|
||||||
|
equity:unrealized gains -$0.25
|
||||||
|
|
||||||
|
Now growth of investment properly affects its price at the time of
|
||||||
|
buy-back:
|
||||||
|
|
||||||
|
$ hledger roi -Q --inv investment --pnl "unrealized"
|
||||||
|
+---++------------+------------++---------------+----------+-------------+------++--------+--------+
|
||||||
|
| || Begin | End || Value (begin) | Cashflow | Value (end) | PnL || IRR | TWR |
|
||||||
|
+===++============+============++===============+==========+=============+======++========+========+
|
||||||
|
| 1 || 2019-01-01 | 2019-03-31 || 0 | 10 | 10.25 | 0.25 || 9.53% | 10.53% |
|
||||||
|
| 2 || 2019-04-01 | 2019-06-30 || 10.25 | 0 | 10.50 | 0.25 || 10.15% | 10.15% |
|
||||||
|
| 3 || 2019-07-01 | 2019-09-30 || 10.50 | 0 | 10.75 | 0.25 || 9.79% | 9.78% |
|
||||||
|
| 4 || 2019-10-01 | 2019-12-31 || 10.75 | 90 | 101.00 | 0.25 || 8.05% | 9.57% |
|
||||||
|
+---++------------+------------++---------------+----------+-------------+------++--------+--------+
|
||||||
|
|
||||||
|
And for annual report, TWR now reports the exact profitability of our
|
||||||
|
investment:
|
||||||
|
|
||||||
|
$ hledger roi -Y --inv investment --pnl "unrealized"
|
||||||
|
+---++------------+------------++---------------+----------+-------------+------++-------+--------+
|
||||||
|
| || Begin | End || Value (begin) | Cashflow | Value (end) | PnL || IRR | TWR |
|
||||||
|
+===++============+============++===============+==========+=============+======++=======+========+
|
||||||
|
| 1 || 2019-01-01 | 2019-12-31 || 0 | 100 | 101.00 | 1.00 || 9.32% | 10.00% |
|
||||||
|
+---++------------+------------++---------------+----------+-------------+------++-------+--------+
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user