Ledgerplot

Ledgerplot reads financial data from the hledger plain text accounting system and processes it into various useful plots.

It has various modes of operation, including plotting locally using GnuPlot, writing data to a Postgres database for plotting using Grafana, and watching input files to redo the above whenever they change. This allows using it as an unattended process on a server (to which you sync your ledger file) in order to feed updated data to Grafana.

Building

If you have Guix installed, you can set up a development environment easily using guix shell -Df guix.scm.

Otherwise, you'll have to install the required Lisp packages manually. See ledgerplot.asd for the list of dependencies.

Once everything is installed, run make to build the bin/ledgerplot executable.

Running

Run the bin/ledgerplot produced above. Use the --help option to see what it can do.

You should point the LEDGER_FILE environment variable at your hledger data file.

For example:

Generate PDF plots

bin/ledgerplot -p

Fetch exchange rates for your currencies and equity (shares, ETFs)

This uses the European Central Bank and Frankfurt Stock Exchange to fetch rates. Some currencies are translated into their three-letter codes automatically. Share and ETF symbols must appear as used at the Frankfurt Stock Exchange.

Ledgerplot will write exchange-rates.journal and market.journal files containing P price directives next to your LEDGER_FILE.

bin/ledgerplot -e -m

Watch `LEDGER_FILE` for changes and feed data into Postgres whenever it changes

This uses a database called ledgerdb:

bin/ledgerplot -w -d ledgerdb

You can use the various --database-* options to customise how Ledgerplot connects to your database.

Ledger file format

Ledgerplot uses hledger to parse your LEDGER_FILE, so some ledger features are not supported and/or treated differently from standard ledger.

Some plots report on "liquid" assets, i.e. immediately-accessible cash. To detect which hledger accounts should be used, Ledgerplot scans your LEDGER_FILE for lines of the format account ... ; tag:liquid.

The following should get you started -- adjust the account names to suit you!

;; Declare top-level accounts.
account assets       ; type:Asset
account liabilities  ; type:Liability
account equity       ; type:Equity
account income       ; type:Revenue
account expenses     ; type:Expense
;; Tell ledgerplot which accounts are considered "liquid", i.e. accessible cash.
account assets:cash              ; tag:liquid
account assets:current account   ; tag:liquid
account liabilities:credit card  ; tag:liquid
;; Declare currencies and how to print them.
commodity ???
  format 1.000,00 ???
commodity Fr
  format 1.000,00 Fr
commodity ??
  format ?? 1,000.00
commodity $
  format $ 1,000.00
;; Include auto-generated exchange rates.
include exchange-rates.journal
include market.journal

To-do list

detect currency number formats (e.g. "1.000,00 ???" vs "?? 1,000.00") from commodity ... format directives
allow configuring *combine-currency*, date range (*begin-date*, *end-date*) and other things from src/constants.lisp
track balance of outstanding reimbursements (assets:reimbursement)
report on stock/ETF portfolio performance, i.e., for each day: total worth of portfolio minus (cost of all stock/ETF purchases until then minus returns from all stock/ETF sales until then)
store exchange rates and equity prices in database for plotting
generate monthly reports in parallel, like the totals per currency

Manual testing

Since I have a WireGuard network that includes the machine running my Grafana instance, I can do the following to set up a temporary Postgres server. Grafana can then connect to it and I can interactively plot the containing data.

initdb -N testdb
echo "host testdb $(whoami) 10.0.0.0/24 trust" >> testdb/pg_hba.conf
echo "host testdb $(whoami) fc00::/64 trust" >> testdb/pg_hba.conf
postgres -F -h 10.0.0.x -D testdb -k "$XDG_RUNTIME_DIR" &
createdb -h "$XDG_RUNTIME_DIR" testdb 'Test database for ledgerplot'