Debian Codegraph @

Hledger/Cli/Commands/Roi.hs

raw
1 {-# LANGUAGE OverloadedStrings #-}
2 {-# LANGUAGE ParallelListComp #-}
3 {-# LANGUAGE TemplateHaskell #-}
4 {-# LANGUAGE TupleSections #-}
5 {-# LANGUAGE RecordWildCards #-}
6 {-# LANGUAGE ViewPatterns #-}
7 {-|
8
9 The @roi@ command prints internal rate of return and time-weighted rate of return for and investment.
10
11 -}
12
13 module Hledger.Cli.Commands.Roi (
14 roimode
15 , roi
16 ) where
17
18 import Control.Monad
19 import Data.Time.Calendar
20 import Text.Printf
21 import Data.Bifunctor (second)
22 import Data.Function (on)
23 import Data.List
24 import Numeric.RootFinding
25 import Data.Decimal
26 import Data.Set qualified as S
27 import Data.Text qualified as T
28 import Data.Text.Lazy.IO qualified as TL
29 import Safe (headDef)
30 import System.Console.CmdArgs.Explicit as CmdArgs
31
32 import Text.Tabular.AsciiWide as Tab
33
34 import Hledger
35 import Hledger.Cli.CliOptions
36
37
38 roimode = hledgerCommandMode
39 $(embedFileRelative "Hledger/Cli/Commands/Roi.txt")
40 [flagNone ["cashflow"] (setboolopt "cashflow") "show all amounts that were used to compute returns"
41 ,flagReq ["investment"] (\s opts -> Right $ setopt "investment" s opts) "QUERY"
42 "query to select your investment transactions"
43 ,flagReq ["profit-loss","pnl"] (\s opts -> Right $ setopt "pnl" s opts) "QUERY"
44 "query to select profit-and-loss or appreciation/valuation transactions"
45 ]
46 cligeneralflagsgroups1
47 hiddenflags
48 ([], Just $ argsFlag "[QUERY]")
49
50 -- One reporting span,
51 data OneSpan = OneSpan
52 Day -- start date, inclusive
53 Day -- end date, exclusive
54 MixedAmount -- value of investment at the beginning of day on spanBegin_
55 MixedAmount -- value of investment at the end of day on spanEnd_
56 [(Day,MixedAmount)] -- all deposits and withdrawals (but not changes of value) in the DateSpan [spanBegin_,spanEnd_)
57 [(Day,MixedAmount)] -- all PnL changes of the value of investment in the DateSpan [spanBegin_,spanEnd_)
58 deriving (Show)
59
60
61 roi :: CliOpts -> Journal -> IO ()
62 roi CliOpts{rawopts_=rawopts, reportspec_=rspec@ReportSpec{_rsReportOpts=ReportOpts{..}}} j = do
63 -- We may be converting posting amounts to value, per hledger_options.m4.md "Effect of --value on reports".
64 let
65 -- lbl = lbl_ "roi"
66 today = _rsDay rspec
67 priceOracle = journalPriceOracle infer_prices_ j
68 styles = journalCommodityStylesWith HardRounding j
69 mixedAmountValue periodlast date =
70 -- These calculations can generate very precise decimals. To avoid showing too many digits:
71 -- If we have no style for the valuation commodity, generate one that will limit the precision ?
72 -- But it's not easy to find out the valuation commodity (or commodities) here if it's implicit,
73 -- as that information is buried in the price graph.
74 -- Instead, do what we don't like to do: hard code a max precision, overriding commodity styles.
75 mixedAmountSetPrecisionMax defaultMaxPrecision
76 . maybe id (mixedAmountApplyValuation priceOracle styles periodlast today date) value_
77 . maybe id (mixedAmountToCost styles) conversionop_
78
79 let
80 ropts = _rsReportOpts rspec
81 wd = whichDate ropts
82 showCashFlow = boolopt "cashflow" rawopts
83 prettyTables = pretty_
84 makeQuery flag = do
85 q <- either usageError (return . fst) . parseQuery today . T.pack $ stringopt flag rawopts
86 return . simplifyQuery $ And [queryFromFlags ropts{period_=PeriodAll}, q]
87 cantCompute msg = error' $ msg ++ " - will be unable to compute the rates of return"
88
89 investmentsQuery <- makeQuery "investment"
90 pnlQuery <- makeQuery "pnl"
91
92 when (pnlQuery == Any) $
93 cantCompute "Need some transactions classed as investment and not pnl, but the pnl query matches any transaction"
94
95 let
96 filteredj = filterJournalTransactions investmentsQuery j
97 trans = dbg3 "investments" $ jtxns filteredj
98
99 when (null trans) $
100 error' "No relevant transactions found. Check your investments query"
101
102 let (fullPeriodDateSpan, mspans) = reportSpan filteredj rspec
103
104 let err = cantCompute "Undefined start or end of the period"
105 spans = maybe err (map (second (addDays 1)) . dayPartitionToList) mspans
106 fullPeriod = case fullPeriodDateSpan of
107 DateSpan (Just b) (Just e) -> (fromEFDay b, fromEFDay e)
108 _ -> err
109
110 let processSpan (b, e) = do
111 -- Spans are [begin,end), and end is 1 day after the actual end date we are interested in
112 let
113 spn = DateSpan (Just $ Exact b) (Just $ Exact e)
114
115 cashFlowApplyCostValue = map (\(d,amt) -> (d,mixedAmountValue e d amt))
116
117 valueBefore = dbg3 "valueBefore" $
118 mixedAmountValue e b $
119 total trans (And [ investmentsQuery
120 , Date (DateSpan Nothing (Just $ Exact b))])
121
122 valueAfter = dbg3 "valueAfter" $
123 mixedAmountValue e e $
124 total trans (And [investmentsQuery
125 , Date (DateSpan Nothing (Just $ Exact e))])
126
127 cashFlow = dbg3 "cashFlow" $
128 cashFlowApplyCostValue $
129 calculateCashFlow wd trans (And [ Not investmentsQuery
130 , Not pnlQuery
131 , Date spn ] )
132
133 pnl = dbg3 "pnl" $
134 cashFlowApplyCostValue $
135 calculateCashFlow wd trans (And [ Not investmentsQuery
136 , pnlQuery
137 , Date spn ] )
138
139 spanCommodities = dbg3 "spanCommodities" $
140 S.unions $ (maCommodities valueBefore) : (maCommodities valueAfter) : map (maCommodities.snd) (cashFlow ++ pnl)
141
142 thisSpan = dbg3 "processing span" $
143 OneSpan b e valueBefore valueAfter cashFlow pnl
144
145 when (S.size spanCommodities > 1) $
146 multiCommodityError $ "Period " ++ show (b,e) ++ " has multiple commodities: " ++ (T.unpack $ T.intercalate ", " $ map showCommoditySymbol (S.toList spanCommodities))
147
148 irr <- internalRateOfReturn styles showCashFlow prettyTables thisSpan
149 (periodTwr, annualizedTwr) <- timeWeightedReturn styles showCashFlow prettyTables investmentsQuery trans mixedAmountValue thisSpan
150 let cashFlowAmt = maNegate . maSum $ map snd cashFlow
151 let smallIsZero x = if abs x < 0.01 then 0.0 else x
152 return [ showDate b
153 , showDate (addDays (-1) e)
154 , T.pack $ showMixedAmountOneLineWithoutCost False $ styleAmounts styles $ valueBefore
155 , T.pack $ showMixedAmountOneLineWithoutCost False $ styleAmounts styles $ cashFlowAmt
156 -- , T.pack $ showMixedAmount $
157 -- -- dbg0With (lbl "cashflow after styling".showMixedAmountOneLine) $
158 -- mapMixedAmount (amountSetFullPrecisionUpTo (Just defaultMaxPrecision)) $
159 -- styleAmounts (styles
160 -- -- & dbg0With (lbl "styles".show))
161 -- cashFlowAmt
162 -- -- & dbg0With (lbl "cashflow before styling".showMixedAmountOneLine)
163 , T.pack $ showMixedAmountOneLineWithoutCost False $ styleAmounts styles $ valueAfter
164 , T.pack $ showMixedAmountOneLineWithoutCost False $ styleAmounts styles $ (valueAfter `maMinus` (valueBefore `maPlus` cashFlowAmt))
165 , T.pack $ printf "%0.2f%%" $ smallIsZero irr
166 , T.pack $ printf "%0.2f%%" $ smallIsZero periodTwr
167 , T.pack $ printf "%0.2f%%" $ smallIsZero annualizedTwr ]
168
169 periodRows <- forM spans processSpan
170 totalRow <- case periodRows of
171 [singleRow] -> return singleRow
172 _ -> processSpan fullPeriod
173
174 let rowTitles = Tab.Group Tab.NoLine (map (Header . T.pack . show) (take (length periodRows) [1..]))
175
176 let isSingleSpan = length spans == 1
177
178 let table = Table
179 (if isSingleSpan
180 then rowTitles
181 else Tab.Group Tab.SingleLine [ rowTitles, Tab.Group Tab.NoLine [ Header "Total" ]]
182 )
183 (Tab.Group Tab.DoubleLine
184 [ Tab.Group Tab.SingleLine [Header "Begin", Header "End"]
185 , Tab.Group Tab.SingleLine [Header "Value (begin)", Header "Cashflow", Header "Value (end)", Header "PnL"]
186 , Tab.Group Tab.SingleLine [Header "IRR"]
187 , Tab.Group Tab.SingleLine [Header "TWR/period", Header "TWR/year"]])
188 (if isSingleSpan then periodRows else periodRows ++ [totalRow])
189
190 TL.putStrLn $ Tab.render prettyTables id id id table
191
192 -- Entry for TWR computation, capturing all cashflows that are potentially accompanied by pnl change on the same day (if not, it is zero)
193 data TwrPeriod = TwrPeriod { twrStartDate :: Day, twrEndDate :: Day, twrStartValue :: Decimal, twrValueBeforeCashflow :: Decimal, twrPnl :: Decimal, twrCashflow :: Decimal, twrValueAfterCashflow :: Decimal } deriving (Eq, Show)
194
195 timeWeightedReturn _styles showCashFlow prettyTables investmentsQuery trans mixedAmountValue (OneSpan begin end valueBeforeAmt valueAfterAmt cashflows pnls) = do
196 let datedCashflows =
197 -- Aggregate all entries for a single day, assuming that intraday interest is negligible
198 dbg3 "datedCashflows"
199 $ sort
200 $ map (\datecashes -> let (dates, cash) = unzip datecashes in (headDef (error' "Roi.hs: datecashes was null, please report a bug") dates, maSum cash))
201 $ groupBy ((==) `on` fst)
202 $ sortOn fst
203 $ map (second maNegate)
204 $ cashflows
205
206 valueBefore = dbg3 ("value at the start of the interval, "++show begin) $ unMix valueBeforeAmt
207 valueAfter = dbg3 ("value at the end of the interval, "++show end) $ unMix valueAfterAmt
208
209 investmentPostings = concatMap (filter (matchesPosting investmentsQuery) . realPostings) trans
210
211 totalInvestmentPostingsTill date = sumPostings $ filter (matchesPosting (Date (DateSpan Nothing (Just $ Exact date)))) investmentPostings
212
213 -- filter span is (-infinity, date+1), which gives us effectively (-infinity, date]
214 valueAfterDate date = unMix $ mixedAmountValue end date $ totalInvestmentPostingsTill (addDays 1 date)
215
216 pnlOn date = unMix $ maNegate $ sum $ map snd $ filter ((==date).fst) pnls
217
218 -- We are dividing the period [begin, end) into subperiods on each cashflow, and then compute
219 -- the rate of return for each subperiod. For this we need to know the value of the investment
220 -- at the beginning and end of each subperiod, adjusted for cashflow.
221 --
222 -- Subperiods are going to be [valueBefore ... (c_0,v_0)][... (c_1, v_1)][... (c_2,v_2)] ... [... (c_n,v_n)][... valueAfter]
223 -- , where v_i is the value of investment computed immediately after cashflow c_i
224 --
225 -- Calculate interest for each subperiod, adjusting the value at the start of the period by the cashflow
226 -- For subperiods [valueBefore ... (c_0,v_0)][... (c_1, v_1)][... (c_2,v_2)] ... [... (c_n,v_n)][... valueAfter], the computation is going to be
227 -- 1 + twr = (v_0 - c_0)/valueBefore + (v_1 - c_1) / v_0 + ... + valueAfter/v_n
228 -- See https://en.wikipedia.org/wiki/Time-weighted_return#Time-weighted_return_compensating_for_external_flows
229 let calculateSubPeriods (startDate,startValue) [] =
230 let subPeriodReturn =
231 if startValue == 0 || valueAfter == 0
232 then 0
233 else valueAfter/startValue - 1
234 in
235 [(subPeriodReturn, TwrPeriod startDate end startValue valueAfter 0 0 valueAfter)]
236 calculateSubPeriods (startDate,startValue) ((date,cashflow):rest) =
237 let (valueBeforeCashflow, valueAfterCashflow, pnl) =
238 let valueAfterPrevDay = valueAfterDate (addDays (-1) date)
239 pnlOnDay = pnlOn date
240 in
241 -- If value was zero at the start of the period, then any PnL on cashflow date would accrue after it, not before.
242 -- If there was some value already, we can assume that PnL contributes to this period's rate
243 if startValue == 0
244 then (valueAfterPrevDay, valueAfterDate date - pnlOnDay, 0)
245 else (valueAfterPrevDay + pnl, valueAfterDate date, pnlOnDay)
246 subPeriodReturn =
247 if valueBeforeCashflow == 0 || startValue == 0
248 then 0
249 else (valueBeforeCashflow / startValue) - 1
250 in
251 (subPeriodReturn, (TwrPeriod startDate date startValue valueBeforeCashflow pnl (unMix cashflow) valueAfterCashflow)) : calculateSubPeriods (date,valueAfterCashflow) rest
252
253 let subPeriods = dbg3 "subPeriods" $ calculateSubPeriods (begin,valueBefore) datedCashflows
254
255 -- Compute overall time-weighted rate of return
256 let twr =
257 dbg3 "twr" $
258 if subPeriods == []
259 then if valueBefore == 0 then 0 else (valueAfter - valueBefore)/valueBefore
260 else foldl (\acc periodRate -> (1+acc)*(1+periodRate)-1) 0 (map fst subPeriods)
261 (startYear, _, _) = toGregorian begin
262 years = fromIntegral (diffDays end begin) / (if isLeapYear startYear then 366 else 365) :: Double
263 periodTWR = roundTo 2 $ 100 * twr
264 annualizedTWR = 100*((1+(realToFrac twr))**(1/years)-1) :: Double
265
266 when showCashFlow $ do
267 printf "\nTWR cash flow entries and subperiod rates for period %s - %s\n" (showDate begin) (showDate (addDays (-1) end))
268 let showDecimalT = T.pack . showDecimal
269 TL.putStr $ Tab.render prettyTables T.pack id id
270 (Table
271 (Tab.Group Tab.NoLine [ Header (show n) | n <-[1..length subPeriods]])
272 (Tab.Group DoubleLine [ Tab.Group Tab.SingleLine [Tab.Header "Subperiod start", Tab.Header "Cashflow date"]
273 , Tab.Group Tab.SingleLine [Tab.Header "Value at start", Tab.Header "Value before cashflow (inc PnL)", Tab.Header "PnL on day", Tab.Header "Cashflow", Tab.Header "Value after cashflow"]
274 , Tab.Group Tab.SingleLine [Tab.Header "Subperiod rate, %"]])
275 [ [ showDate (twrStartDate sp), showDate (twrEndDate sp)
276 , showDecimalT (twrStartValue sp), showDecimalT (twrValueBeforeCashflow sp), showDecimalT (twrPnl sp), showDecimalT (twrCashflow sp), showDecimalT (twrValueAfterCashflow sp)
277 , showDecimalT (roundTo 2 (100*rate)) ]
278 | (rate, sp) <- subPeriods
279 ])
280
281 printf "Total period TWR: %s%%.\nPeriod: %.2f years.\nAnnualized TWR: %.2f%%\n\n"
282 (showDecimal periodTWR) years annualizedTWR
283
284 return ((realToFrac periodTWR) :: Double, annualizedTWR)
285
286 internalRateOfReturn styles showCashFlow prettyTables (OneSpan begin end valueBefore valueAfter cashFlow _pnl) = do
287 let prefix = (begin, maNegate valueBefore)
288
289 postfix = (end, valueAfter)
290
291 totalCF = filter (maIsNonZero . snd) $ prefix : (sortOn fst cashFlow) ++ [postfix]
292
293 when showCashFlow $ do
294 printf "\nIRR cash flow for %s - %s\n" (showDate begin) (showDate (addDays (-1) end))
295 let (dates, amts) = unzip totalCF
296 TL.putStrLn $ Tab.render prettyTables id id id
297 (Table
298 (Tab.Group Tab.NoLine (map (Header . showDate) dates))
299 (Tab.Group Tab.SingleLine [Header "Amount"])
300 (map ((:[]) . T.pack . showMixedAmountOneLineWithoutCost False . styleAmounts styles) amts))
301
302 -- 0% is always a solution, so require at least something here
303 case totalCF of
304 [] -> return 0
305 _ -> case ridders (RiddersParam 100 (AbsTol 0.00001))
306 (0.000000000001,10000)
307 (interestSum end totalCF) of
308 Root rate -> return ((rate-1)*100)
309 NotBracketed -> error' $ "Equation for Internal Rate of Return (IRR) can not be solved.\n"
310 ++ " Possible causes: IRR is huge (>1000000%), balance of investment becomes negative at some point in time."
311 SearchFailed -> error' $ "Equation for Internal Rate of Return (IRR) can not be solved.\n"
312 ++ " Either search does not converge to a solution, or converges too slowly."
313
314 type CashFlow = [(Day, MixedAmount)]
315
316 interestSum :: Day -> CashFlow -> Double -> Double
317 interestSum referenceDay cf rate = sum $ map go cf
318 where go (t,m) = realToFrac (unMix m) * rate ** (fromIntegral (referenceDay `diffDays` t) / 365)
319
320
321 calculateCashFlow :: WhichDate -> [Transaction] -> Query -> CashFlow
322 calculateCashFlow wd trans query =
323 [ (postingDateOrDate2 wd p, pamount p) | p <- concatMap (filter (matchesPosting query) . realPostings) trans, maIsNonZero (pamount p) ]
324
325 total :: [Transaction] -> Query -> MixedAmount
326 total trans query = sumPostings (concatMap (filter (matchesPosting query) . realPostings) trans)
327
328 unMix :: MixedAmount -> Quantity
329 unMix a =
330 case (unifyMixedAmount a) of
331 Just a' -> aquantity a'
332 Nothing -> multiCommodityError $ "Amounts could not be converted to a single commodity: " ++ show (map showAmount $ amounts a)
333
334 multiCommodityError msg = error' $ msg ++
335 "\nConsider using --value to force all costs to be in a single commodity." ++
336 "\nFor example, \"--value=end,<commodity> --infer-market-prices\", where commodity is the one that you want to value the investment in."
337
338 -- Show Decimal rounded to two decimal places, unless it has less places already. This ensures that "2" won't be shown as "2.00"
339 showDecimal :: Decimal -> String
340 showDecimal d = if d == rounded then show d else show rounded
341 where
342 rounded = roundTo 2 d