Hforecast
Documentation menu

Documentation

Analyzing output

Hforecast writes a standard hledger journal — the same format you’d keep by hand. There’s nothing hforecast-specific about querying it: every report below is an ordinary hledger command. This page collects the useful ones.

Point -o at a file so you have something to query:

hforecast -c plan.yaml -o hforecast.journal

Then run reports against hforecast.journal. (You can also pipe: hforecast | hledger -f - bal assets.)

Net worth over time

Assets minus liabilities, one column per year:

hledger -f hforecast.journal bal assets liabilities --tree -Y

Add --depth 2 to collapse subaccounts, or a date range with -b/-e:

hledger -f hforecast.journal bal assets liabilities -Y --depth 2 -b 2030 -e 2060

Balance sheet at a point in time 

hledger -f hforecast.journal bs -e 2060-01-01

Income and expenses

Income statement by year, and a focused look at any category:

hledger -f hforecast.journal is -Y                       # income vs. expenses
hledger -f hforecast.journal bal expenses --tree -Y      # where the money goes
hledger -f hforecast.journal bal expenses:taxes -Y       # tax burden by year

Investments and holdings

Because hforecast writes price directives each period, hledger can value holdings and show commodity quantities:

hledger -f hforecast.journal bal assets:brokerage -Y                     # value by year
hledger -f hforecast.journal bal assets:brokerage -Y --no-total -B       # cost basis
hledger -f hforecast.journal bal assets:brokerage -Y --value=end         # market value each year

Viewing results in today’s dollars

Hforecast amounts are nominal (future) dollars — $2M in 2060 buys far less than $2M today. To restate the results in today’s (plan-start) dollars, the journal carries a real-value price for the default currency each period: the inflation discount of one unit back to the start date. The commodity is named after the default currency — TODAYUSD for a $ plan, TODAYEUR for €, and so on (TODAYCURR if the currency isn’t recognized). Convert with hledger’s --value:

# Final net worth in today's dollars
hledger -f hforecast.journal bal assets liabilities --infer-market-prices --value=end,TODAYUSD

# Net worth by year, each year already in today's dollars
hledger -f hforecast.journal bal assets liabilities --infer-market-prices --value=end,TODAYUSD --historical -Y

--infer-market-prices lets hledger read investment prices from the @/@@ cost annotations, so equities and property convert through the default currency to TODAYUSD. Only the default currency is discounted this way.

Use --value=end for balances, --value=then for flows. A balance sheet (bal, balancesheet) is a snapshot of what you have and owe, so value it at the snapshot date with --value=end: a settled account — a paid-off mortgage, a spent-down savings account — reads exactly zero. An income statement (incomestatement, is) is a stream of flows, so value each flow at its own date with --value=then. Running a balance query with --value=then re-sums every historical posting at its own date’s discount, which leaves a residue on a settled account (for a paid-off mortgage, its real inflation gain) — correct for flows, misleading for a balance. Because the two statements use different rates, a valued balance sheet and income statement won’t reconcile to the penny; the gap is a purchasing-power gain/loss, which is expected in real-terms accounting.

Checking what the run did

If a run ended early or a number looks off, two things help before you touch hledger:

  • hforecast --explain prints the resolved plan (with provenance) before the run — confirm the inputs are what you intended. See Command-line reference.
  • stderr reports an early stop (e.g. running out of money) and the reason. A non-zero exit status means a config or validation error.

Then trace the journal itself:

hledger -f hforecast.journal reg assets:general           # every cash movement, in order
hledger -f hforecast.journal reg expenses:taxes           # tax settlements
hledger -f hforecast.journal print -b 2040 -e 2041        # raw transactions for one year

Charting

hledger’s output is plain text and CSV-friendly, so it feeds charting tools directly:

hledger -f hforecast.journal bal assets liabilities -Y -O csv > networth.csv

Load that into a spreadsheet, or use hledger-ui / hledger-web for interactive exploration.

See also