Identity

To move a mark, VisDelta has to know it is the same mark in A and B. Marks that match move; the others enter or leave.

KeysCopy Anchor Link

Give marks a key when they should keep their identity through a change:

point(cars).x('weight').y('mpg').key('name');
bar(sales).x('region').y('revenue').key(['region', 'channel']);

Without .key(), each chart type uses a sensible default. If marks fade in and out when you expected them to move, add a key.

Records and marks are differentCopy Anchor Link

A record is a row of your data. A mark is something drawn. When you total rows, many records become one mark, and the records still keep their own identity.

VisDelta finds record identity on its own: a unique id field if there is one, otherwise the smallest set of text fields that tells rows apart. Override it only when that guess would be wrong:

bar(rows).datumKey('id');

LineageCopy Anchor Link

With inline data, VisDelta also traces which records feed which marks in both states. That is how it knows a total split into parts, parts merged into a total, or groups were reaggregated:

delta(byYear, byLocation).lineage.mode; // 'reaggregate'

Lineage is evidence, not an order. Bar uses it to keep sums readable while they split and merge; averages and medians keep their history but move directly, because their parts don't add up to the whole.

The functions behind this are in Core.