hledger-forecast

"Improved", you say? Using a CSV file, forecasts can be quickly generated into a journal file ready to be fed into hledger. A 16 line CSV file can generate a 46 line hledger forecast file!

Before hledger: As the complexity of my forecasts started to increase, so did the length of my journal file. When I undertook the monthly exercise of editing my forecast, it became more cumbersome to find specific amounts and descriptions.It also became a nuisance if I'd grouped certain items by date which needed to be changed.

With hledger-forecast forecasts can be constrained between dates, tracked until they appear in your bank statements and summarized into your own daily/weekly/monthly/yearly personal forecast income and expenditure statement.

• 🚀 Uses a simple CSV file to generate forecasts which can be used with hledger
• 📆 Can smartly track forecasts against your bank statement
• 💵 Can automatically apply modifiers such as inflation/deflation to forecasts
• 🔍 Enables the use of maths in your forecasts (for amounts and dates)
• 📊 Display your forecasts as income and expenditure reports (e.g. daily, weekly, monthly)
• 🔀 Compare and display the difference between hledger outputs
• 💻 Simple and easy to use CLI

A CSV forecast and the hledger journal it generates

The ouput from the summarize command

Assuming you have Ruby and Rubygems installed on your system, simply run:

gem install --user hledger-forecast

Run:

hledger-forecast

The available options are:

Usage: hledger-forecast [command] [options]

Commands:
  generate    Generate a forecast from a file
  summarize   Summarize the forecast file and output to the terminal
  compare     Compare and highlight the differences between two CSV files

Options:
    -h, --help                       Show this help message
    -v, --version                    Show version

The hledger-forecast generate command will generate a forecast from a CSV file to a journal file. You can see the output of this command in the example.journal file.

The available options are:

Usage: hledger-forecast generate [options]

  -f, --forecast FILE              The path to the FORECAST CSV file to generate from
  -o, --output-file FILE           The path to the OUTPUT file to create
  -t, --transaction FILE           The path to the TRANSACTION journal file
  -v, --verbose                    Don't group transactions by type in the output file
      --force                      Force an overwrite of the output file
      --no-track                   Don't track any transactions
  -h, --help                       Show this help message

Note: For the tracking of transactions you need to include the -t flag

Running the command with no options will assume a forecast.csv file exists.

To work with hledger, include the forecast file and use the --forecast flag:

hledger -f bank_transactions.journal -f forecast.journal --forecast bal assets -e 2024-02

The command will generate a forecast up to the end of Feb 2024, showing the balance for any asset accounts, overlaying some bank transactions with the forecast journal file. Forecasting in hledger can be complicated so be sure to refer to the documentation or start a discussion.

If you use the hledger-ui tool, it may be helpful to use the --verbose flag. This ensures that transactions are not grouped together in the forecast journal file, making descriptions much easier to read.

As your forecast file grows, it can be helpful to sum up the total amounts and output them to the CLI. Think of this command as your own profit and loss summarizer, generating a statement over a period you specify.

hledger-forecast summarize -f my_forecast.csv

The available options are:

Usage: hledger-forecast summarize [options]

-f, --forecast FILE              The path to the FORECAST CSV file to summarize
-r, --roll-up PERIOD             The period to roll-up your forecasts into. One of:
                                 [yearly], [half-yearly], [quarterly], [monthly], [weekly], [daily]
-v, --verbose                    Show additional information in the summary
-h, --help                       Show this help message

A core part of managing your personal finances is the comparison of what you expected to happen versus what actually happened. This can be challenging to accomplish with hledger so to make this easier, the app has a useful compare command:

hledger-forecast compare [path/to/file1.csv] [path/to/file2.csv]

To generate CSV output with hledger, append -O csv > output.csv to your desired command.

To make it easier to read horizontal output in the terminal, consider the use of a terminal pager like most by appending | most to the compare command.

Note: The two CSV files being compared must have the same structure

The app makes it easy to generate a comprehensive journal file with very few lines of code, making it much easier to stay on top of your forecasting from month to month.

The CSV file should contain a header row with the following columns:

