New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add `--available` option to `hledger register` #638

Closed
wants to merge 5 commits into
base: master
from

Conversation

Projects
None yet
3 participants
@eamsden

eamsden commented Oct 31, 2017

This PR adds a flag --available to the hledger register command. This flag shows minimum future balances after postings, condensing postings postings whose minimum future balance is the same to show only postings at which the minimum future balance changes.

This is useful if one is using hledger for budgeting e.g. by keeping predicted future transactions in a journal file, as it shows how much money can be spent without sending the balance negative at any point in the future.

Example usage:

$ hledger register -p "from yesterday to 2018/12/31" -f "budget.journal" --available assets:checking

This PR is incomplete. In particular, there are no tests for the added functions yet. Comments and constructive criticism would be very helpful.

@ony

This comment has been minimized.

Show comment
Hide comment
@ony

ony Nov 26, 2017

Collaborator

Having a mockups and/or shell-tests might improve attraction to this pull-request, I believe.
I'm not sure I understand
Please correct me if I misunderstand wanted behaviour.

  • You have pre-generated/crafted budget.journal that contains future transactions.
  • You want to find moment of time and accounts that will reach zero or will go below it with next posting honoring --date2 if specified.
    Is that correct?
Collaborator

ony commented Nov 26, 2017

Having a mockups and/or shell-tests might improve attraction to this pull-request, I believe.
I'm not sure I understand
Please correct me if I misunderstand wanted behaviour.

  • You have pre-generated/crafted budget.journal that contains future transactions.
  • You want to find moment of time and accounts that will reach zero or will go below it with next posting honoring --date2 if specified.
    Is that correct?
@eamsden

This comment has been minimized.

Show comment
Hide comment
@eamsden

eamsden Nov 26, 2017

@ony

  • You have a pre-generated/crafted budget.journal that contains future transactions.

Correct.

  • You want to find moment of time and accounts that will reach zero or will go below it with next posting honoring --date2 if specified.

Sort of, not really.

I want to know how much more could be spent from an account without sending it below zero in the future. It answers the question: "How much is unallocated from this account in the budget?"

The standard behavior of the register command is to keep a running total of every posting it encounters. The -H/--historical command adds the balance from all prior postings (matching the filter) to this running total. The --available command does this, but then looks forward from each transaction and finds the smallest running total in the future and displays that. Because this will generally be the same for several subsequent transactions, --available also elides subsequent transactions with the same minimum future balance.

Hope this helps. I'll be pushing the shell test to this branch as soon as I get it passing.

eamsden commented Nov 26, 2017

@ony

  • You have a pre-generated/crafted budget.journal that contains future transactions.

Correct.

  • You want to find moment of time and accounts that will reach zero or will go below it with next posting honoring --date2 if specified.

Sort of, not really.

I want to know how much more could be spent from an account without sending it below zero in the future. It answers the question: "How much is unallocated from this account in the budget?"

The standard behavior of the register command is to keep a running total of every posting it encounters. The -H/--historical command adds the balance from all prior postings (matching the filter) to this running total. The --available command does this, but then looks forward from each transaction and finds the smallest running total in the future and displays that. Because this will generally be the same for several subsequent transactions, --available also elides subsequent transactions with the same minimum future balance.

Hope this helps. I'll be pushing the shell test to this branch as soon as I get it passing.

@simonmichael

This comment has been minimized.

Show comment
Hide comment
@simonmichael

simonmichael Nov 27, 2017

Owner

Thanks for this @eamsden. @ony is right, a mockup or demo of this in action, and draft documentation (no need for commits yet) would help a lot to explain this.

How will this relate with the forecasting/budgeting-related features just landed in #654 ?

Owner

simonmichael commented Nov 27, 2017

Thanks for this @eamsden. @ony is right, a mockup or demo of this in action, and draft documentation (no need for commits yet) would help a lot to explain this.

How will this relate with the forecasting/budgeting-related features just landed in #654 ?

@eamsden

This comment has been minimized.

Show comment
Hide comment
@eamsden

eamsden Nov 27, 2017

@ony @simonmichael I just added a shell test that shows it in action.
Where would draft docs go if not in a commit?

I've been reading over #654 during a compile, still wrapping my head around it. Will report back.

