feat(animation): recompute scales per frame with time.rescale

`rescale` was declared on the time encoding but never read, so a frame's
scales were always fixed across the whole animation. That is the right
default -- it keeps positions comparable between frames -- but it makes
some animations unreadable: in a racing bar chart the early frames'
values are a rounding error against the final ones, so the bars start out
invisible and never reorder.

Read it. When set, redirect the affected scale domains to the current
frame dataset during domain assembly.

Three things are deliberately excluded. Scales with a discrete output
range are left alone, since moving between their outputs is not a
continuous change. The time scale is left alone because it defines the
extent of the animation, and narrowing it to the current frame would
collapse the very domain being played through. And only the unit's own
raw and main sources are redirected, since other datasets have no
per-frame counterpart.

Both raw and main are redirected because a domain may read either: a band
domain sorted by another field reads the raw source, and in a racing bar
chart that domain is precisely the one whose reordering is the point.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: jonathanzong

build/vega-lite-schema.json

@@ -26942,6 +26942,7 @@
               "description": "__Required.__ A string defining the name of the field from which to pull a data value or an object defining iterated values from the [`repeat`](https://vega.github.io/vega-lite/docs/repeat.html) operator.\n\n__See also:__ [`field`](https://vega.github.io/vega-lite/docs/field.html) documentation.\n\n__Notes:__ 1)  Dots (`.`) and brackets (`[` and `]`) can be used to access nested objects (e.g., `\"field\": \"foo.bar\"` and `\"field\": \"foo['bar']\"`). If field names contain dots or brackets but are not nested, you can use `\\\\` to escape dots and brackets (e.g., `\"a\\\\.b\"` and `\"a\\\\[0\\\\]\"`). See more details about escaping in the [field documentation](https://vega.github.io/vega-lite/docs/field.html). 2) `field` is not required if `aggregate` is `count`."
             },
             "rescale": {
+              "description": "Whether the animated marks' scales should be recomputed from the current frame rather than held fixed across the whole animation. Rescaling keeps each frame's data filling the view -- as in a racing bar chart, where the bars stay legible as their magnitudes grow -- at the cost of making positions incomparable between frames.\n\nScales with a discrete output range (`ordinal`, `bin-ordinal`, `quantile`, `quantize`, and `threshold`) are never rescaled, since interpolating between their outputs is not meaningful.\n\n__Default value:__ `false`",
               "type": "boolean"
             },
             "scale": {
@@ -29507,6 +29508,7 @@
           "description": "__Required.__ A string defining the name of the field from which to pull a data value or an object defining iterated values from the [`repeat`](https://vega.github.io/vega-lite/docs/repeat.html) operator.\n\n__See also:__ [`field`](https://vega.github.io/vega-lite/docs/field.html) documentation.\n\n__Notes:__ 1)  Dots (`.`) and brackets (`[` and `]`) can be used to access nested objects (e.g., `\"field\": \"foo.bar\"` and `\"field\": \"foo['bar']\"`). If field names contain dots or brackets but are not nested, you can use `\\\\` to escape dots and brackets (e.g., `\"a\\\\.b\"` and `\"a\\\\[0\\\\]\"`). See more details about escaping in the [field documentation](https://vega.github.io/vega-lite/docs/field.html). 2) `field` is not required if `aggregate` is `count`."
         },
         "rescale": {
+          "description": "Whether the animated marks' scales should be recomputed from the current frame rather than held fixed across the whole animation. Rescaling keeps each frame's data filling the view -- as in a racing bar chart, where the bars stay legible as their magnitudes grow -- at the cost of making positions incomparable between frames.\n\nScales with a discrete output range (`ordinal`, `bin-ordinal`, `quantile`, `quantize`, and `threshold`) are never rescaled, since interpolating between their outputs is not meaningful.\n\n__Default value:__ `false`",
           "type": "boolean"
         },
         "scale": {

site/_includes/docs_toc.md

@@ -352,6 +352,7 @@
 - [Animation]({{site.baseurl}}/docs/animation.html)
     - [The Time Encoding Channel]({{site.baseurl}}/docs/animation.html#time-encoding)
     - [Keyframes vs. Continuous Time]({{site.baseurl}}/docs/animation.html#timing)
+    - [Rescaling]({{site.baseurl}}/docs/animation.html#rescale)
     - [Limitations]({{site.baseurl}}/docs/animation.html#limitations)
 - [Config]({{site.baseurl}}/docs/config.html)
     - [Top-level Configuration]({{site.baseurl}}/docs/config.html#top-level-config)

site/docs/animation.md

@@ -29,7 +29,7 @@ This is the design described in [Animated Vega-Lite](https://vis.csail.mit.edu/p
 
 The `time` channel names the field the animation runs over and how that field maps onto elapsed time.
 
-{% include table.html props="field,type,timeUnit,scale" source="TimeFieldDef" %}
+{% include table.html props="field,type,timeUnit,scale,rescale" source="TimeFieldDef" %}
 
 {:#timing}
 
@@ -45,6 +45,18 @@ Set `"scale": {"type": "linear"}` instead when the field is continuous and what
 
 Unlike a visual channel, the time channel accepts either scale type for any orderable field, temporal ones included: it maps onto elapsed playback time rather than a visual range.
 
+{:#rescale}
+
+## Rescaling
+
+By default the scales are fixed across the whole animation, which keeps positions comparable between frames. Set `"rescale": true` on the time encoding to recompute them from each frame instead. This is what makes a racing bar chart readable: without it, the early frames' values are a rounding error against the final ones and the bars start out invisible.
+
+```json
+"time": {"field": "date", "type": "ordinal", "rescale": true}
+```
+
+Scales with a discrete output range (`ordinal`, `bin-ordinal`, `quantile`, `quantize`, and `threshold`) are never rescaled, since moving between their outputs is not a continuous change. Neither is the time scale itself, which defines the extent of the animation.
+
 {:#limitations}
 
 ## Limitations

src/channeldef.ts

@@ -106,7 +106,11 @@ import {isSignalRef} from './vega.schema.js';
 export type PrimitiveValue = number | string | boolean | null;
 
 export type Value<ES extends ExprRef | SignalRef = ExprRef | SignalRef> =
-  PrimitiveValue | number[] | Gradient | Text | ES;
+  | PrimitiveValue
+  | number[]
+  | Gradient
+  | Text
+  | ES;
 
 /**
  * Definition object for a constant value (primitive value or gradient definition) of an encoding channel.
@@ -139,7 +143,9 @@ export type ValueDefWithCondition<F extends FieldDef<any> | DatumDef<any>, V ext
    * A field definition or one or more value definition(s) with a parameter predicate.
    */
   condition?:
-    Conditional<F> | Conditional<ValueDef<V | ExprRef | SignalRef>> | Conditional<ValueDef<V | ExprRef | SignalRef>>[];
+    | Conditional<F>
+    | Conditional<ValueDef<V | ExprRef | SignalRef>>
+    | Conditional<ValueDef<V | ExprRef | SignalRef>>[];
 };
 
 export type StringValueDefWithCondition<F extends Field, T extends Type = StandardType> = ValueDefWithCondition<
@@ -393,7 +399,9 @@ export interface ScaleMixins {
 }
 
 export type OffsetDef<F extends Field, T extends Type = StandardType> =
-  ScaleFieldDef<F, T> | ScaleDatumDef<F> | ValueDef<number>;
+  | ScaleFieldDef<F, T>
+  | ScaleDatumDef<F>
+  | ValueDef<number>;
 
 export interface DatumDef<
   F extends Field = string,
@@ -534,6 +542,19 @@ export type PolarDef<F extends Field> = PositionFieldDefBase<F> | PositionDatumD
 
 export type TimeDef<F extends Field> = TimeFieldDef<F>;
 export interface TimeMixins {
+  /**
+   * Whether the animated marks' scales should be recomputed from the current
+   * frame rather than held fixed across the whole animation. Rescaling keeps
+   * each frame's data filling the view -- as in a racing bar chart, where the
+   * bars stay legible as their magnitudes grow -- at the cost of making
+   * positions incomparable between frames.
+   *
+   * Scales with a discrete output range (`ordinal`, `bin-ordinal`, `quantile`,
+   * `quantize`, and `threshold`) are never rescaled, since interpolating
+   * between their outputs is not meaningful.
+   *
+   * __Default value:__ `false`
+   */
   rescale?: boolean;
 }
 export type TimeFieldDef<F extends Field> = ScaleFieldDef<F, StandardType> & TimeMixins;
@@ -637,7 +658,8 @@ export type MarkPropFieldDef<F extends Field, T extends Type = Type> = ScaleFiel
 export type MarkPropDatumDef<F extends Field> = LegendMixins & ScaleDatumDef<F>;
 
 export type MarkPropFieldOrDatumDef<F extends Field, T extends Type = Type> =
-  MarkPropFieldDef<F, T> | MarkPropDatumDef<F>;
+  | MarkPropFieldDef<F, T>
+  | MarkPropDatumDef<F>;
 
 export interface LegendMixins {
   /**

src/compile/scale/domain.ts

@@ -10,7 +10,7 @@ import {
   MULTIDOMAIN_SORT_OP_INDEX as UNIONDOMAIN_SORT_OP_INDEX,
 } from '../../aggregate.js';
 import {isBinning, isBinParams, isParameterExtent} from '../../bin.js';
-import {getSecondaryRangeChannel, isScaleChannel, isXorY, ScaleChannel} from '../../channel.js';
+import {getSecondaryRangeChannel, isScaleChannel, isXorY, ScaleChannel, TIME} from '../../channel.js';
 import {
   binRequiresRange,
   getBandPosition,
@@ -20,6 +20,7 @@ import {
   isFieldDef,
   ScaleDatumDef,
   ScaleFieldDef,
+  TimeFieldDef,
   TypedFieldDef,
   valueExpr,
   vgField,
@@ -30,7 +31,15 @@ import {DateTime} from '../../datetime.js';
 import {ExprRef} from '../../expr.js';
 import * as log from '../../log/index.js';
 import {isPathMark, isRectBasedMark} from '../../mark.js';
-import {Domain, hasDiscreteDomain, isDomainUnionWith, isParameterDomain, ScaleConfig, ScaleType} from '../../scale.js';
+import {
+  Domain,
+  hasDiscreteDomain,
+  hasDiscreteRange,
+  isDomainUnionWith,
+  isParameterDomain,
+  ScaleConfig,
+  ScaleType,
+} from '../../scale.js';
 import {ParameterExtent} from '../../selection.js';
 import {DEFAULT_SORT_OP, EncodingSortField, isSortArray, isSortByEncoding, isSortField} from '../../sort.js';
 import {normalizeTimeUnit, TimeUnit, TimeUnitTransformParams} from '../../timeunit.js';
@@ -58,6 +67,7 @@ import {isFacetModel, isUnitModel, Model} from '../model.js';
 import {SignalRefWrapper} from '../signal.js';
 import {Explicit, makeExplicit, makeImplicit, mergeValuesWithExplicit} from '../split.js';
 import {UnitModel} from '../unit.js';
+import {CURR} from '../selection/point.js';
 import {ScaleComponent, ScaleComponentIndex} from './component.js';
 
 export function parseScaleDomain(model: Model) {
@@ -695,15 +705,53 @@ export function getFieldFromDomain(domain: VgDomain): string {
   return undefined;
 }
 
+/**
+ * When a scale should be recomputed from the current animation frame, the
+ * datasets to redirect away from and the frame dataset to redirect to.
+ *
+ * A domain may read either the unit's raw source or its main one -- a band
+ * domain sorted by another field uses the raw source, for instance -- and both
+ * should follow the animation. Both redirect to the main source's frame
+ * dataset, which is the data the marks themselves draw.
+ *
+ * The time scale is never redirected: it defines the extent of the animation,
+ * so narrowing it to the current frame would collapse the very domain being
+ * played through.
+ */
+function animationRescale(model: Model, channel: ScaleChannel): {sources: Set<string>; frame: string} | undefined {
+  if (channel === TIME || !isUnitModel(model) || !model.isAnimated) {
+    return undefined;
+  }
+
+  if (!(model.encoding.time as TimeFieldDef<string>)?.rescale) {
+    return undefined;
+  }
+
+  if (hasDiscreteRange(model.component.scales[channel]?.get('type'))) {
+    return undefined;
+  }
+
+  const main = model.lookupDataSource(model.getDataName(DataSourceType.Main));
+  return {
+    sources: new Set([main, model.lookupDataSource(model.getDataName(DataSourceType.Raw))]),
+    frame: main + CURR,
+  };
+}
+
 export function assembleDomain(model: Model, channel: ScaleChannel) {
   const scaleComponent: ScaleComponent = model.component.scales[channel];
+  const rescale = animationRescale(model, channel);
 
   const domains = scaleComponent.get('domains').map((domain: VgNonUnionDomain) => {
     // Correct references to data as the original domain's data was determined
     // in parseScale, which happens before parseData. Thus the original data
     // reference can be incorrect.
     if (isDataRefDomain(domain)) {
       domain.data = model.lookupDataSource(domain.data);
+
+      if (rescale?.sources.has(domain.data)) {
+        domain.data = rescale.frame;
+      }
     }
 
     return domain;

src/scale.ts

@@ -180,6 +180,15 @@ export function isContinuousToDiscrete(type: ScaleType): type is 'quantile' | 'q
   return CONTINUOUS_TO_DISCRETE_SCALES.has(type);
 }
 
+/**
+ * Whether a scale's *output* is a set of discrete values rather than a
+ * continuous span. Note that `band` and `point` are not among these: their
+ * domains are discrete but they map onto continuous positions.
+ */
+export function hasDiscreteRange(type: ScaleType): boolean {
+  return type === 'ordinal' || type === 'bin-ordinal' || isContinuousToDiscrete(type);
+}
+
 export interface ScaleConfig<ES extends ExprRef | SignalRef> extends ScaleInvalidDataConfigMixins {
   /**
    * If true, rounds numeric output values to integers.

test/compile/animation.test.ts

@@ -20,6 +20,22 @@ const gapminder = (select: any, extraParams: any[] = []): TopLevelSpec => ({
   },
 });
 
+const racingBars = (rescale: boolean): TopLevelSpec => ({
+  data: {url: 'data/category-brands.csv'},
+  params: [{name: 'frame', select: {type: 'point', on: 'timer'}}],
+  transform: [{filter: {param: 'frame'}}],
+  mark: 'bar',
+  encoding: {
+    x: {field: 'value', type: 'quantitative'},
+    y: {field: 'name', type: 'nominal', sort: {field: 'value', order: 'descending'}},
+    color: {field: 'category', type: 'nominal'},
+    time: {field: 'date', type: 'ordinal', ...(rescale ? {rescale: true} : {})},
+  },
+});
+
+const scaleDomains = (spec: TopLevelSpec) =>
+  Object.fromEntries(compile(spec).spec.scales.map((s) => [s.name, (s.domain as any)?.data]));
+
 describe('animation', () => {
   describe('frame filter placement', () => {
     it('moves the frame filter off an upstream dataset', () => {
@@ -78,4 +94,45 @@ describe('animation', () => {
       );
     });
   });
+  describe('rescale', () => {
+    it('leaves scale domains on the full dataset by default', () => {
+      const domains = scaleDomains(racingBars(false));
+      expect(domains.x).not.toMatch(/_curr$/);
+      expect(domains.y).not.toMatch(/_curr$/);
+    });
+
+    it('reads continuous domains from the current frame', () => {
+      expect(scaleDomains(racingBars(true)).x).toMatch(/_curr$/);
+    });
+
+    it('reads a sorted band domain from the current frame', () => {
+      // a band domain sorted by another field reads the raw source rather than
+      // the main one; it has to follow the animation too, or the bars in a
+      // racing bar chart never reorder
+      expect(scaleDomains(racingBars(true)).y).toMatch(/_curr$/);
+    });
+
+    it('leaves scales with a discrete range alone', () => {
+      // interpolating between an ordinal scale's outputs is not meaningful
+      expect(scaleDomains(racingBars(true)).color).not.toMatch(/_curr$/);
+    });
+
+    it('leaves the time scale alone', () => {
+      // the time scale defines the extent of the animation; narrowing it to the
+      // current frame would collapse the domain being played through
+      expect(scaleDomains(racingBars(true)).time).not.toMatch(/_curr$/);
+    });
+
+    it('points the rescaled domains at a dataset that exists', () => {
+      const compiled = compile(racingBars(true)).spec;
+      const names = new Set(compiled.data.map((d) => d.name));
+
+      for (const scale of compiled.scales) {
+        const data = (scale.domain as any)?.data;
+        if (data) {
+          expect(names).toContain(data);
+        }
+      }
+    });
+  });
 });