slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

;doc: forecasting: rewrite

Browse Source
This commit is contained in:
Simon Michael 2023-04-21 10:41:42 -10:00
parent 93ee092ab7
commit 65fd7e821e
1 changed files with 125 additions and 45 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

170
hledger/hledger.m4.md
View File

@ -4867,62 +4867,140 @@ are built in to hledger's journal format:
# Forecasting # Forecasting
The `--forecast` flag activates any [periodic transaction rules](#periodic-transactions) Forecasting, or speculative future reporting, can be useful for estimating future balances, or for exploring different future scenarios.
in the journal. These will generate temporary additional transactions,
usually recurring and in the future, which will appear in all reports.
`hledger print --forecast` is a good way to see them.
This can be useful for estimating balances into the future, The simplest and most flexible way to do it with hledger is to manually record a bunch of future-dated transactions. You could keep these in a separate `future.journal` and include that with `-f` only when you want to see them.
perhaps experimenting with different scenarios.
It could also be useful for scripted data entry: you could describe recurring ## --forecast
transactions, and every so often copy the output of `print --forecast` There is another way: with the `--forecast` option, hledger can generate temporary "forecast transactions" for reporting purposes, according to [periodic transaction rules](#periodic-transactions) defined in the journal. Each rule can generate multiple recurring transactions, so by changing one rule you can change many forecasted transactions. (These same rules can also generate budget goals, described in [Budgeting](#budgeting).)
into the journal.
The generated transactions will have an extra [tag](#tags), like Forecast transactions usually start after ordinary transactions end. By default, they begin after your latest-dated ordinary transaction, or today, whichever is later, and they end six months from today. (The exact rules are a little more complicated, and are given below.)
`generated-transaction:~ PERIODICEXPR`,
indicating which periodic rule generated them.
There is also a similar, hidden tag, named `_generated-transaction:`,
which you can use to reliably match transactions generated "just now"
(rather than `print`ed in the past).
The forecast transactions are generated within a *forecast period*, This is the "forecast period", which need not be the same as the [report period](#report-period).
which is independent of the [report period](#report-start--end-date). You can override it - eg to forecast farther into the future, or to force forecast transactions to overlap your ordinary transactions - by giving the --forecast option a [period expression](#period-expressions) argument, like `--forecast=..2099` or `--forecast=2023-02-15..`. Note that the `=` is required.
(Forecast period sets the bounds for generated transactions,
report period controls which transactions are reported.)
The forecast period begins on:
- the start date provided within `--forecast`'s argument, if any ## Inspecting forecast transactions
- otherwise, the later of
- the report start date, if specified (with `-b`/`-p`/`date:`)
- the day after the latest ordinary transaction in the journal, if any
- otherwise today.
It ends on: `print` is the best command for inspecting and troubleshooting forecast transactions. Eg:
```journal
~ monthly from 2022-12-20 rent
assets:bank:checking
expenses:rent $1000
```
```terminal
$ hledger print --forecast --today=2023/4/21
2023-05-20 rent
; generated-transaction: ~ monthly from 2022-12-20
assets:bank:checking
expenses:rent $1000
- the end date provided within `--forecast`'s argument, if any 2023-06-20 rent
- otherwise, the report end date, if specified (with `-e`/`-p`/`date:`) ; generated-transaction: ~ monthly from 2022-12-20
- otherwise 180 days (6 months) from today. assets:bank:checking
expenses:rent $1000
Note, this means that ordinary transactions will suppress periodic transactions, 2023-07-20 rent
by default; the periodic transactions will not start until after the last ordinary transaction. ; generated-transaction: ~ monthly from 2022-12-20
This is usually convenient, but you can get around it in two ways: assets:bank:checking
expenses:rent $1000
- If you need to record some transactions in the future, make them 2023-08-20 rent
periodic transactions (with a single occurrence, eg: `~ YYYY-MM-DD`) rather than ordinary transactions. ; generated-transaction: ~ monthly from 2022-12-20
That way they won't suppress other periodic transactions. assets:bank:checking
expenses:rent $1000
- Or give `--forecast` a [period expression](#period-expressions) argument. 2023-09-20 rent
A forecast period specified this way can overlap ordinary transactions, ; generated-transaction: ~ monthly from 2022-12-20
and need not be in the future. Some things to note: assets:bank:checking
expenses:rent $1000
```
- You must use `=` between flag and argument; a space won't work. Here there are no ordinary transactions, so the forecasted transactions begin on the first occurence after today's date.
- The period expression can specify the forecast period's start date, end date, or both. (You won't normally use `--today`; it's just to make these examples reproducible.)
See also [Report start & end date](#report-start--end-date).
- The period expression should not specify a [report interval](#report-intervals).
(Each periodic transaction rule specifies its own interval.)
Some examples: `--forecast=202001-202004`, `--forecast=jan-`, `--forecast=2021`. ## Forecast transaction tags
Note the `generated-transaction` tags added by hledger. They remind that these are temporary forecasted transactions, visible in reports only; and they show which rule was responsible. You can use these if you ever need to match forecast transactions in a query: `tag:generated-transaction`.
(The same tag is also present, hidden, with the name `_generated-transaction`. You could use this to match transactions generated "just now", in a situation where you have others previously generated and saved in the journal.)
## Forecast reports
Forecast transactions affect all reports, as you would expect. Eg:
```terminal
$ hledger areg rent --forecast --today=2023/4/21
Transactions in expenses:rent and subaccounts:
2023-05-20 rent as:ba:checking $1000 $1000
2023-06-20 rent as:ba:checking $1000 $2000
2023-07-20 rent as:ba:checking $1000 $3000
2023-08-20 rent as:ba:checking $1000 $4000
2023-09-20 rent as:ba:checking $1000 $5000
```
```terminal
$ hledger bal -M expenses --forecast --today=2023/4/21
Balance changes in 2023-05-01..2023-09-30:
|| May Jun Jul Aug Sep
===============++===================================
expenses:rent || $1000 $1000 $1000 $1000 $1000
---------------++-----------------------------------
|| $1000 $1000 $1000 $1000 $1000
```
## Forecast troubleshooting
When --forecast is not doing what you expect, here are some tips.
Can't see what it's doing ?
- Use `print --forecast`, as above.
No forecast transactions are visible ?
- Remember to use the `--forecast` option.
- Remember to create at least one periodic transaction rule in your journal.
- Check for typos or restrictive start/end dates in your periodic transaction rule.
- If your rule contains a transaction description, be sure to separate it from the period expression by at least 2 spaces.
- Check for a future dated ordinary transaction suppressing forecasted transactions.
- Set an explicit report end date with `-e`, `-p` or `date:`.
- Add the `-E` flag to encourage display of empty periods/zero transactions.
- Consult [Forecast period, in detail](#forecast-period-in-detail), below.
- Check the engine: add the `--debug=N` option, increasing N from 1 to 9 as needed.
Forecast transactions are visible, but starting or ending too soon/too late ?
- First, adjust (or remove) any start/end dates within your periodic transaction rule.
- Next try setting explicit report start and/or end dates with `-b`, `-e`, `-p` or `date:`.
- And/or override the forecast start and/or end date with `--forecast=STARTDATE..ENDDATE`
A future-dated transaction is making it harder to generate forecast transactions ?
- If you have recorded some important future event as an ordinary transaction, and it is interfering with easy --forecast-ing, you could consider making it a (non-recurring) forecast transaction instead. Just insert a `~` before the date and make sure there 2+ spaces after the date: `~ YYYY-MM-DD ...`. Then it won't suppress other forecast transactions (and you'll have to use `--forecast` to see it).
## Forecast period, in detail
Forecast start/end dates are chosen so as to do something useful by default in almost all situations, while also being flexible. Here are (with luck) the exact rules, to help with troubleshooting:
The forecast period starts on:
- the later of
- the start date in the periodic transaction rule
- the start date in `--forecast`'s argument
- or if neither of the above are available, the later of
- the day after the latest ordinary transaction in the journal
- the report start date specified with `-b`/`-p`/`date:`
- or if none of the above are available: today.
The forecast period ends on:
- the earlier of
- the end date in the periodic transaction rule
- the end date in `--forecast`'s argument
- or if neither of the above are available
- the report end date specified with `-e`/`-p`/`date:`
- or if none of the above are available: 180 days (~6 months) from today.
# Budgeting # Budgeting
@ -4930,7 +5008,9 @@ With the balance command's [`--budget` report](#budget-report),
each periodic transaction rule generates recurring budget goals in specified accounts, each periodic transaction rule generates recurring budget goals in specified accounts,
and goals and actual performance can be compared. and goals and actual performance can be compared.
See the balance command's doc below. See the balance command's doc below.
You can generate budget goals and forecast transactions at the same time, from the same or different periodic transaction rules: `hledger bal -M --budget --forecast ...`
See also: [Budgeting and Forecasting](/budgeting-and-forecasting.html). See also: [Budgeting and Forecasting](/budgeting-and-forecasting.html).