feat: frame animations with time encoding and timer param

examples/specs/animated_gapminder.vl.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
+  "data": {
+    "url": "data/gapminder.json"
+  },
+  "mark": "point",
+  "params": [
+    {
+      "name": "avl",
+      "select": {
+        "type": "point",
+        "fields": [
+          "year"
+        ],
+        "on": "timer"
+      }
+    }
+  ],
+  "transform": [
+    {
+      "filter": {
+        "param": "avl"
+      }
+    }
+  ],
+  "encoding": {
+    "color": {
+      "field": "country"
+    },
+    "x": {
+      "field": "fertility",
+      "type": "quantitative"
+    },
+    "y": {
+      "field": "life_expect",
+      "type": "quantitative"
+    },
+    "time": {
+      "field": "year",
+      "type": "ordinal"
+    }
+  }
+}

examples/specs/animated_hop.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
+  "data": {
+    "url": "data/seattle-weather.csv"
+  },
+  "mark": "tick",
+  "config": {
+    "tick": {
+      "thickness": 3
+    }
+  },
+  "params": [
+    {
+      "name": "date",
+      "select": {
+        "type": "point",
+        "fields": [
+          "date"
+        ],
+        "on": "timer"
+      }
+    }
+  ],
+  "transform": [
+    {
+      "filter": {
+        "param": "date"
+      }
+    }
+  ],
+  "encoding": {
+    "y": {
+      "field": "precipitation",
+      "type": "quantitative"
+    },
+    "time": {
+      "field": "date",
+      "type": "ordinal"
+    }
+  }
+}

src/channel.ts

@@ -40,6 +40,9 @@ export const LONGITUDE = 'longitude' as const;
 export const LATITUDE2 = 'latitude2' as const;
 export const LONGITUDE2 = 'longitude2' as const;
 
+// Time
+export const TIME = 'time' as const;
+
 // Mark property with scale
 export const COLOR = 'color' as const;
 
