ludget: ledger-cli data visualization

ludget is a command-line program for visualization of Ledger data. It also supports envelope budgeting.

It generates the following plots:

• Budget balance bar chart.
• Expenses pie chart.
• Cash flow bar chart.
• Assets area chart.
• Net worth bar chart.

Installation

pip install ludget

Requirements

• ledger
• python 3.6+
• numpy
• matplotlib
• pandas

Usage

ludget [OPTIONS]

ludget usage is similar to that of Ledger.

The simplest way to use ludget is to specify all Ledger options in an init file (e.g. ~/.ledgerrc). Calling ludget will then use the init file. Ledger options can also be passed directly to ludget. Refer to the Ledger documentation.

ludget also has its own options. If no options are provided, all plots are generated. The following options are used to generate specific plots:

• --budget: budget balance bar chart, last 1 month.
• --expenses: expenses pie chart, last 1 month.
  • By default, accounts below 5% of the total expenses are aggregated as the label Other. The threshold can be specified with the option --threshold THRESHOLD where THRESHOLD is a ratio (e.g. 0.05 for 5%).
• --cash-flow: cash flow bar chart, last 12 months.
• --assets: assets area chart, last 365 days.
• --net-worth: net worth bar chart, last 12 months.

The following options are used to change the date range:

• --periods PERIODS: use the last PERIODS number of periods.
• --freq FREQ: use frequency FREQ given as a pandas offset alias.

For example, ludget --cash-flow --periods 4 --freq Q generates a quarterly (--freq Q) cash flow (--cash-flow) plot of the last four quarters (--periods 4).

By default, ludget resolves accounts to the finest level of detail. The following option is used to aggregate accounts to a coarser level of detail:

• --level LEVEL: resolve accounts up to LEVEL levels of detail.

For example, if an account Expenses:Food:Hamburgers and Fries exists, it has 3 levels of detail separated by :. Level 1 is Expenses, level 2 is Food and level 3 is Hamburgers and Fries. The option --level 2 aggregates all Expenses:Food subaccounts together.

The only level 1 accounts considered by ludget are:

• Assets
• Expenses
• Income
• Liabilities
• Equity

If a level 0 account Budget exists (e.g. Budget:Expenses:Food:Hamburgers and Fries), it is considered for the budget bar chart.

Example