docs: animated time encoding documentation and examples

build/vega-lite-schema.json

@@ -5095,7 +5095,8 @@
           "description": "The end angle of arc marks in radians. A value of 0 indicates up or “north”, increasing values proceed clockwise."
         },
         "time": {
-          "$ref": "#/definitions/TimeDef"
+          "$ref": "#/definitions/TimeDef",
+          "description": "Time position of animated marks."
         },
         "tooltip": {
           "anyOf": [
@@ -9223,7 +9224,8 @@
           "description": "The end angle of arc marks in radians. A value of 0 indicates up or “north”, increasing values proceed clockwise."
         },
         "time": {
-          "$ref": "#/definitions/TimeDef"
+          "$ref": "#/definitions/TimeDef",
+          "description": "Time position of animated marks."
         },
         "tooltip": {
           "anyOf": [
@@ -22019,7 +22021,7 @@
       "additionalProperties": false,
       "properties": {
         "animationDuration": {
-          "description": "Default animation duration (in seconds) for time encodings, except for [`band`](https://vega.github.io/vega-lite/docs/scale.html#band) scales.\n\n__Default value:__ `5`",
+          "description": "Default animation duration (in seconds) for [`time`](https://vega.github.io/vega-lite/docs/encoding.html#time) encodings (except for [`band`](https://vega.github.io/vega-lite/docs/scale.html#band) scales, which use `framesPerSecond` instead).\n\n__Default value:__ `5`",
           "type": "number"
         },
         "bandPaddingInner": {
@@ -22111,7 +22113,7 @@
           "minimum": 0
         },
         "framesPerSecond": {
-          "description": "Default framerate (frames per second) for time [`band`](https://vega.github.io/vega-lite/docs/scale.html#band) scales.\n\n__Default value:__ `2`",
+          "description": "Default framerate (frames per second) for [`time`](https://vega.github.io/vega-lite/docs/encoding.html#time) encoding animation [`band`](https://vega.github.io/vega-lite/docs/scale.html#band) scales.\n\n__Default value:__ `2`",
           "type": "number"
         },
         "invalid": {

examples/compiled/animated_gapminder.vg.json

@@ -191,20 +191,5 @@
       "tickCount": {"signal": "ceil(height/40)"},
       "zindex": 0
     }
-  ],
-  "legends": [
-    {
-      "stroke": "color",
-      "symbolType": "circle",
-      "title": "country",
-      "encode": {
-        "symbols": {
-          "update": {
-            "fill": {"value": "transparent"},
-            "opacity": {"value": 0.7}
-          }
-        }
-      }
-    }
   ]
 }

examples/specs/animated_gapminder.vl.json

@@ -25,7 +25,8 @@
   ],
   "encoding": {
     "color": {
-      "field": "country"
+      "field": "country",
+      "legend": null
     },
     "x": {
       "field": "fertility",

site/_data/examples.json

@@ -955,5 +955,19 @@
         "png": true
       }
     ]
+  },
+  "Animated": {
+    "": [
+      {
+        "name": "animated_gapminder",
+        "title": "Gapminder Frame Animation",
+        "description": "An animated scatterplot showing the relationship between fertility rates and life expectancy across different countries, based on Gapminder data. Each point represents a country, with points colored by country and the visualization updating over time to show how these metrics have changed across years."
+      },
+      {
+        "name": "animated_hop",
+        "title": "Hypothetical outcome plot",
+        "description": "An animated tick chart displaying precipitation measurements from Seattle weather data. Each horizontal tick mark represents a precipitation value for a specific date, with the visualization updating over time to show the temporal progression of rainfall patterns."
+      }
+    ]
   }
 }

site/docs/encoding.md

