Debian Codegraph @

Hledger/Cli/Commands/Roi.txt

raw
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