@@ -135,6 +138,9 @@ const UNIT_CHANNEL_INDEX: Flag<Channel> = {
   fill: 1,
   stroke: 1,
 
+  // time
+  time: 1,
+
   // other non-position with scale
   opacity: 1,
   fillOpacity: 1,
@@ -424,6 +430,16 @@ export function isXorYOffset(channel: Channel): channel is OffsetScaleChannel {
   return channel in OFFSET_SCALE_CHANNEL_INDEX;
 }
 
+const TIME_SCALE_CHANNEL_INDEX = {
+  time: 1
+} as const;
+export const TIME_SCALE_CHANNELS = keys(TIME_SCALE_CHANNEL_INDEX);
+export type TimeScaleChannel = keyof typeof TIME_SCALE_CHANNEL_INDEX;
+
+export function isTime(channel: ExtendedChannel): channel is TimeScaleChannel {
+  return channel in TIME_SCALE_CHANNEL_INDEX;
+}
+
 // NON_POSITION_SCALE_CHANNEL = SCALE_CHANNELS without position / offset
 const {
   // x2 and y2 share the same scale as x and y
@@ -464,6 +480,7 @@ export function supportLegend(channel: NonPositionScaleChannel) {
     case FILLOPACITY:
     case STROKEOPACITY:
     case ANGLE:
+    case TIME:
       return false;
   }
 }
@@ -551,6 +568,7 @@ function getSupportedMark(channel: ExtendedChannel): SupportedMark {
     case YOFFSET:
     case LATITUDE:
     case LONGITUDE:
+    case TIME:
       // all marks except geoshape. geoshape does not use X, Y -- it uses a projection
       return ALL_MARKS_EXCEPT_GEOSHAPE;
     case X2:
@@ -625,6 +643,7 @@ export function rangeType(channel: ExtendedChannel): RangeType {
     case OPACITY:
     case FILLOPACITY:
     case STROKEOPACITY:
+    case TIME:
 
     // X2 and Y2 use X and Y scales, so they similarly have continuous range. [falls through]
     case X2:

src/channeldef.ts

@@ -40,6 +40,7 @@ import {
   TEXT,
   THETA,
   THETA2,
+  TIME,
   TOOLTIP,
   URL,
   X,
@@ -517,6 +518,12 @@ export interface PositionMixins {
 
 export type PolarDef<F extends Field> = PositionFieldDefBase<F> | PositionDatumDefBase<F> | PositionValueDef;
 
+export type TimeDef<F extends Field> = TimeFieldDef<F>;
+export interface TimeMixins {
+  rescale?: boolean;
+}
+export type TimeFieldDef<F extends Field> = ScaleFieldDef<F, StandardType> & TimeMixins;
+
 export function getBandPosition({
   fieldDef,
   fieldDef2,
@@ -1303,6 +1310,7 @@ export function channelCompatibility(
     case RADIUS2:
     case X2:
     case Y2:
+    case TIME:
       if (type === 'nominal' && !fieldDef['sort']) {
         return {
           compatible: false,
@@ -1338,13 +1346,13 @@ export function channelCompatibility(
  */
 export function isFieldOrDatumDefForTimeFormat(fieldOrDatumDef: FieldDef<string> | DatumDef): boolean {
   const {formatType} = getFormatMixins(fieldOrDatumDef);
-  return formatType === 'time' || (!formatType && isTimeFieldDef(fieldOrDatumDef));
+  return formatType === 'time' || (!formatType && isTemporalFieldDef(fieldOrDatumDef));
 }
 
 /**
  * Check if field def has type `temporal`. If you want to also cover field defs that use a time format, use `isTimeFormatFieldDef`.
  */
-export function isTimeFieldDef(def: FieldDef<any> | DatumDef): boolean {
+export function isTemporalFieldDef(def: FieldDef<any> | DatumDef): boolean {
   return def && (def['type'] === 'temporal' || (isFieldDef(def) && !!def.timeUnit));
 }
 

src/compile/compile.ts

@@ -202,11 +202,8 @@ function assembleTopLevelModel(
   // Config with Vega-Lite only config removed.
   const vgConfig = model.config ? stripAndRedirectConfig(model.config) : undefined;
 
-  const data = [].concat(
-    model.assembleSelectionData([]),
-    // only assemble data in the root
-    assembleRootData(model.component.data, datasets)
-  );
+  const rootData = assembleRootData(model.component.data, datasets);
+  const data = model.assembleSelectionData(rootData);
 
   const projections = model.assembleProjections();
   const title = model.assembleTitle();

src/compile/model.ts

@@ -598,25 +598,6 @@ export abstract class Model {
     return undefined;
   }
 
-  /**
-   * Corrects the data references in marks after assemble.
-   */
-  public correctDataNames = (mark: VgMarkGroup) => {
-    // TODO: make this correct
-
-    // for normal data references
-    if (mark.from?.data) {
-      mark.from.data = this.lookupDataSource(mark.from.data);
-    }
-
-    // for access to facet data
-    if (mark.from?.facet?.data) {
-      mark.from.facet.data = this.lookupDataSource(mark.from.facet.data);
-    }
-
-    return mark;
-  };
-
   /**
    * Traverse a model's hierarchy to get the scale component for a particular channel.
    */

src/compile/scale/range.ts

@@ -25,7 +25,8 @@
   X,
   XOFFSET,
   Y,
-  YOFFSET
+  YOFFSET,
+  TIME
 } from '../../channel';
 import {
   getBandPosition,
@@ -318,6 +319,13 @@
       ];
     }
 
+    case TIME: {
+      if (scaleType === 'band') {
+        return {step: 1000 / config.scale.framesPerSecond};
+      }
+      return [0, config.scale.animationDuration * 1000]; // e.g. linear
+    }
+
     case STROKEWIDTH:
       // TODO: support custom rangeMin, rangeMax
       return [config.scale.minStrokeWidth, config.scale.maxStrokeWidth];

src/compile/scale/type.ts

@@ -3,6 +3,7 @@
   getSizeChannel,
   isColorChannel,
   isScaleChannel,
+  isTime,
   isXorY,
   isXorYOffset,
   rangeType,
@@ -76,6 +77,10 @@
         return 'ordinal';
       }
 
+      if (isTime(channel)) {
+        return 'band';
+      }
+
       if (isXorY(channel) || isXorYOffset(channel)) {
         if (util.contains(['rect', 'bar', 'image', 'rule'], mark.type)) {
           // The rect/bar mark should fit into a band.
@@ -111,7 +116,11 @@
         return 'ordinal';
       } else if (isFieldDef(fieldDef) && fieldDef.timeUnit && normalizeTimeUnit(fieldDef.timeUnit).utc) {
         return 'utc';
+      } else if (isTime(channel)) {
+        // return 'linear';
+        return 'band'; // TODO(jzong): when interpolation is implemented, this should be 'linear'
       }
+
       return 'time';
 
     case 'quantitative':
@@ -125,6 +134,9 @@
         log.warn(log.message.discreteChannelCannotEncode(channel, 'quantitative'));
         // TODO: consider using quantize (equivalent to binning) once we have it
         return 'ordinal';
+      } else if (isTime(channel)) {
+        // return 'linear';
+        return 'band'; // TODO(jzong): when interpolation is implemented, this should be 'linear'
       }
 
       return 'linear';

src/compile/selection/assemble.ts

@@ -1,7 +1,7 @@
 import {Signal, SignalRef} from 'vega';
 import {parseSelector} from 'vega-event-selector';
 import {identity, isArray, stringValue} from 'vega-util';
-import {MODIFY, STORE, unitName, VL_SELECTION_RESOLVE, TUPLE, selectionCompilers} from '.';
+import {MODIFY, STORE, unitName, VL_SELECTION_RESOLVE, TUPLE, selectionCompilers, isTimerSelection} from '.';
 import {dateTimeToExpr, isDateTime, dateTimeToTimestamp} from '../../datetime';
 import {hasContinuousDomain} from '../../scale';
 import {SelectionInit, SelectionInitInterval, ParameterExtent, SELECTION_ID} from '../../selection';
@@ -14,6 +14,8 @@ import {ScaleComponent} from '../scale/component';
 import {UnitModel} from '../unit';
 import {parseSelectionExtent} from './parse';
 import {SelectionProjection} from './project';
+import {CURR} from './point';
+import {DataSourceType} from '../../data';
 
 export function assembleProjection(proj: SelectionProjection) {
   const {signals, hasLegend, index, ...rest} = proj;
@@ -120,7 +122,8 @@ export function assembleTopLevelSignals(model: UnitModel, signals: Signal[]) {
 }
 
 export function assembleUnitSelectionData(model: UnitModel, data: readonly VgData[]): VgData[] {
-  const dataCopy = [...data];
+  const selectionData = [];
+  const animationData = [];
   const unit = unitName(model, {escape: false});
 
   for (const selCmpt of vals(model.component.selection ?? {})) {
@@ -138,13 +141,37 @@ export function assembleUnitSelectionData(model: UnitModel, data: readonly VgDat
         : selCmpt.init.map(i => ({unit, fields, values: assembleInit(i, false)}));
     }
 
-    const contains = dataCopy.filter(d => d.name === selCmpt.name + STORE);
+    const contains = [...selectionData, ...data].filter(d => d.name === selCmpt.name + STORE);
     if (!contains.length) {
-      dataCopy.push(store);
+      selectionData.push(store);
+    }
+
+    if (isTimerSelection(selCmpt) && data.length) {
+      const sourceName = model.lookupDataSource(model.getDataName(DataSourceType.Main));
+      const sourceData = data.find(d => d.name === sourceName);
+
+      // find the filter transform for the current selection
+      const sourceDataFilter = sourceData.transform.find(
+        t => t.type === 'filter' && t.expr.includes('vlSelectionTest')
+      );
+
+      if (sourceDataFilter) {
+        // remove it from the original dataset
+        sourceData.transform = sourceData.transform.filter(t => t !== sourceDataFilter);
+
+        // create dataset to hold current animation frame
+        const currentFrame: VgData = {
+          name: sourceData.name + CURR,
+          source: sourceData.name,
+          transform: [sourceDataFilter] // add the selection filter to the animation dataset
+        };
+
+        animationData.push(currentFrame);
+      }
     }
   }
 
-  return dataCopy;
+  return selectionData.concat(data, animationData);
 }
 
 export function assembleUnitSelectionMarks(model: UnitModel, marks: any[]): any[] {

src/compile/selection/clear.ts

@@ -1,15 +1,15 @@
 import {Update} from 'vega';
 import {parseSelector} from 'vega-event-selector';
 import {isString} from 'vega-util';
-import {TUPLE} from '.';
+import {TUPLE, isTimerSelection} from '.';
 import {varName} from '../../util';
 import inputBindings from './inputs';
 import toggle, {TOGGLE} from './toggle';
 import {SelectionCompiler} from '.';
 
 const clear: SelectionCompiler = {
   defined: selCmpt => {
-    return selCmpt.clear !== undefined && selCmpt.clear !== false;
+    return selCmpt.clear !== undefined && selCmpt.clear !== false && !isTimerSelection(selCmpt);
   },
 
   parse: (model, selCmpt) => {

src/compile/selection/index.ts

@@ -118,3 +118,7 @@ export function disableDirectManipulation(selCmpt: SelectionComponent, selDef: S
   if (isString(selDef.select) || !selDef.select.clear) delete selCmpt.clear;
   if (isString(selDef.select) || !selDef.select.toggle) delete selCmpt.toggle;
 }
+
+export function isTimerSelection<T extends SelectionType>(selCmpt: SelectionComponent<T>) {
+  return selCmpt.events?.find(e => 'type' in e && e.type === 'timer');
+}