diff --git a/hledger/Hledger/Cli/Commands/Roi.hs b/hledger/Hledger/Cli/Commands/Roi.hs index 45bae86ce3e..2bfa609933b 100644 --- a/hledger/Hledger/Cli/Commands/Roi.hs +++ b/hledger/Hledger/Cli/Commands/Roi.hs @@ -40,7 +40,7 @@ roimode = hledgerCommandMode ,flagReq ["investment"] (\s opts -> Right $ setopt "investment" s opts) "QUERY" "query to select your investment transactions" ,flagReq ["profit-loss","pnl"] (\s opts -> Right $ setopt "pnl" s opts) "QUERY" - "query to select profit-and-loss or appreciation/valuation transactions" + "query to select profit-and-loss or appreciation/valuation transactions (optional)" ] cligeneralflagsgroups1 hiddenflags @@ -85,7 +85,9 @@ roi CliOpts{rawopts_=rawopts, reportspec_=rspec@ReportSpec{_rsReportOpts=ropts@R cantCompute msg = error' $ msg ++ " - will be unable to compute the rates of return" investmentsQuery <- makeQuery "investment" - pnlQuery <- makeQuery "pnl" + pnlQuery <- case maybestringopt "pnl" rawopts of + Nothing -> return None + Just _ -> makeQuery "pnl" when (pnlQuery == Any) $ cantCompute "Need some transactions classed as investment and not pnl, but the pnl query matches any transaction" diff --git a/hledger/Hledger/Cli/Commands/Roi.md b/hledger/Hledger/Cli/Commands/Roi.md index 892974c9058..7a2c01f6f42 100644 --- a/hledger/Hledger/Cli/Commands/Roi.md +++ b/hledger/Hledger/Cli/Commands/Roi.md @@ -9,17 +9,18 @@ Flags: returns --investment=QUERY query to select your investment transactions --profit-loss=QUERY --pnl query to select profit-and-loss or - appreciation/valuation transactions + appreciation/valuation transactions (optional) ``` At a minimum, you need to supply a query (which could be just an -account name) to select your investment(s) with `--inv`, and another -query to identify your profit and loss transactions with `--pnl`. - -If your investment's value changes are captured solely through price -directives (rather than manual P&L journal entries), or if you do not -need TWR, `--pnl` can be an empty query (`--pnl ""` or `--pnl STR` -where `STR` does not match any of your accounts). +account name) to select your investment(s) with `--inv`. + +An optional second query to identify your profit and loss transactions +could be given with `--pnl`. If your investment's value changes are +captured solely through price directives (rather than manual P&L +journal entries), or if you do not need TWR, you can simply omit +`--pnl`, and no transactions will be classed as profit and loss in +this case. This command will compute and display the internal rate of return (IRR, also known as money-weighted rate of return) and time-weighted diff --git a/hledger/Hledger/Cli/Commands/Roi.txt b/hledger/Hledger/Cli/Commands/Roi.txt index f10f9cd57c9..3bd2a32f28e 100644 --- a/hledger/Hledger/Cli/Commands/Roi.txt +++ b/hledger/Hledger/Cli/Commands/Roi.txt @@ -8,16 +8,16 @@ Flags: returns --investment=QUERY query to select your investment transactions --profit-loss=QUERY --pnl query to select profit-and-loss or - appreciation/valuation transactions + appreciation/valuation transactions (optional) At a minimum, you need to supply a query (which could be just an account -name) to select your investment(s) with --inv, and another query to -identify your profit and loss transactions with --pnl. +name) to select your investment(s) with --inv. -If your investment's value changes are captured solely through price -directives (rather than manual P&L journal entries), or if you do not -need TWR, --pnl can be an empty query (--pnl "" or --pnl STR where STR -does not match any of your accounts). +An optional second query to identify your profit and loss transactions +could be given with --pnl. If your investment's value changes are +captured solely through price directives (rather than manual P&L journal +entries), or if you do not need TWR, you can simply omit --pnl, and no +transactions will be classed as profit and loss in this case. This command will compute and display the internal rate of return (IRR, also known as money-weighted rate of return) and time-weighted rate of @@ -30,22 +30,22 @@ Price directives will be taken into account if you supply appropriate Note, in some cases this report can fail, for these reasons: -- 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. -- Error (NotBracketed): Cannot compute window IRR. Possible cause: - investment balance becomes negative within that window. -- Error (SearchFailed): Window IRR search did not converge. +- 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. +- Error (NotBracketed): Cannot compute window IRR. Possible cause: + investment balance becomes negative within that window. +- Error (SearchFailed): Window IRR search did not converge. Examples: -- Using roi to compute total return of investment in stocks: - https://github.com/simonmichael/hledger/blob/main/examples/investing/roi-unrealised.ledger +- Using roi to compute total return of investment in stocks: + https://github.com/simonmichael/hledger/blob/main/examples/investing/roi-unrealised.ledger -- Cookbook > Return on Investment: https://hledger.org/roi.html +- Cookbook > Return on Investment: https://hledger.org/roi.html Spaces and special characters in --inv and --pnl @@ -73,23 +73,23 @@ sorted into two categories: "cash flow" and "profit and loss", as ROI needs to know which part of the investment value is your contributions and which is due to the return on investment. -- "Cash flow" is depositing or withdrawing money, buying or selling - assets, or otherwise converting between your investment commodity and - any other commodity. Example: +- "Cash flow" is depositing or withdrawing money, buying or selling + assets, or otherwise converting between your investment commodity + and any other commodity. Example: - 2019-01-01 Investing in Snake Oil - assets:cash -$100 - investment:snake oil + 2019-01-01 Investing in Snake Oil + assets:cash -$100 + investment:snake oil - 2020-01-01 Selling my Snake Oil - assets:cash $10 - investment:snake oil = 0 + 2020-01-01 Selling my Snake Oil + assets:cash $10 + investment:snake oil = 0 -- "Profit and loss" is change in the value of your investment: +- "Profit and loss" is change in the value of your investment: - 2019-06-01 Snake Oil falls in value - investment:snake oil = $57 - equity:unrealized profit or loss + 2019-06-01 Snake Oil falls in value + investment:snake oil = $57 + equity:unrealized profit or loss All non-investment postings are assumed to be "cash flow", unless they match --pnl query. Changes in value of your investment due to "profit @@ -180,9 +180,9 @@ removes the distortion caused by investor cash flows. References: -- Explanation of rate of return -- Explanation of IRR -- Explanation of TWR -- IRR vs TWR -- Examples of computing IRR and TWR and discussion of the limitations of - both metrics +- Explanation of rate of return +- Explanation of IRR +- Explanation of TWR +- IRR vs TWR +- Examples of computing IRR and TWR and discussion of the limitations + of both metrics diff --git a/hledger/test/roi.test b/hledger/test/roi.test index 8fc2a39b7a8..1f8d70687ce 100644 --- a/hledger/test/roi.test +++ b/hledger/test/roi.test @@ -8,7 +8,7 @@ 2017-06-01 investment assets:cash -$100 investment -$ hledger -f- roi --inv investment --pnl pnl -b 2017 -e 2018 -Y +$ hledger -f- roi --inv investment -b 2017 -e 2018 -Y +---++------------+------------++---------------+----------+-------------+-----++-------++------------+----------+ | || Begin | End || Value (begin) | Cashflow | Value (end) | PnL || IRR || TWR/period | TWR/year | +===++============+============++===============+==========+=============+=====++=======++============+==========+ @@ -212,7 +212,7 @@ $ hledger -f- roi --inv investment --pnl pnl -b 2017-06 -e 2018 2019/11/01 Example Assets:Checking 1 Income:Salary -1 -$ hledger -f- roi -p 2019-11 --pnl "^$" +$ hledger -f- roi -p 2019-11 +---++------------+------------++---------------+----------+-------------+-----++-------++------------+----------+ | || Begin | End || Value (begin) | Cashflow | Value (end) | PnL || IRR || TWR/period | TWR/year | +===++============+============++===============+==========+=============+=====++=======++============+==========+ @@ -379,7 +379,7 @@ P 2023-01-01 C 1B P 2023-12-31 C 2B -$ hledger -f - roi --inv investment --pnl income --value='then,B' -b2023 -e2024 +$ hledger -f - roi --inv investment --value='then,B' -b2023 -e2024 +---++------------+------------++---------------+----------+-------------+-----++--------++------------+----------+ | || Begin | End || Value (begin) | Cashflow | Value (end) | PnL || IRR || TWR/period | TWR/year | +===++============+============++===============+==========+=============+=====++========++============+==========+ @@ -405,7 +405,7 @@ P 2019-06-28 "IE00B4L5Y983" 50.93000000 "EUR" P 2019-12-30 "IE00B4L5Y983" 56.59000000 "EUR" -$ hledger -f - roi --value then --begin 2019 --end 2020 --inv investmen --pnl '"profit and loss"' -p 'every 2 quarters' +$ hledger -f - roi --value then --begin 2019 --end 2020 --inv investmen -p 'every 2 quarters' +-------++------------+------------++---------------+------------+-------------+-----------++--------++------------+----------+ | || Begin | End || Value (begin) | Cashflow | Value (end) | PnL || IRR || TWR/period | TWR/year | +=======++============+============++===============+============+=============+===========++========++============+==========+ @@ -434,7 +434,7 @@ P 2024-11-08 B 1 CHF P 2024-12-31 B 1.0018 CHF -$ hledger -f - roi -M -b 2024-10-01 -e 2024-12-31 --value then,CHF --inv '"investments:"' --pnl STR +$ hledger -f - roi -M -b 2024-10-01 -e 2024-12-31 --value then,CHF --inv '"investments:"' +-------++------------+------------++---------------+---------------+---------------+------------++--------++------------+----------+ | || Begin | End || Value (begin) | Cashflow | Value (end) | PnL || IRR || TWR/period | TWR/year | +=======++============+============++===============+===============+===============+============++========++============+==========+ @@ -479,7 +479,7 @@ P 2024-07-30 BAR 1 GBP assets £-90000.00 investment -$ hledger -f - roi -Y -b 2024 -e 2025 --inv 'investment' --pnl STR +$ hledger -f - roi -Y -b 2024 -e 2025 --inv 'investment' +---++------------+------------++---------------+------------+-------------+-----++-------++------------+----------+ | || Begin | End || Value (begin) | Cashflow | Value (end) | PnL || IRR || TWR/period | TWR/year | +===++============+============++===============+============+=============+=====++=======++============+==========+