Graph matrix (aka road) data structure documentation

### Desiderata
- [ ] Decide where this should live
- [ ] Move it there

Possibly this should go into a wiki, or into the code as doc strings somewhere, but for now:

Beebrain, starting with the javascript incarnation, implements the following data structure to describe your bright red line (it helps with drawing them in D3):

## Road (now redline) struct is a list of segments:

[{
  sta -> [t1, v1],
  end -> [t2, v2],
  slope -> (v2 - v1) / (t2 - t1),
  auto in {0, 1, 2} (i.e. DATE, VALUE, RATE)
}, 
...
]

We also discovered a gotcha here. There are dummy rows added to the beginning and end of the graph matrix which start 100 days before tini, and end 100 days after tfin. I think these are for the sake of the graph editor, so you can scroll to (and by extension, are able to change the goal/graph to) times before the red line started, or after it is set to end.

However, some functions (like lnf in the past, though that doesn't exist now) of the first segment throw an error (no property sta of undefined), so the introduction of this data structure means that the programmer either needs to know to filter those segments out before doing certain operations, or functions that operate on a road struct need to have error checking around the bounds of the road that they are attached to.

My first instinct is that if those rows are needed for the sake of the graph editor, they ought to be added at the last possible minute before rendering in the graph editor, and otherwise the road struct should start with tini and end with tfin. However, as I don't fully grok the reason for / use of those rows, that could be totally wrong-headed.

Anyhow, we probably need to document the road struct a little more thoroughly and possibly refactor stuff with those dummy rows.

Cognata

https://github.com/beeminder/beeminder/issues/750 (CHAINY vs CHUNKY structure)

Verbata: piecewise linear bright red line, road matrix, graph matrix, true breaks, d3,

Beebrain, starting with the javascript incarnation, implements a new data structure to describe your bright red line (probably to simplify drawing them with the graphing library etc?)

Just to record what I recall, this was implemented due to the particular way in which d3 associates svg elements with data. Each data element is required to have all the info required to draw its associated visual element. Consequently, in order to be able to draw road segments, I had implemented this structure wherein each array element contains both endpoints. That was of course back when I was just learning d3 as well, so I am sure one could find a better way of doing this, e.g. with indices and such. So, this is more historical than anything else I guess. There might be, as you observed, various gotchas that are due to my lack of foresight back then. I guess it might be possible to refactor some of this, or at least eliminate those gotchas as we discover and document them. For instance, the "no property of sta" should not be too difficult to eliminate by patching lnf. In any case, sorry!

beeminder / road

Graph matrix (aka road) data structure documentation #117

Cognata