Charts and Graphs

Tips and techniques for producing graphical charts from hledger data.

The most common general approach is to produce simple CSV output from a report - usually the balance report with -N/--no-total and --layout=bare:

hledger bal expenses -N --layout bare -o report.csv

and then use one of the many ways to make charts from CSV data.

Charting tools built for hledger

Simplest first:

hledger-bar

hledger-bar (2023) is a bash script for making quick bar charts in the terminal.

$ hledger bar someacct
2023-01	+++++
2023-02	++++
2023-03	++++
2023-04	+

$ hledger bar -- -v 1 -f $TIMELOG biz
2023-01	        15 +++++++++++++++
2023-02	        10 ++++++++++
2023-03	        20 ++++++++++++++++++++
2023-04	        12 ++++++++++++

$ hledger bar -- -v 1 -f $TIMELOG biz -p weeklyfrom3weeksago
2023-03-27W13	         8 ++++++++
2023-04-03W14	         2 ++
2023-04-10W15	         4 ++++
2023-04-17W16	         5 +++++

hledger-plot

hledger-plot (2023) is a powerful graphical chart-making tool written in python.

hledger-sankey

hledger-vega

hledger-vega (2022) is a set of scripts for producing custom charts from your hledger reports, using the powerful vega-lite. It works best with hledger 1.25+.

hledger-vega example

r-ledger

r-ledger is an R package for making reports and charts from hledger, Ledger or Beancount.

Other tools

Spreadsheets

Drag the CSV file into your favourite spreadsheet app and use its interactive charting tools.

Ledger chart tools

Tools built for Ledger or other PTA apps can sometimes be adapted to work with hledger also; or, hledger data can be exported to be read by Ledger.

ploterific

ploterific (stack install hvega-theme ploterific) produces simple charts, in a HTML file that uses the Vega-Lite javascript library. Charts can also be saved as SVG or PNG. An example:

hledger -f examples/bcexample.hledger bal -O csv -N expenses -3 cur:USD \
    | sed 's/ USD//' \
    | ploterific -m Bar -f account:N -f balance:Q -c account -o a.html \
    && open a.html

ploterific example 1

Let's break down that command line:

  • -f examples/bcexample.hledger - use this example file in the hledger repo. Omit this to use your default journal.
  • bal - run a balance report
  • -O csv - show it as CSV on stdout
  • -N - disable the final Total row
  • expenses - limit to accounts whose name contains expenses
  • -3 - summarise accounts to depth 3 and above
  • cur:USD - limit to balances in USD currency. If you use the $ symbol, it would be cur:\\$.
  • sed 's/ USD//g' - process the output with sed, stripping the USD symbols to leave bare numbers for ploterific. With $ it would be sed 's/\$//g'.
  • -m Bar - use Bar as the Vega-Lite mark type
  • -f account:N - use the account column as the first feature (X axis), treating values as names
  • -f balance:Q - use the balance column as a second feature (Y axis), treating values as quantities
  • -c account - use account values to select colours
  • -o a.html - save into a temporary HTML file
  • && open a.html - and view it in your web browser, on Mac; on other systems it might be xdg-open or start

Here is the same chart but with the colour set by the balance:

hledger -f examples/bcexample.hledger bal -O csv -N expenses -3 cur:USD \
    | sed 's/ USD//' \
    | ploterific -m Bar -f account:N -f balance:Q -c balance:Q -o a.html

ploterific example 2

SankeyMATIC

The format is Source [Amount] Target. A rough script that exports the outflows from several asset accounts:

LEDGER_FILE=examples/sample.journal
for f in checking saving cash; do 
  hledger areg $f -O tsv | tail +2 | sed -e "s/^/$f\t/"
done | cut -f1,6,7 | gsed -E -e 's/\$//' -e 's/([^\t]*)\t([^\t]*)\t([^\t]*)/\1 [\3] \2/' | grep '\[-' | gsed 's/\[-/[/'

hledger-sankeymatic is a shell script that uses awk to generate sankey flow nodes you can paste directly into https://sankeymatic.com.