eamsden commented Nov 27, 2017

@ony @simonmichael I just added a shell test that shows it in action.
Where would draft docs go if not in a commit?

I've been reading over #654 during a compile, still wrapping my head around it. Will report back.

@eamsden

This comment has been minimized.

Show comment
Hide comment
@eamsden

eamsden Nov 27, 2017

@simonmichael @ony my understanding of #654 is that it adds --budget and --forecast options akin to ledger. Is that correct?

If so, then the relation is that --budget and --forecast allow you to specify your budget expectations as periodic transactions, receive reports about how far your actual spending was from budgeted spending, and forecast future balances according to those periodic transactions.

This change deals instead with budgeting by simply writing down predicted future transactions as real transactions, and allows computation of the minimum balance in the future given a budget in that style.
So for people who keep a budget as future real transactions, rather than ledger --budget-style periodic transactions.

eamsden commented Nov 27, 2017

@simonmichael @ony my understanding of #654 is that it adds --budget and --forecast options akin to ledger. Is that correct?

If so, then the relation is that --budget and --forecast allow you to specify your budget expectations as periodic transactions, receive reports about how far your actual spending was from budgeted spending, and forecast future balances according to those periodic transactions.

This change deals instead with budgeting by simply writing down predicted future transactions as real transactions, and allows computation of the minimum balance in the future given a budget in that style.
So for people who keep a budget as future real transactions, rather than ledger --budget-style periodic transactions.

@simonmichael

This comment has been minimized.

Show comment
Hide comment
@simonmichael

simonmichael Nov 27, 2017

Owner

Ok, that's how I have always done forecasting - write ordinary transactions with future dates, see what register or a multiperiod balance report show. Using register especially I can see when a balance goes negative, or the low point, pretty easily. I don't see the problem you have solved here, yet.

Draft docs can go right here, or on a gist if easier. Eg the --available flag's help text (from command line) and manual text (from hledger manual -> register command).

Owner

simonmichael commented Nov 27, 2017

Ok, that's how I have always done forecasting - write ordinary transactions with future dates, see what register or a multiperiod balance report show. Using register especially I can see when a balance goes negative, or the low point, pretty easily. I don't see the problem you have solved here, yet.

Draft docs can go right here, or on a gist if easier. Eg the --available flag's help text (from command line) and manual text (from hledger manual -> register command).

@simonmichael

This comment has been minimized.

Show comment
Hide comment
@simonmichael

simonmichael Nov 27, 2017

Owner

Help text: "show available balance (minimum future balance in given period)"

Owner

simonmichael commented Nov 27, 2017

Help text: "show available balance (minimum future balance in given period)"

@simonmichael

This comment has been minimized.

Show comment
Hide comment
@simonmichael

simonmichael Nov 27, 2017

Owner

The example from the test, expanded:

$ cat $LEDGER_FILE
2018/1/1 x
  a  1
  b

2018/1/2 y
  a  -0.5
  b

2018/1/3 x
  a  1
  b

2018/1/4 z
  a  -1.25
  b  

2018/1/5 x
  a   1
  b

2018/1/6 y
  a   -0.5
  b

$ hledger reg a
2018/01/01 x                  a                          1.00          1.00
2018/01/02 y                  a                         -0.50          0.50
2018/01/03 x                  a                          1.00          1.50
2018/01/04 z                  a                         -1.25          0.25
2018/01/05 x                  a                          1.00          1.25
2018/01/06 y                  a                         -0.50          0.75
$ hledger reg a --available
2018/01/01 x                    a                             1.00          0.25
2018/01/05 x                    a                             1.00          0.75
Owner

simonmichael commented Nov 27, 2017

The example from the test, expanded:

$ cat $LEDGER_FILE
2018/1/1 x
  a  1
  b

2018/1/2 y
  a  -0.5
  b

2018/1/3 x
  a  1
  b

2018/1/4 z
  a  -1.25
  b  

2018/1/5 x
  a   1
  b

2018/1/6 y
  a   -0.5
  b