• type - (string) - The type of forecast entry. One of monthly, quarterly, half-yearly, yearly, once or custom
• frequency - (string) - The frequency that the type repeats with (only if custom). As per hledger's periodic rule syntax
• account - (string) - The account the transaction applies to e.g. Expenses:Food
• from - (date) - The date the transaction should start from e.g. 2023-06-01
• to - (date) (optional) - The date the transaction should end on e.g. 2023-12-31
• description - (string) - A description of the transaction
• category - (string) - The classification or category of the transaction
• amount - (integer/float) - The amount of the transaction
• roll-up - (integer/float) (optional) - For use with the summarizer, the value you need to multiply the amount by to get it into a yearly amount
• summary_exclude - (boolean) (optional) - Exclude the transaction from the summarizer?
• track - (boolean) (optional) - Track the transaction against your confirmed transactions?

Putting it together, we end up with a CSV file like:

type,frequency,account,from,to,description,category,amount,roll-up,summary_exclude,track
monthly,,Assets:Bank,01/03/2023,,Salary,Income:Salary,-3500,,,
monthly,,Assets:Bank,01/03/2023,01/01/2025,Mortgage,Expenses:Mortgage,2000,,,
monthly,,Assets:Bank,01/03/2023,,Bills,Expenses:Bills,175,,,
monthly,,Assets:Bank,01/03/2023,,Food,Expenses:Food,500,,,
monthly,,Assets:Bank,01/03/2023,,New Kitchen,Expenses:House,=5000/24,,,
monthly,,Assets:Bank,01/03/2023,=12,Holiday,Expenses:Holiday,125,,,
monthly,,Assets:Bank,01/03/2023,01/03/2025,Rainy day fund,Assets:Savings,300,,,
monthly,,Assets:Pension,01/01/2024,,Pension draw down,Income:Pension,-500,,,
quarterly,,Assets:Bank,01/04/2023,,Quarterly bonus,Income:Bonus,-1000,,,
half-yearly,,Assets:Bank,01/04/2023,,Top up holiday funds,Expenses:Holiday,500,,,
yearly,,Assets:Bank,01/04/2023,,Annual bonus,Income:Bonus,-2000,,,
once,,Assets:Bank,05/03/2023,,Refund for that damn laptop,Expenses:Shopping,-3000,,TRUE,TRUE
custom,every 2 weeks,Assets:Bank,01/03/2023,,Hair and beauty,Expenses:Personal Care,80,26,,
custom,every 5 weeks,Assets:Bank,01/03/2023,,Misc expenses,Expenses:General Expenses,30,10.4,,
settings,currency,USD,,,,,,,,

From the example above, there are a few additional features that may be useful.

Note: Calculations will be determined up to two decimal places

It may be helpful to let the app calculate the forecasted amount in your transactions on your behalf. This can be especially useful if you're spreading a payment out over a number of months:

type,frequency,account,from,to,description,category,amount,roll-up,summary_exclude,track
monthly,,Assets:Bank,01/03/2023,,New Kitchen,Expenses:House,=5000/24,,,

Simply start the amount column with a = sign and use standard Excel based math formatting.

It may also be helpful for to dates to be calculated:

type,frequency,account,from,to,description,category,amount,roll-up,summary_exclude,track
monthly,,Assets:Bank,01/03/2023,=12,Holiday,Expenses:Holiday,125,,,

There are also additional settings that can be applied in the forecast. The defaults are:

type,frequency,account,from,to,description,category,amount,roll-up,summary_exclude,track
settings,currency,USD,,,,,,,,
settings,show_symbol,true,,,,,,,,
settings,thousands_separator,true,,,,,,,,

Note: Marking a transaction for tracking will ensure that it is only written into the forecast if it isn't found within a specified transaction file

Sometimes it can be useful to track and monitor forecasted transactions to ensure that they are accounted for in any financial projections. If they are present, then these should be discarded from your forecast as this will create a double count against your actuals. However, if they can't be found then they should be carried forward into a future period to ensure accurate recording.

To mark transactions as available for tracking you may use the track option in your config file:

type,frequency,account,from,to,description,category,amount,roll-up,summary_exclude,track
once,,Assets:Bank,2023-03-05,,Refund for that damn laptop,Expenses:Shopping,-3000,,,TRUE

Note: This feature has been designed to work with once transaction types only

To use this feature, ensure you pass a filepath to the -t flag, such as:

hledger-forecast generate -t [journal_file_to_search] -f [path_to_yaml_file] -o [path_to_output_journal]

The app will use a hledger query to determine if the combination of category and amount is present in the periods between the from key and the current date in the journal file you've specified. If not, then the app will include it as a forecast transaction in the output file.

I am open to any pull requests that fix bugs but would ask that any new functionality is discussed before it could be accepted.