Chart Annotations

A chart is good at showing you that something changed. It cannot tell you why. Chart annotations are where you write that down: click a point on a Dashboard chart and record what was happening, so that next month you still know what the spike was about.

An annotation belongs to a measurement at a point in time, not to a single chart. If you write an annotation on your glucose, it appears on every chart of your glucose, at whatever granularity that chart is showing.

Writing an annotation

Click any point on a chart. A small editor opens showing the date, the value at that point, and a box for your annotation. Type what happened and press Save.

The date recorded is the bucket you clicked, not the moment you clicked it. An annotation written on a monthly chart is about that month, so it stays where you put it rather than moving to today.

You can write more than one annotation on the same point. Open it again and a fresh box is offered below the annotations already there.

Where your annotations appear

Annotations appear as small chips in a lane underneath the chart, lined up with the point they belong to. Hover a chip to read the full annotation, or click it to edit or delete it.

When several annotations fall close together, they merge into one chip that says how many there are. Click it and the editor lists all of them, so a busy week does not turn into a row of chips on top of each other.

One annotation, every chart

Annotations follow the measurement. Two things fall out of that, both deliberate:

• An annotation written on a daily chart also appears on a weekly or monthly chart of the same measurement, in the bucket that contains it. Write it once and it shows up wherever you look at that data.
• Units do not matter. An annotation written on a chart in miles appears on a chart of the same measurement drawn in kilometers, and an annotation on mg/dL glucose appears on the mmol/L chart.

Annotations that came with a reading

Some readings arrive from your Sources with a comment already attached, and for measurements that record a single value, such as Glucose, Oxygen, and Temperature, that comment is shown as an annotation too.

These are marked as belonging to the measurement itself, because they are part of the reading rather than something written on the chart. To change one, edit the reading in your FitnessSyncer Notebook. You can still add your own annotation to the same point.

Which charts take annotations

Any chart whose horizontal axis is time: line, area, line with range, column, stacked column, stream graph, and box plot charts all take annotations.

Charts that plot something other than time along the bottom do not, because there is no date to attach an annotation to. That covers scatter charts, histograms, heat maps, the Day chart, pie and donut charts, gauges, and KPI tiles.

Calculated measurements do not take annotations either. An Estimated A1C, a Percent in Range, or a Sleep Debt is worked out from other readings rather than recorded, so there is no reading there to comment on. Write the annotation on the readings underneath instead.

If you would rather a particular chart did not show annotations and you are a FitnessSyncer Pro user, open the chart’s settings in the Dashboard editor and turn them off for that chart.

Your Annotations

The annotations icon on the Dashboard toolbar opens Your Annotations, which lists every annotation you have written in one table, a hundred at a time.

Both the date and the text are editable there. Change a cell, press Save, and the annotation moves or reads differently everywhere it appears. The measurement an annotation belongs to cannot be changed, because that would move it onto charts you never chose.

Exporting and importing

Your Annotations also carries an Export button and a drop box for importing, so you can keep a copy of your annotations or write a batch of them somewhere else and bring them in.

Export downloads every annotation as a CSV file with four columns:

• Date: when the annotation applies, written as an ISO date and time in UTC.
• DataField: the measurement the annotation is about, in the form FitnessSyncer uses internally, such as GLUCOSE_MMOL_PER_L.
• Measurement: the readable name of that measurement. This column is for your benefit when reading the file and is ignored on import.
• Note: your text.

Import reads a file of the same shape. An annotation is identified by its date and its measurement rather than by an id, so a file you exported, edited, and imported again updates the annotations it describes instead of creating a second copy of each.

A row that cannot be read does not stop the file. A row naming a measurement FitnessSyncer does not recognize, carrying a date that will not parse, or leaving the annotation empty is skipped, and the import tells you how many rows were created, how many were updated, how many were skipped, and which lines they were. Annotations longer than a thousand characters are shortened rather than rejected.

In the apps

Annotations are shown on charts in the FitnessSyncer apps for iOS and Android, and are read-only there. Write and edit them on the web.