$ hledger reg a
2018/01/01 x                  a                          1.00          1.00
2018/01/02 y                  a                         -0.50          0.50
2018/01/03 x                  a                          1.00          1.50
2018/01/04 z                  a                         -1.25          0.25
2018/01/05 x                  a                          1.00          1.25
2018/01/06 y                  a                         -0.50          0.75
$ hledger reg a --available
2018/01/01 x                    a                             1.00          0.25
2018/01/05 x                    a                             1.00          0.75
b
>>>
2018/01/01 x a 1.00 0.25
2018/01/05 x a 1.00 0.75

This comment has been minimized.

@ony

ony Nov 28, 2017

Collaborator

Why we get two lines for same account here having different values 0.25 and 0.75?
I expected only one with date and minimum value (even if it is negative honoring the sign).

@ony

ony Nov 28, 2017

Collaborator

Why we get two lines for same account here having different values 0.25 and 0.75?
I expected only one with date and minimum value (even if it is negative honoring the sign).

This comment has been minimized.

@simonmichael

simonmichael Nov 28, 2017

Owner

I had the same question. It reports all the minima (of a curve plotting balance over time), not just the lowest minimum.

@simonmichael

simonmichael Nov 28, 2017

Owner

I had the same question. It reports all the minima (of a curve plotting balance over time), not just the lowest minimum.

@ony

This comment has been minimized.

Show comment
Hide comment
@ony

ony Nov 28, 2017

Collaborator

I see benefit of that query. If I understand correctly ideal output is one or few lines where running total reaches its minimum individually per commodity (i.e. assuming that commodities are not interchangeable unless something like -V specified).

2018/01/01 x                    a                            -1.25 EUR          0.25 EUR
2018/01/05 y                    a                            -0.50 CHF          0.75 CHF

I also can identify few cases when you may want to use power of query and select multiple accounts like hledger reg --available assets:cash assets:bank:current.

So it looks like output is mostly per-commodity for a particular set of accounts. I have feeling that it worth a separate report command. Might be prototyped as an external addon which I believe can be merged and dropped more easily.

Collaborator

ony commented Nov 28, 2017

I see benefit of that query. If I understand correctly ideal output is one or few lines where running total reaches its minimum individually per commodity (i.e. assuming that commodities are not interchangeable unless something like -V specified).

2018/01/01 x                    a                            -1.25 EUR          0.25 EUR
2018/01/05 y                    a                            -0.50 CHF          0.75 CHF

I also can identify few cases when you may want to use power of query and select multiple accounts like hledger reg --available assets:cash assets:bank:current.

So it looks like output is mostly per-commodity for a particular set of accounts. I have feeling that it worth a separate report command. Might be prototyped as an external addon which I believe can be merged and dropped more easily.

@simonmichael

This comment has been minimized.

Show comment
Hide comment
@simonmichael

simonmichael Nov 28, 2017

Owner

Good point about multiple commodities, yes it would need to report minima of each one.

Owner

simonmichael commented Nov 28, 2017

Good point about multiple commodities, yes it would need to report minima of each one.

@simonmichael

This comment has been minimized.

Show comment
Hide comment
@simonmichael

simonmichael Mar 12, 2018

Owner

@eamsden are you still interested in this ? Do I remember rightly that we chatted and agreed that renaming to --minima, adding --maxima, making sure multiple commodities are handled right, and adding to the manual would be useful next steps ?

Owner

simonmichael commented Mar 12, 2018

@eamsden are you still interested in this ? Do I remember rightly that we chatted and agreed that renaming to --minima, adding --maxima, making sure multiple commodities are handled right, and adding to the manual would be useful next steps ?

@eamsden

This comment has been minimized.

Show comment
Hide comment
@eamsden

eamsden Mar 16, 2018

@simonmichael I am still interested, it's just a question of getting time to work on it :\

eamsden commented Mar 16, 2018

@simonmichael I am still interested, it's just a question of getting time to work on it :\

@simonmichael

This comment has been minimized.

Show comment
Hide comment
@simonmichael

simonmichael Mar 16, 2018

Owner

Understood! No problem, I'll leave this open then.

Owner

simonmichael commented Mar 16, 2018

Understood! No problem, I'll leave this open then.

@simonmichael

This comment has been minimized.

Show comment
Hide comment
@simonmichael

simonmichael Apr 9, 2018

Owner

Inactive, closing for now.

Owner

simonmichael commented Apr 9, 2018

Inactive, closing for now.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment