A Visualization is one or more trackables’ series, how they are drawn, and the question asked of them. One of a single trackable is one of that trackable’s tabs; one of several is a visualization in its own right, compared in the Editor for Several Trackables. It is one glossary term, Visualization, whose banned spellings include Analysis, Display and View. Everything you look at in the app is one: a trackable’s page and its Home card show its tabs, Home shows the ones pinned to it, and the Calendar and Table pages are the calendar and the table over every trackable at once.
The kinds a trackable’s visualization can be
The kinds are VisualizationKind in packages/core/src/value-schema.ts: Chart, Calendar, Day, Timeline, Distribution, Scatter and Table. Which a trackable can have is decided by kindsFor in apps/renderer/src/lib/visualizations.ts: Chart, Calendar, Day and Table always; Timeline where its entries sit on a 24-hour axis (it has an interval, or logs moments with a time and is not answered for the whole day); Distribution where its days spread over values; Scatter where it logs a catalog’s items (Catalog Scatter). With none stored, a trackable has the ones its shape suggests: it opens on its Table if it is words, its Day if it logs amounts of catalog items, and otherwise its Chart, followed by the rest. Day is always among them.
A surface leaves out what it cannot draw: a Chart with nothing to plot, the Table on a Home card, and a Day, Timeline, Distribution or Scatter for a tag. A yes/no has a Chart, bars of its yes days or, where chosen, a heat strip, as has a number whose chart is read as Any; it still opens on its Calendar, which shows the heat of its days. The tab does not depend on the type chosen, so picking the heat strip never takes it away. A trackable of fields (Strength) has a Chart, each number field charted on its own (RecordFieldCharts). One rule says so for its page, its card and the editor alike (hasChart), asked of the trackable as saved, so a Reading picked on a page or card only to look does not take the tab away.
- Chart: its values a day over the period; see Chart.
- Calendar: a contribution grid of the period’s days, shaded by value, count or presence, the same on a Home card, a trackable’s page and in the editor, a day opening what was logged on it; see Calendar Drill-down.
- Table: its entries; see Data Table.
- Day: the day set in the top bar, which is not always today. First what the day came to, by the trackable’s shape, then each of the day’s entries with its time, value, note and issues, each opening to edit.
| shape | what the day came to |
|---|---|
| a number that adds up (Water) | the day’s total, against its target |
| a number read as a level (Weight, a mood) | the day’s reading, and its range when logged more than once |
| amounts of catalog items (Diet) | the totals of the catalog’s numbers |
| an interval (Sleep, Read, Meditate) | how many entries and their total time, and a strip of the day on the Timeline’s 24-hour axis |
| a yes/no, options, words | the day’s answer |
| fields beside the value or alone (Strength) | its declared summaries, or each number field’s total |
| asked more than once a day | how many of its Cadence’s times are answered (“1 of 2”) |
- Timeline: the entries on a 24-hour axis, one day per column with the hours running down by default, or one per row (
orientation: "horizontal"), newest first. An entry with an interval is a bar from start to end that opens it; one still running is drawn to now, paler; one open past its stale limit is a mark at its start; one with only an end is a mark there; a moment is a mark at its time; a Nothing has no time and is not drawn. The 24 hours start at the Day Boundary (starts), which is either set or worked out: midnight, unless finished entries cross it, and then the middle of the longest run of hours they cover least. A row that starts after noon is named for the next day, as a night is dated by its morning. - Distribution: how many days of the period fell at each option, each yes/no word, or each range of a number, beside the period before (paler), in the options’ own colours.
- Scatter: the catalog items it logged, placed on two of the catalog’s numbers.
The question it holds
Each of a trackable’s visualizations is a VisualizationSpec, so its page and its Home card ask the same question of the same days:
| field | what it sets |
|---|---|
period | the days it covers, ending today, or every day; per kind, Chart 7 to 365 days or all (30 by default), Calendar 91, 182 or 364 (182), Timeline 7 to 60 (14), Distribution 7 to 90 (30), Scatter as Chart (30); a Day and a Table have none |
compare | what its headline is set against: the period before (the default), the trackable’s zones, or nothing. Zones apply only while it is read by the trackable’s own Reading and the trackable has a zone; otherwise it is the period before, in the settings and the headline alike (comparisonOf) |
headline | how the period folds into one value: Sum, Mean, Median, Min, Max, how many days, or the option most often, offered by the kind of value (a level has no Sum); by the kind of value when unset |
reading | the trackable read another way than its own (Journal read as Any); see Readings |
select | which of its entries it reads: a time of day, items, a Category value, a Routine, the narrowings a derived trackable’s Reading has (Derived Authoring). For a Chart, a Calendar and a Distribution of a trackable you log (narrowsOf); the Chart’s field charts are narrowed with it, and the drawing says “Entries: Run” under its headline so a narrowed chart is never taken for the whole trackable. Every entry while unset |
scale, direction | a calendar’s: what a cell encodes, and which end of its ramp is light |
chart | a chart’s type |
starts, orientation | a timeline’s |
axes | a scatter’s catalog values |
color | its own colour |
pinned | on Home as a card of its own |
The headline is the period read as one value and how it stands: “78.5 kg, Mean of the last 90 days · 76 of 90 days in Healthy”, “Low, Most often, 17 of 30 days · Okay in the 30 days before”, “89 of 182 days”. Days on hold that were not answered are left out of what a count is out of. It is hidden when neither the period nor the one before has a day.
A visualization of several is a different spec, the renderer’s SeriesSpec; both are stored the same way (Visualization Persistence).
Where it shows
On a trackable, as tabs on its Home card and its page: its own visualizations in its order, then every visualization of several placed on it that still reads it (placedOn). The page’s address picks the open tab for a visit (/trackables/read?id=…&mode=…, a kind or visualization:<id>), so a visualization can be linked to without changing the trackable. A trackable’s page also lists, under Visualizations, every visualization of several that reads it, with the other trackables each reads. On Home, a pinned one is a card of its own (see Home). All visualizations of several are listed at /visualizations, with New visualization.
A kind is drawn the same wherever it is open: VisualizationDrawing (components/visualizations/VisualizationBody.tsx) is the one place a kind is given its drawing, for a Home card, the editor and a trackable’s page, and a source test (drawings.test.ts) keeps the page from choosing one again. The page draws it framed, each kind on a card of the page’s height, a Day under its date and the headline over a Table too, and a tag hands it its members.
A tag’s Chart, Calendar and Table cover every trackable under it: its members as small multiples (Chart), a contribution grid of how many entries each day has under it, and the table of them; the rest of its page is in Tags. A derived trackable’s values are one a day and it has no entries of its own: its Table says it is computed on read, and, when it has no members, its Calendar is the contribution grid of its days.
Which controls save
Visualizations are made and changed in one editor, opened from a card’s or a page’s settings button on the open tab (Editor for Several Trackables), where the drawing changes as you change it and nothing is kept until Save. A trackable’s page and its Home card are for looking. Pin to Home is the only control on a page or a card that saves: it pins or unpins the open visualization. The period chips and the Reading picker on a trackable’s page, and the Reading picker and a calendar’s scale on a Home card, change only what is shown there, while it is open (useLook, which lays them over the saved settings with withLooks). The editor and Pin to Home save, through useSaveVisualization.
Series colours
A trackable’s colour is a default. A visualization can set its own per series (SeriesSpec.colors), and a trackable’s tab its own (VisualizationSpec.color); a trackable’s values keep their colours on the trackable or its catalog (a scale’s options, a category’s values, its zones). In a comparison, in series order, a series with no colour of its own whose default is too close to an earlier series’ (under 0.1 apart in OKLab, distinctColors in lib/series-colors.ts) takes the next chart colour that is not. Any CSS colour compares, a custom property included (cssColorRgb). The colour is picked beside each series in the editor, and as a tab’s Color in its settings, with the library’s ColorPicker and Default for the trackable’s.
Words a visualization uses
Cadence (stored as check_in) is where in the day a trackable is expected and how many times: the Day’s “1 of 2” reads it, and so does the issue a day left unanswered raises. Untracked is a day with nothing logged anywhere: hollow in a trackable’s calendar, dashed in the month grid.
One series primitive
A trackable you log has its days folded from its entries by one function, dailyValues (apps/renderer/src/lib/series.ts), by its aggregation or a Reading’s; a derived trackable’s days are computed on read by the derived evaluator. useTrackableSeriesMap (hooks/useTrackableSeriesMap.ts) resolves a list of trackables, or Readings of them, through those two, for the editor for several, Home’s derived cards and a tag’s charts. A narrowed series is read there as the derived Reading of the same choices (narrowedReading in packages/core/src/reading-id.ts, worked out by the evaluator), so a chart and a derived trackable narrowed alike read alike. A card, a page and the editor’s one-trackable panes read their visualization through one hook, useVisualizationReading: its Reading through readSeries (lib/read-series.ts), and a narrowed one through the series map, which calls the same fold for a trackable you log and re-reads a derived one’s computed days as the evaluator does (Any is Yes on a day with a value, a 0 counting as none only where the kind’s 0 means none, zeroIsFalse; Count is 1). So a card, a page and a comparison fold a trackable’s entries the same way.
Related
Chart · Calendar Drill-down · Data Table · Catalog Scatter · Editor for Several Trackables · Visualization Persistence · Home · Presentation Layer