| 1 |
roi |
| 2 |
|
| 3 |
Shows the time-weighted (TWR) and money-weighted (IRR) rate of return on |
| 4 |
your investments. |
| 5 |
|
| 6 |
Flags: |
| 7 |
--cashflow show all amounts that were used to compute |
| 8 |
returns |
| 9 |
--investment=QUERY query to select your investment transactions |
| 10 |
--profit-loss=QUERY --pnl query to select profit-and-loss or |
| 11 |
appreciation/valuation transactions |
| 12 |
|
| 13 |
At a minimum, you need to supply a query (which could be just an account |
| 14 |
name) to select your investment(s) with --inv, and another query to |
| 15 |
identify your profit and loss transactions with --pnl. |
| 16 |
|
| 17 |
If you do not record changes in the value of your investment manually, |
| 18 |
or do not require computation of time-weighted return (TWR), --pnl could |
| 19 |
be an empty query (--pnl "" or --pnl STR where STR does not match any of |
| 20 |
your accounts). |
| 21 |
|
| 22 |
This command will compute and display the internalized rate of return |
| 23 |
(IRR, also known as money-weighted rate of return) and time-weighted |
| 24 |
rate of return (TWR) for your investments for the time period requested. |
| 25 |
IRR is always annualized due to the way it is computed, but TWR is |
| 26 |
reported both as a rate over the chosen reporting period and as an |
| 27 |
annual rate. |
| 28 |
|
| 29 |
Price directives will be taken into account if you supply appropriate |
| 30 |
--cost or --value flags (see VALUATION). |
| 31 |
|
| 32 |
Note, in some cases this report can fail, for these reasons: |
| 33 |
|
| 34 |
- Error (NotBracketed): No solution for Internal Rate of Return (IRR). |
| 35 |
Possible causes: IRR is huge (>1000000%), balance of investment |
| 36 |
becomes negative at some point in time. |
| 37 |
- Error (SearchFailed): Failed to find solution for Internal Rate of |
| 38 |
Return (IRR). Either search does not converge to a solution, or |
| 39 |
converges too slowly. |
| 40 |
|
| 41 |
Examples: |
| 42 |
|
| 43 |
- Using roi to compute total return of investment in stocks: |
| 44 |
https://github.com/simonmichael/hledger/blob/master/examples/investing/roi-unrealised.ledger |
| 45 |
|
| 46 |
- Cookbook > Return on Investment: https://hledger.org/roi.html |
| 47 |
|
| 48 |
Spaces and special characters in --inv and --pnl |
| 49 |
|
| 50 |
Note that --inv and --pnl's argument is a query, and queries could have |
| 51 |
several space-separated terms (see QUERIES). |
| 52 |
|
| 53 |
To indicate that all search terms form single command-line argument, you |
| 54 |
will need to put them in quotes (see Special characters): |
| 55 |
|
| 56 |
$ hledger roi --inv 'term1 term2 term3 ...' |
| 57 |
|
| 58 |
If any query terms contain spaces themselves, you will need an extra |
| 59 |
level of nested quoting, eg: |
| 60 |
|
| 61 |
$ hledger roi --inv="'Assets:Test 1'" --pnl="'Equity:Unrealized Profit and Loss'" |
| 62 |
|
| 63 |
Semantics of --inv and --pnl |
| 64 |
|
| 65 |
Query supplied to --inv has to match all transactions that are related |
| 66 |
to your investment. Transactions not matching --inv will be ignored. |
| 67 |
|
| 68 |
In these transactions, ROI will conside postings that match --inv to be |
| 69 |
"investment postings" and other postings (not matching --inv) will be |
| 70 |
sorted into two categories: "cash flow" and "profit and loss", as ROI |
| 71 |
needs to know which part of the investment value is your contributions |
| 72 |
and which is due to the return on investment. |
| 73 |
|
| 74 |
- "Cash flow" is depositing or withdrawing money, buying or selling |
| 75 |
assets, or otherwise converting between your investment commodity and |
| 76 |
any other commodity. Example: |
| 77 |
|
| 78 |
2019-01-01 Investing in Snake Oil |
| 79 |
assets:cash -$100 |
| 80 |
investment:snake oil |
| 81 |
|
| 82 |
2020-01-01 Selling my Snake Oil |
| 83 |
assets:cash $10 |
| 84 |
investment:snake oil = 0 |
| 85 |
|
| 86 |
- "Profit and loss" is change in the value of your investment: |
| 87 |
|
| 88 |
2019-06-01 Snake Oil falls in value |
| 89 |
investment:snake oil = $57 |
| 90 |
equity:unrealized profit or loss |
| 91 |
|
| 92 |
All non-investment postings are assumed to be "cash flow", unless they |
| 93 |
match --pnl query. Changes in value of your investment due to "profit |
| 94 |
and loss" postings will be considered as part of your investment return. |
| 95 |
|
| 96 |
Example: if you use --inv snake --pnl equity:unrealized, then postings |
| 97 |
in the example below would be classifed as: |
| 98 |
|
| 99 |
2019-01-01 Snake Oil #1 |
| 100 |
assets:cash -$100 ; cash flow posting |
| 101 |
investment:snake oil ; investment posting |
| 102 |
|
| 103 |
2019-03-01 Snake Oil #2 |
| 104 |
equity:unrealized pnl -$100 ; profit and loss posting |
| 105 |
snake oil ; investment posting |
| 106 |
|
| 107 |
2019-07-01 Snake Oil #3 |
| 108 |
equity:unrealized pnl ; profit and loss posting |
| 109 |
cash -$100 ; cash flow posting |
| 110 |
snake oil $50 ; investment posting |
| 111 |
|
| 112 |
IRR and TWR explained |
| 113 |
|
| 114 |
"ROI" stands for "return on investment". Traditionally this was computed |
| 115 |
as a difference between current value of investment and its initial |
| 116 |
value, expressed in percentage of the initial value. |
| 117 |
|
| 118 |
However, this approach is only practical in simple cases, where |
| 119 |
investments receives no in-flows or out-flows of money, and where rate |
| 120 |
of growth is fixed over time. For more complex scenarios you need |
| 121 |
different ways to compute rate of return, and this command implements |
| 122 |
two of them: IRR and TWR. |
| 123 |
|
| 124 |
Internal rate of return, or "IRR" (also called "money-weighted rate of |
| 125 |
return") takes into account effects of in-flows and out-flows, and the |
| 126 |
time between them. Investment at a particular fixed interest rate is |
| 127 |
going to give you more interest than the same amount invested at the |
| 128 |
same interest rate, but made later in time. If you are withdrawing from |
| 129 |
your investment, your future gains would be smaller (in absolute |
| 130 |
numbers), and will be a smaller percentage of your initial investment, |
| 131 |
so your IRR will be smaller. And if you are adding to your investment, |
| 132 |
you will receive bigger absolute gains, which will be a bigger |
| 133 |
percentage of your initial investment, so your IRR will be larger. |
| 134 |
|
| 135 |
As mentioned before, in-flows and out-flows would be any cash that you |
| 136 |
personally put in or withdraw, and for the "roi" command, these are the |
| 137 |
postings that match the query in the--inv argument and NOT match the |
| 138 |
query in the--pnl argument. |
| 139 |
|
| 140 |
If you manually record changes in the value of your investment as |
| 141 |
transactions that balance them against "profit and loss" (or "unrealized |
| 142 |
gains") account or use price directives, then in order for IRR to |
| 143 |
compute the precise effect of your in-flows and out-flows on the rate of |
| 144 |
return, you will need to record the value of your investement on or |
| 145 |
close to the days when in- or out-flows occur. |
| 146 |
|
| 147 |
In technical terms, IRR uses the same approach as computation of net |
| 148 |
present value, and tries to find a discount rate that makes net present |
| 149 |
value of all the cash flows of your investment to add up to zero. This |
| 150 |
could be hard to wrap your head around, especially if you haven't done |
| 151 |
discounted cash flow analysis before. Implementation of IRR in hledger |
| 152 |
should produce results that match the =XIRR formula in Excel. |
| 153 |
|
| 154 |
Second way to compute rate of return that roi command implements is |
| 155 |
called "time-weighted rate of return" or "TWR". Like IRR, it will |
| 156 |
account for the effect of your in-flows and out-flows, but unlike IRR it |
| 157 |
will try to compute the true rate of return of the underlying asset, |
| 158 |
compensating for the effect that deposits and withdrawas have on the |
| 159 |
apparent rate of growth of your investment. |
| 160 |
|
| 161 |
TWR represents your investment as an imaginary "unit fund" where |
| 162 |
in-flows/ out-flows lead to buying or selling "units" of your investment |
| 163 |
and changes in its value change the value of "investment unit". Change |
| 164 |
in "unit price" over the reporting period gives you rate of return of |
| 165 |
your investment, and make TWR less sensitive than IRR to the effects of |
| 166 |
cash in-flows and out-flows. |
| 167 |
|
| 168 |
References: |
| 169 |
|
| 170 |
- Explanation of rate of return |
| 171 |
- Explanation of IRR |
| 172 |
- Explanation of TWR |
| 173 |
- IRR vs TWR |
| 174 |
- Examples of computing IRR and TWR and discussion of the limitations of |
| 175 |
both metrics |