#595 Measures: running balances from changes, and one change index per timeline
–
- github
- github/openchronology/timeline-app
- github/openchronology/timeline-app#595
- issue
- state:closed
Follow-up to #570. A measure's values can be **changes** (deltas), and its **balance** at any time is a known anchor plus the changes on one side of that time. - **Opening value S:** the balance at t is S + (the total of everything up to t). - **Closing value X:** the balance at t is X − (the total of everything after t). ## Declaring ```json "cost": { "type": "mpz", "durations": "end", "balance": { "at": "end", "value": "125000" } } ``` - **`durations`:** `"start"` (the default) or `"end"`. It says where each duration's change applies. It governs both the measure's totals and its balance, so the two always agree. - **`balance`:** optional. `at` is `"start"` (an opening balance, before everything), `"end"` (a closing balance, after everything), or an exact time (the balance just after that time's changes, like a statement's closing balance). `value` is exact, in the measure's type. ## Semantics - **Simultaneous changes:** changes at the same time apply together, with no order among them. The balance changes only between times. - **Right-continuous:** the balance *at* t includes the changes at t. The balance *before* t excludes them. - **Window edges:** - the left edge reports the balance just before any change in the window, excluding changes exactly at the left edge; - the right edge reports the balance after every change in it, including changes exactly at the right edge. - **Ongoing durations** counted at their end apply nothing until they end. - **Moving ends:** ends that follow a moment move with it. - **Comparisons:** each timeline keeps its own balance, as with totals (#586). ## One change index per timeline, in every engine The index is keyed by the time each change applies, and holds only measure values, not counts: - a moment contributes at its time; - a duration at its start or end, as each measure says. Each node keeps its subtree's totals, so: - **Balance anywhere:** one descent gives the total up to any time, in O(log n). An edit rewrites one path. - **Summaries' totals partition the window.** Each summary covers from its first time up to the next summary's first; the first summary also covers the window's start, and the last its end. Every change in the window counts exactly once, bands' included. A summary's total equals the balance after it minus the balance before it. It replaces the per-node totals of the moment and duration trees (#574, #576) as the source of summaries' totals. - **Browser:** a `MeasureTree` of changes. - **PostgreSQL:** an AVL tree of change points, like the moment tree. - **SQLite:** a `rational_index` with sums. Today durations are summed with a scan. ## What uses it - **Overviews:** - `balances: { before, after }` at the window's edges, for measures with a balance; - each summary's `balanceAfter`; - partitioned `totals`. - **Editor:** - the balance at the window's edges; - "before → after" in the reader and hover cards; - a `balance` background chart kind, drawn as a step line. - **Plugins:** `api.balance(name)`. ## Order of work 1. Declarations, the browser index, partitioned totals and balances in browser frames. 2. PostgreSQL change tree and overviews. 3. SQLite change index. 4. Editor readouts, reader and hover, the balance chart, and `api.balance`. https://github.com/circagraph/timeline-app/issues/595
Related
- #570 Measures: typed quantities on moments and durations, totalled in every summary
- #574 Measures 3: totals in the summary trees (browser, PostgreSQL, SQLite)
- #576 Measures 5: durations' measures counted where they start
- #586 Measures: comparisons keep totals per timeline, never added across them
- #596 Measures: balances, durations at start or end, and totals that split the window (#595)
- #597 Measures: the PostgreSQL change index, balances and split totals (#595)
- #598 Measures: the SQLite change index for desktop files (#595)
- #602 Measures: balances in the editor, a balance chart and api.balance (#595)
- #609 Balance charts and readouts follow the view on servers and desktop files
- #621 Drawing a moments chart no longer doubles measures' balances
- Measures: the PostgreSQL change index, balances and split totals (#595)
- Drawing a moments chart no longer doubles measures' balances
- Merge pull request #598 from openchronology/feat/595-sqlite-balances
- Merge pull request #596 from openchronology/feat/595-balances
- Merge pull request #597 from openchronology/feat/595-postgres-balances
- Measures: balances in the editor, a balance chart and api.balance (#595)
- Measures: the SQLite change index, so desktop files split totals and keep balances (#595)
- Measures: balances, durations at start or end, and totals that split the window (#595)
- Balance charts and readouts follow the view on servers and desktop files
- Every measure chart is drawn, each with a value axis on the right
- Merge pull request #602 from openchronology/feat/595-balance-readouts
Open #595 Measures: running balances from changes, and one change index per timeline in the timeline