@@ -84,6 +84,7 @@ The keys in the `encoding` object are encoding channels. Vega-Lite supports the
 - [Position Offset Channels](#position-offset): `xOffset`, `yOffset`
 - [Polar Position Channels](#polar): `theta`, `theta2`, `radius`, `radius2`
 - [Geographic Position Channels](#geo): `longitude`, `latitude`, `longitude2`, `latitude2`
+- [Time Channel](#time): `time`
 - [Mark Property Channels](#mark-prop): `angle`, `color` (and `fill` / `stroke`), `opacity`, `fillOpacity`, `strokeOpacity`, `shape`, `size`, `strokeDash`, `strokeWidth`
 - [Text and Tooltip Channels](#text): `text`, `tooltip`
 - [Hyperlink Channel](#href): `href`
@@ -261,6 +262,36 @@ Polar field and datum definitions may include `scale`, `stack`, and `sort` prope
 
 See [an example that uses `longitude` and `latitude` channels in a map]({{ site.baseurl }}/examples/geo_circle.html) or [another example that draws line segments (`rule`s) between points in a map]({{ site.baseurl }}/examples/geo_rule.html).
 
+{:#time}
+
+## Time Channel
+
+The `time` channel maps data values to animation keyframes over time. When a time encoding is specified, together with a [selection parameter](selection.html) that has a `timer` [event stream](selection.html#on), marks are animated to show different data values as time progresses.
+
+See [an example scatterplot animation]({{ site.baseurl }}/examples/animated_gapminder.html) that uses the `time` channel and a `timer` selection parameter.
+
+{% include table.html props="time" source="Encoding" %}
+
+Note: `time` encoding animations currently have a few restrictions. See the [example gallery]({{ site.baseurl }}/examples/#animated) for examples of animated visualizations.
+
+- must also explicility specify a selection parameter
+  - parameter must have a `timer` event
+  - parameter must select the same field as the `time` field definition
+- must explicitly define a filter using that parameter
+- currently, the `time` channel only supports `band` scales (these are the default for discrete frame animation)
+- currently, only unit specifications are supported (no multi-view animations)
+
+<!--
+TODO(jzong): uncomment once we've added rescale, scale types
+
+{:#time-field-def}
+
+### Time Field Definition
+
+In addition to the general [field definition properties](#field-def), the `time` field definition may include the properties listed below.
+
+{% include table.html props="scale,rescale,sort" source="TimeFieldDef" %} -->
+
 {:#mark-prop}
 
 ## Mark Property Channels

site/docs/encoding/scale.md

@@ -458,6 +458,14 @@ To provide themes for all scales, the scale config (`config: {scale: {...}}`) ca
 
 {% include table.html props="invalid" source="ScaleConfig" %}
 
+#### Animation
+
+<!-- TODO(jzong): uncomment animationDuration when linear scales for animation are implemented -->
+<!-- https://github.com/vega/vega-lite/issues/9590 -->
+<!-- {% include table.html props="animationDuration,framesPerSecond" source="ScaleConfig" %} -->
+
+{% include table.html props="framesPerSecond" source="ScaleConfig" %}
+
 #### Other
 
 {% include table.html props="clamp,round,xReverse,useUnaggregatedDomain,zero" source="ScaleConfig" %}

src/channeldef.ts

@@ -525,6 +525,11 @@ export type PolarDef<F extends Field> = PositionFieldDefBase<F> | PositionDatumD
 
 export type TimeDef<F extends Field> = TimeFieldDef<F>;
 export interface TimeMixins {
+  /*
+  Optional. A boolean flag. When rescale is true, scale domains update according to the subset of data inside the current keyframe. When rescale is false, scale domains are generated from the entire dataset.
+
+  __Default value:__ `false`
+  */
   rescale?: boolean;
 }
 export type TimeFieldDef<F extends Field> = ScaleFieldDef<F, StandardType> & TimeMixins;

src/compile/scale/range.ts

@@ -322,7 +322,7 @@ function defaultRange(channel: ScaleChannel, model: UnitModel): VgRange {
       // if (scaleType === 'band') {
       return {step: 1000 / config.scale.framesPerSecond};
       // }
-      // return [0, config.scale.animationDuration * 1000]; // TODO(jzong): uncomment for linear scales when interpolation is implemented
+      // return [0, config.scale.animationDuration * 1000]; // TODO(jzong): uncomment for linear scales when interpolation is implemented https://github.com/vega/vega-lite/issues/9590
     }
 
     case STROKEWIDTH:

src/compile/scale/type.ts

@@ -118,7 +118,7 @@ function defaultType(
         return 'utc';
       } else if (isTime(channel)) {
         // return 'linear';
-        return 'band'; // TODO(jzong): when interpolation is implemented, this should be 'linear'
+        return 'band'; // TODO(jzong): when interpolation is implemented, this should be 'linear' https://github.com/vega/vega-lite/issues/9590
       }
 
       return 'time';
@@ -136,7 +136,7 @@ function defaultType(
         return 'ordinal';
       } else if (isTime(channel)) {
         // return 'linear';
-        return 'band'; // TODO(jzong): when interpolation is implemented, this should be 'linear'
+        return 'band'; // TODO(jzong): when interpolation is implemented, this should be 'linear' https://github.com/vega/vega-lite/issues/9590
       }
 
       return 'linear';

src/compile/selection/point.ts

@@ -27,7 +27,7 @@ const animationSignals = (selectionName: string, scaleName: string): Signal[] =>
     },
 
     // scale signals
-    // TODO(jzong): uncomment commented signals below when implementing interpolation
+    // TODO(jzong): uncomment commented signals below when implementing interpolation https://github.com/vega/vega-lite/issues/9590
     {name: `${selectionName}_domain`, init: `domain('${scaleName}')`},
     {name: MIN_EXTENT, init: `extent(${selectionName}_domain)[0]`},
     // {name: 'max_extent', init: `extent(${selectionName}_domain)[1]`},

src/encoding.ts

@@ -187,6 +187,9 @@ export interface Encoding<F extends Field> {
    */
   radius2?: Position2Def<F>;
 
+  /**
+   * Time position of animated marks.
+   */
   time?: TimeDef<F>;
 
   /**

src/scale.ts

@@ -436,20 +436,22 @@ export interface ScaleConfig<ES extends ExprRef | SignalRef> extends ScaleInvali
   zero?: boolean;
 
   /**
-   * Default framerate (frames per second) for time [`band`](https://vega.github.io/vega-lite/docs/scale.html#band) scales.
+   * Default framerate (frames per second) for [`time`](https://vega.github.io/vega-lite/docs/encoding.html#time) encoding animation [`band`](https://vega.github.io/vega-lite/docs/scale.html#band) scales.
    *
    * __Default value:__ `2`
    *
    */
   framesPerSecond?: number;
 
   /**
-   * Default animation duration (in seconds) for time encodings, except for [`band`](https://vega.github.io/vega-lite/docs/scale.html#band) scales.
+   *
+   * Default animation duration (in seconds) for [`time`](https://vega.github.io/vega-lite/docs/encoding.html#time) encodings (except for [`band`](https://vega.github.io/vega-lite/docs/scale.html#band) scales, which use `framesPerSecond` instead).
    *
    * __Default value:__ `5`
    *
    */
-  animationDuration?: number;
+  // TODO(jzong): uncomment when linear scales for animation are implemented https://github.com/vega/vega-lite/issues/9590
+  // animationDuration?: number;
 }
 
 export const defaultScaleConfig: ScaleConfig<SignalRef> = {
@@ -481,7 +483,7 @@ export const defaultScaleConfig: ScaleConfig<SignalRef> = {
   zero: true,
 
   framesPerSecond: 2,
-  animationDuration: 5,
+  // animationDuration: 5, //TODO(jzong): uncomment when linear scales for animation are implemented https://github.com/vega/vega-lite/issues/9590
 };
 
 export interface SchemeParams {