Forecasting Future Transactions in Beancount

Beancount can project future recurring transactions using the fava.plugins.forecast plugin. This allows you to visualize the future impact of regular income and expenses, such as salaries, rent, and subscriptions, on your financial reports.

Step 1: Enable the Forecast Plugin

First, you need to enable the plugin by adding the following line to the top of your Beancount ledger file:

plugin "fava.plugins.forecast"

Step 2: Create a Forecast Transaction

To forecast a recurring transaction, create a single transaction entry using the # flag (instead of * or !) and add a special forecast tag to the narration.

The basic structure looks like this:

YYYY-MM-DD # "Narration [FREQUENCY CONDITIONS]"
  Account:One      100.00 USD
  Account:Two     -100.00 USD

The forecast plugin will use this entry as a template to generate future transactions in your reports.

Understanding the Forecast Syntax

The forecast tag in the narration follows a specific format: [FREQUENCY CONDITIONS].

Frequency

The FREQUENCY part is mandatory and defines how often the transaction recurs. It must be in all caps.

• DAILY
• WEEKLY
• MONTHLY
• QUARTERLY
• YEARLY

Example: A Monthly Rent Payment This transaction will be projected to occur on the 1st of every month, starting from January 2024.

2024-01-01 # "Rent payment [MONTHLY]"
  Expenses:Housing:Rent            2500.00 USD
  Assets:Checking                 -2500.00 USD

Conditions (Optional)

You can add optional CONDITIONS to control the forecast's duration and pattern.

1. Set an End Date with UNTIL Use UNTIL YYYY-MM-DD to stop the forecast on a specific date.

• Example: A Gym membership that ends this year.

  2024-01-15 # "Gym membership [MONTHLY UNTIL 2024-12-31]"
    Expenses:Health:Gym                 80.00 USD
    Assets:Checking                    -80.00 USD

2. Limit Occurrences with REPEAT Use REPEAT n TIMES to generate the transaction a specific number of times.

• Example: A car loan with 36 remaining payments.

  2024-01-25 # "Car payment [MONTHLY REPEAT 36 TIMES]"
    Expenses:Transportation:CarPayment  450.00 USD
    Liabilities:Auto-Loan              -450.00 USD

3. Create Irregular Patterns with SKIP Use SKIP n TIME/TIMES to skip intervals. This is useful for things like bi-weekly paychecks.

• Example: A bi-weekly salary (occurs every two weeks).

  2024-01-05 # "Bi-weekly salary [WEEKLY SKIP 1 TIME]"
    Assets:Checking                    3000.00 USD
    Income:Salary                     -3000.00 USD

Practical Example: A Monthly Budget

You can combine multiple forecasts to project your entire budget, including various income and expense streams.

plugin "fava.plugins.forecast"

; === INCOME ===
2024-01-05 # "Bi-weekly salary [WEEKLY SKIP 1 TIME]"
  Assets:Checking                    3000.00 USD
  Income:Salary                     -3000.00 USD

; === EXPENSES ===
2024-01-01 # "Rent [MONTHLY]"
  Expenses:Housing:Rent            2500.00 USD
  Assets:Checking                 -2500.00 USD

2024-01-01 # "Groceries [WEEKLY]"
  Expenses:Food:Groceries           150.00 USD
  Assets:Checking                  -150.00 USD

2024-01-15 # "Car Insurance [QUARTERLY REPEAT 4 TIMES]"
  Expenses:Insurance:Auto           450.00 USD
  Assets:Checking                  -450.00 USD

Once you add these entries, your reports, such as the Income Statement and Net Profit chart, will automatically include the projected data, giving you a clear view of your financial future.

Troubleshooting & Best Practices

• Forecasts Not Appearing?

  • Ensure plugin "fava.plugins.forecast" is in your ledger file.
  • Use the # flag for the transaction, not *.
  • Check for typos in the frequency tag (e.g., [MONTHLY] not [Monthly] or [MONTLY]).

• Best Practices

  • Be Descriptive: Use clear narrations so you know what each forecast is for.
  • Review Regularly: Update your forecasts (e.g., for a salary increase or rent change) to keep them accurate.
  • Use End Conditions: For transactions that aren't permanent (like loans or subscriptions), use UNTIL or REPEAT to prevent them from forecasting indefinitely.