# * roi command # ** 1. investment that does not grow has no return < 2017-01-01 investment assets:cash -$100 investment 2017-06-01 investment assets:cash -$100 investment $ hledger -f- roi --inv investment --pnl pnl -b 2017 -e 2018 -Y +---++------------+------------++---------------+----------+-------------+-----++-------++------------+----------+ | || Begin | End || Value (begin) | Cashflow | Value (end) | PnL || IRR || TWR/period | TWR/year | +===++============+============++===============+==========+=============+=====++=======++============+==========+ | 1 || 2017-01-01 | 2017-12-31 || 0 | $200 | $200 | 0 || 0.00% || 0.00% | 0.00% | +---++------------+------------++---------------+----------+-------------+-----++-------++------------+----------+ >= 0 # ** 2. Growth by 12% from single investment transaction should show 12% IRR and 12% TWR < 2017-01-01 investment assets:cash -$100 investment 2017-12-31 investment valuation investment = $112 pnl $ hledger -f- roi --inv investment --pnl pnl -b 2017 -e 2018 -Y +---++------------+------------++---------------+----------+-------------+-----++--------++------------+----------+ | || Begin | End || Value (begin) | Cashflow | Value (end) | PnL || IRR || TWR/period | TWR/year | +===++============+============++===============+==========+=============+=====++========++============+==========+ | 1 || 2017-01-01 | 2017-12-31 || 0 | $100 | $112 | $12 || 12.00% || 12.00% | 12.00% | +---++------------+------------++---------------+----------+-------------+-----++--------++------------+----------+ >= 0 # ** 3. Same as (2), but grow by 1% per month < 2017-01-01 investment assets:cash -$100 investment 2017-01-31 investment valuation investment = $101 pnl 2017-02-28 investment valuation investment = $102 pnl 2017-03-31 investment valuation investment = $103 pnl 2017-04-30 investment valuation investment = $104 pnl 2017-05-31 investment valuation investment = $105 pnl 2017-06-30 investment valuation investment = $106 pnl 2017-07-31 investment valuation investment = $107 pnl 2017-08-31 investment valuation investment = $108 pnl 2017-09-30 investment valuation investment = $109 pnl 2017-10-31 investment valuation investment = $110 pnl 2017-11-30 investment valuation investment = $111 pnl 2017-12-31 investment valuation investment = $112 pnl $ hledger -f- roi --inv investment --pnl pnl -b 2017 -e 2018 -Y +---++------------+------------++---------------+----------+-------------+-----++--------++------------+----------+ | || Begin | End || Value (begin) | Cashflow | Value (end) | PnL || IRR || TWR/period | TWR/year | +===++============+============++===============+==========+=============+=====++========++============+==========+ | 1 || 2017-01-01 | 2017-12-31 || 0 | $100 | $112 | $12 || 12.00% || 12.00% | 12.00% | +---++------------+------------++---------------+----------+-------------+-----++--------++------------+----------+ >= 0 # ** 4. When $100 invested over 12 month + $100 invested over 6 month yield $220, that's 10% TWR, but 12.73% IRR < 2017-01-01 investment assets:cash -$100 investment 2017-06-01 investment assets:cash -$100 investment 2017-12-31 investment valuation investment = $220 pnl $ hledger -f- roi --inv investment --pnl pnl -b 2017 -e 2018 -Y +---++------------+------------++---------------+----------+-------------+-----++--------++------------+----------+ | || Begin | End || Value (begin) | Cashflow | Value (end) | PnL || IRR || TWR/period | TWR/year | +===++============+============++===============+==========+=============+=====++========++============+==========+ | 1 || 2017-01-01 | 2017-12-31 || 0 | $200 | $220 | $20 || 12.72% || 10.00% | 10.00% | +---++------------+------------++---------------+----------+-------------+-----++--------++------------+----------+ >= 0 # ** 5. When $100 invested over 12 month + $100 invested over 6 month yield $20, that's -90% TWR, but -95.73% IRR < 2017-01-01 investment assets:cash -$100 investment 2017-06-01 investment assets:cash -$100 investment 2017-12-31 investment valuation investment = $20 pnl $ hledger -f- roi --inv investment --pnl pnl -b 2017 -e 2018 -Y +---++------------+------------++---------------+----------+-------------+-------++---------++------------+----------+ | || Begin | End || Value (begin) | Cashflow | Value (end) | PnL || IRR || TWR/period | TWR/year | +===++============+============++===============+==========+=============+=======++=========++============+==========+ | 1 || 2017-01-01 | 2017-12-31 || 0 | $200 | $20 | $-180 || -95.73% || -90.00% | -90.00% | +---++------------+------------++---------------+----------+-------------+-------++---------++------------+----------+ >= 0 # ** 6. Check that deposits/withdrawals and profit/loss are reflected in the right periods < 2017-01-01 investment assets:cash -$100 investment 2017-06-30 investment valuation investment = $110 pnl 2017-07-01 investment assets:cash -$100 investment 2017-10-01 withdrawal assets:cash $50 investment 2017-12-31 investment valuation investment = $155 pnl $ hledger -f- roi --inv investment --pnl pnl -b 2017 -e 2018 -Q +-------++------------+------------++---------------+----------+-------------+-----++---------++------------+----------+ | || Begin | End || Value (begin) | Cashflow | Value (end) | PnL || IRR || TWR/period | TWR/year | +=======++============+============++===============+==========+=============+=====++=========++============+==========+ | 1 || 2017-01-01 | 2017-03-31 || 0 | $100 | $100 | 0 || 0.00% || 0.00% | 0.00% | | 2 || 2017-04-01 | 2017-06-30 || $100 | 0 | $110 | $10 || 46.56% || 10.00% | 46.56% | | 3 || 2017-07-01 | 2017-09-30 || $110 | $100 | $210 | 0 || 0.00% || 0.00% | 0.00% | | 4 || 2017-10-01 | 2017-12-31 || $210 | $-50 | $155 | $-5 || -11.83% || -3.12% | -11.83% | +-------++------------+------------++---------------+----------+-------------+-----++---------++------------+----------+ | Total || 2017-01-01 | 2017-12-31 || 0 | $150 | $155 | $5 || 3.64% || 6.56% | 6.56% | +-------++------------+------------++---------------+----------+-------------+-----++---------++------------+----------+ >= 0 # ** 7. Check that reporting for the part of the total history of investment works < 2017-01-01 investment assets:cash -$100 investment 2017-06-30 investment valuation investment = $110 pnl 2017-07-01 investment assets:cash -$100 investment 2017-10-01 withdrawal assets:cash $50 investment 2017-12-31 investment valuation investment = $155 pnl $ hledger -f- roi --inv investment --pnl pnl -b 2017-06 -e 2018 +---++------------+------------++---------------+----------+-------------+-----++-------++------------+----------+ | || Begin | End || Value (begin) | Cashflow | Value (end) | PnL || IRR || TWR/period | TWR/year | +===++============+============++===============+==========+=============+=====++=======++============+==========+ | 1 || 2017-06-01 | 2017-12-31 || $100 | $50 | $155 | $5 || 5.24% || 6.56% | 11.45% | +---++------------+------------++---------------+----------+-------------+-----++-------++------------+----------+ >= 0 # ** 8. Dont fail where there is no rate-of-return < 2019/11/01 Example Assets:Checking 1 Income:Salary -1 $ hledger -f- roi -p 2019-11 --pnl "^$" +---++------------+------------++---------------+----------+-------------+-----++-------++------------+----------+ | || Begin | End || Value (begin) | Cashflow | Value (end) | PnL || IRR || TWR/period | TWR/year | +===++============+============++===============+==========+=============+=====++=======++============+==========+ | 1 || 2019-11-01 | 2019-11-30 || 0 | 0 | 0 | 0 || 0.00% || 0.00% | 0.00% | +---++------------+------------++---------------+----------+-------------+-----++-------++------------+----------+ >= 0 # ** 9. Fail with a nice error message when commodity can't be valued < 2019/11/01 Example Assets:Checking -100 A Investment 10 B 2019/11/02 Example Assets:Checking -100 C Investment 100 C 2019/11/02 Example Investment -9 B @@ 100 A Assets:Checking 101 A Unrealized PnL $ hledger -f- roi -p 2019-11 --inv Investment --pnl PnL >2 hledger: Error: Period (2019-11-01,2019-12-01) has multiple commodities: A, B, C Consider using --value to force all costs to be in a single commodity. For example, "--value=end, --infer-market-prices", where commodity is the one that you want to value the investment in. >= 1 # ** 10. Forcing valuation via --value < 2019/11/01 Example Assets:Checking -100 A Investment 10 B 2019/11/02 Example Investment -10 B @@ 100 A Assets:Checking 101 A Unrealized PnL $ hledger -f- roi -p 2019-11 --inv Investment --pnl PnL --cost --value=then,A --infer-market-prices +---++------------+------------++---------------+----------+-------------+-----++----------++------------+----------+ | || Begin | End || Value (begin) | Cashflow | Value (end) | PnL || IRR || TWR/period | TWR/year | +===++============+============++===============+==========+=============+=====++==========++============+==========+ | 1 || 2019-11-01 | 2019-11-30 || 0 | -1 A | 0 | 1 A || 3678.34% || 1.00% | 12.87% | +---++------------+------------++---------------+----------+-------------+-----++----------++------------+----------+ >= 0 # ** 11. Use "then" prices. 10000/76.20 = 131.23, 11000/73.88=148.89. # Also note that large decimals are limited to 8 digits if there's no # standard display precision for them (P directives do not set display precision). < P 2020-12-01 $ 76.20 P 2021-01-01 $ 73.88 2020-12-02 invest assets:investment 10000 assets 2021-01-02 get profit assets:investment =11000 income:investment $ hledger -f - roi --inv assets:investment --pnl income:investment --value=then,'$' +---++------------+------------++---------------+---------------+---------------+--------------++---------++------------+----------+ | || Begin | End || Value (begin) | Cashflow | Value (end) | PnL || IRR || TWR/period | TWR/year | +===++============+============++===============+===============+===============+==============++=========++============+==========+ | 1 || 2020-12-02 | 2021-01-02 || 0 | $131.23359580 | $148.89009204 | $17.65649624 || 321.99% || 13.45% | 323.66% | +---++------------+------------++---------------+---------------+---------------+--------------++---------++------------+----------+ >= # ** 12. Use "end" prices. 10000/73.88=135.35. # And, large decimals can be rounded further with a commodity directive. < commodity $1000.00 P 2020-12-01 $ 76.20 P 2021-01-01 $ 73.88 2020-12-02 invest assets:investment 10000 assets 2021-01-02 get profit assets:investment =11000 income:investment $ hledger -f - roi --inv assets:investment --pnl income:investment --value=end,'$' +---++------------+------------++---------------+----------+-------------+--------++---------++------------+----------+ | || Begin | End || Value (begin) | Cashflow | Value (end) | PnL || IRR || TWR/period | TWR/year | +===++============+============++===============+==========+=============+========++=========++============+==========+ | 1 || 2020-12-02 | 2021-01-02 || 0 | $135.35 | $148.89 | $13.54 || 196.58% || 10.00% | 197.46% | +---++------------+------------++---------------+----------+-------------+--------++---------++------------+----------+ >= # ** 13. Several PnL transactions on a single date are aggregated together < 2010-01-01 A1 savingA 100.00 € checking 2011-12-31 A2 savingA 0.00 € dividendA -8.00 € checking 2012-03-29 A3 savingA -100.00 € checking # ======================================== 2010-01-01 B1 savingB 100.00 € checking 2011-12-31 B2 savingB 0.00 € dividendB -8.00 € checking 2012-03-29 B3 saving -100.00 € checking $ hledger -f - roi --inv saving --pnl dividend +---++------------+------------++---------------+----------+-------------+---------++-------++------------+----------+ | || Begin | End || Value (begin) | Cashflow | Value (end) | PnL || IRR || TWR/period | TWR/year | +===++============+============++===============+==========+=============+=========++=======++============+==========+ | 1 || 2010-01-01 | 2012-03-29 || 0 | -16.00 € | 0 | 16.00 € || 3.52% || 8.00% | 3.49% | +---++------------+------------++---------------+----------+-------------+---------++-------++------------+----------+ >= 0 # ** 14. Should support begin date before first transaction where first transaction has pnl < P 2022-07-31 A € 1 2022-08-01 Purchase checking € -101 stocks 100 A @ € 1 expenses € 1 P 2022-08-02 A € 2 $ hledger -f - roi --inv stocks --pnl expenses --value=then,€ -Y +---++------------+------------++---------------+----------+-------------+------++---------++------------+----------+ | || Begin | End || Value (begin) | Cashflow | Value (end) | PnL || IRR || TWR/period | TWR/year | +===++============+============++===============+==========+=============+======++=========++============+==========+ | 1 || 2022-01-01 | 2022-12-31 || 0 | € 101 | € 200 | € 99 || 410.31% || 98.02% | 98.02% | +---++------------+------------++---------------+----------+-------------+------++---------++------------+----------+ >= 0 # ** 15. Correctly work with --value and complex valuation chains < P 2023-01-01 B 20A P 2023-01-01 C 1B 2023-01-01 investment 1C @@ 20A investment 4B @@ 80A assets P 2023-12-31 C 2B $ hledger -f - roi --inv investment --pnl income --value='then,B' -b2023 -e2024 +---++------------+------------++---------------+----------+-------------+-----++--------++------------+----------+ | || Begin | End || Value (begin) | Cashflow | Value (end) | PnL || IRR || TWR/period | TWR/year | +===++============+============++===============+==========+=============+=====++========++============+==========+ | 1 || 2023-01-01 | 2023-12-31 || 0 | 5B | 6B | 1B || 20.00% || 20.00% | 20.00% | +---++------------+------------++---------------+----------+-------------+-----++--------++------------+----------+ >= 0 # ** 16. Correcly process dates with just pricing changes < D 1,000.00 EUR 2018-07-01 investment assets:bank investments:iShares Core MSCI World 1 "IE00B4L5Y983" P 2018-12-28 "IE00B4L5Y983" 43.11000000 "EUR" P 2019-06-28 "IE00B4L5Y983" 50.93000000 "EUR" 2019-07-01 investment assets:bank investments:iShares Core MSCI World 10 "IE00B4L5Y983" 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' +-------++------------+------------++---------------+------------+-------------+-----------++--------++------------+----------+ | || Begin | End || Value (begin) | Cashflow | Value (end) | PnL || IRR || TWR/period | TWR/year | +=======++============+============++===============+============+=============+===========++========++============+==========+ | 1 || 2019-01-01 | 2019-06-30 || 43.11 EUR | 0 | 50.93 EUR | 7.82 EUR || 39.96% || 18.14% | 39.96% | | 2 || 2019-07-01 | 2019-12-31 || 50.93 EUR | 509.30 EUR | 622.49 EUR | 62.26 EUR || 23.25% || 11.11% | 23.25% | +-------++------------+------------++---------------+------------+-------------+-----------++--------++------------+----------+ | Total || 2019-01-01 | 2019-12-31 || 43.11 EUR | 509.30 EUR | 622.49 EUR | 70.08 EUR || 24.51% || 31.27% | 31.27% | +-------++------------+------------++---------------+------------+-------------+-----------++--------++------------+----------+ >= 0 # ** 17. Avoids fencepost problem when allocating PnL to periods < commodity 1,000.00 CHF P 2024-11-07 A 1 CHF P 2024-11-08 B 1 CHF 2024-11-07 buying A assets -20 CHF investments:A 20 A @@ 20 CHF 2024-11-26 buying B assets -20000 CHF investments:B 19986 B @@ 20000 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 +-------++------------+------------++---------------+---------------+---------------+------------++--------++------------+----------+ | || Begin | End || Value (begin) | Cashflow | Value (end) | PnL || IRR || TWR/period | TWR/year | +=======++============+============++===============+===============+===============+============++========++============+==========+ | 1 || 2024-10-01 | 2024-10-31 || 0 | 0 | 0 | 0 || 0.00% || 0.00% | 0.00% | | 2 || 2024-11-01 | 2024-11-30 || 0 | 20,020.00 CHF | 20,006.00 CHF | -14.00 CHF || -4.96% || 0.00% | 0.00% | | 3 || 2024-12-01 | 2024-12-31 || 20,006.00 CHF | 0 | 20,041.97 CHF | 35.97 CHF || 2.14% || 0.18% | 2.14% | +-------++------------+------------++---------------+---------------+---------------+------------++--------++------------+----------+ | Total || 2024-10-01 | 2024-12-31 || 0 | 20,020.00 CHF | 20,041.97 CHF | 21.97 CHF || 1.12% || 0.18% | 0.72% | +-------++------------+------------++---------------+---------------+---------------+------------++--------++------------+----------+ >= 0