| 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 |