docs: animated time encoding documentation and examples

[jonathanzong]

This PR contains documentation for animation features added in #8921.

• added doc comments to time encoding channel, animationDuration and framesPerSecond scale config (updates schema)
• add time channel to encoding.md documentation.
  • lists current restrictions with use of time channel
• add animation-related config to scale.md under new Animation subhead in Configuration section
• add two examples to the example gallery under new Animated header (after Interactive)
  • Gapminder frame animation
  • Hypothetical outcome plot
• removed the legend from the gapminder example so it looks cleaner

A problem before I ask for a review: the automatic vg2png thumbnail generation doesn't currently work with animated specs (it'll generate an image with without filtering, i.e. all the frames show at once). I imagine this is probably because the animated specs are getting run through an older version of the compiler before we added animation. I'd appreciate some guidance on what I need to do to fix this. We can't push the docs until then because presumably running the script will over-write the pngs with incorrect ones even if we put correct ones in manually.

closes #9534

[domoritz]

Please reference an issue so we know when this work is done and keep track of what needs to be done here.

[domoritz]

If this is not supported yet, we should not expose this in the spec. You can use @hidden if you still need it in the types.

[domoritz]

A problem before I ask for a review: the automatic vg2png thumbnail generation doesn't currently work with animated specs (it'll generate an image with without filtering, i.e. all the frames show at once). I imagine this is probably because the animated specs are getting run through an older version of the compiler before we added animation. I'd appreciate some guidance on what I need to do to fix this. We can't push the docs until then because presumably running the script will over-write the pngs with incorrect ones even if we put correct ones in manually.

Yeah, don't put manual ones in. I suspect something doesn't get cleared.

[domoritz]

I'm seeing warnings for Channel time should not be used with an unsorted discrete field. for the gap minder example. We should try to avid having examples throw warnings.

[jonathanzong]

opened a PR for the vg2png issue: vega/vega#4061

[domoritz]

Eventually, we could replace the custom image generation pipeline with vitest/playwright's snapshot generation. But that's a separate issue.

[mattijn]

I’m trying to create a bar chart race using the gapminder dataset using this new Time encoding channel. My result now looks like this (Open in Editor):

trim.3B8512D1-B70D-465E-A611-9D60798F8E06.MOV

Created with the following JSON:

{
  "$schema": "https://vega.github.io/schema/vega-lite/v6.1.0.json",
  "config": {
    "view": {
      "continuousHeight": 300,
      "continuousWidth": 300
    }
  },
  "data": {
    "url": "https://cdn.jsdelivr.net/npm/vega-datasets@v1.29.0/data/gapminder.json"
  },
  "encoding": {
    "time": {
      "field": "year",
      "type": "ordinal"
    },
    "x": {
      "field": "pop",
      "type": "quantitative"
    },
    "y": {
      "field": "country",
      "type": "nominal"
    }
  },
  "mark": {
    "type": "bar"
  },
  "params": [
    {
      "name": "date",
      "select": {
        "fields": [
          "year"
        ],
        "on": "timer",
        "type": "point"
      }
    }
  ],
  "transform": [
    {
      "filter": {
        "param": "date"
      }
    },
    {
      "filter": {
        "field": "country",
        "oneOf": [
          "Bangladesh",
          "Brazil",
          "China",
          "India",
          "Indonesia",
          "Japan",
          "Mexico",
          "Nigeria",
          "Pakistan",
          "United States"
        ]
      }
    }
  ]
}

How do I make sure the bars are starting at zero on x-axis for each time step?

And how to make sure the y-axis is sorted in descending order when using the time encoding channel?

Since the following produces an error (Open in Editor):

{
    "$schema": "https://vega.github.io/schema/vega-lite/v6.1.0.json",
    "config": {
        "view": {
            "continuousHeight": 300,
            "continuousWidth": 300
        }
    },
    "data": {
        "url": "https://cdn.jsdelivr.net/npm/vega-datasets@v1.29.0/data/gapminder.json"
    },
    "encoding": {
        "time": {
            "field": "year",
            "type": "ordinal"
        },
        "x": {
            "field": "pop",
            "type": "quantitative"
        },
        "y": {
            "field": "country",
            "sort": {
                "encoding": "x",
                "order": "descending"
            },
            "type": "nominal"
        }
    },
    "mark": {
        "type": "bar"
    },
    "params": [
        {
            "name": "date",
            "select": {
                "fields": [
                    "year"
                ],
                "on": "timer",
                "type": "point"
            }
        }
    ],
    "transform": [
        {
            "filter": {
                "field": "country",
                "oneOf": [
                    "Bangladesh",
                    "Brazil",
                    "China",
                    "India",
                    "Indonesia",
                    "Japan",
                    "Mexico",
                    "Nigeria",
                    "Pakistan",
                    "United States"
                ]
            }
        },
        {
            "filter": {
                "param": "date"
            }
        }
    ]
}

This results for me in this error:

Javascript Error: Undefined data set name: "data_0_curr"

It would be great to have a working bar chart race as example in the docs.

Btw I used the following python code on Altair VL6 branch, currently in PR:

import altair as alt
from vega_datasets import data

source = data.gapminder.url
slice_year = alt.selection_point(fields=['year'], on='timer')

filter_top_10_countries = alt.FieldOneOfPredicate(
    field='country', 
    oneOf=['Bangladesh','Brazil','China','India','Indonesia','Japan','Mexico','Nigeria','Pakistan','United States']
)

chart = alt.Chart(source).mark_bar().encode(
    x='pop:Q',
    y=alt.Y('country:N').sort(encoding='x', order='descending'),
    time='year:O'
).transform_filter(
    filter_top_10_countries
).transform_filter(
    slice_year
).add_params(slice_year)
chart#.to_json()

[mattijn]

Setting "stack": "False" on the x encoding channel makes the bars start from zero.

trim.A13708B2-F77D-4279-84DC-E2358099A9E1.MOV

So the remaining is how to have the bars reorder on each frame without erroring on the undefined data set name data_0_curr.

Edit: it feels a bit imperative for having to define stack here. Maybe usage of time encoding is like unstacking by it self? Not sure if this was observed before.

[mattijn]

I try to replicate this apache echarts example: https://echarts.apache.org/examples/en/editor.html?c=line-race
But somehow my chart in Vega-lite is not animating at all even when only added the line mark. Did I miss something obvious?

Open the Chart in the Vega Editor

[domoritz]

@jonathanzong @arvind could you help wrap this up?

[domoritz]

@jonathanzong @arvind do you have a timeline for wrapping this up?

[arvind]

@jonathanzong is currently moving to Boulder, so I think he may be offline for a bit. What's left to do on this PR? Is it bugs with the documentation, or bugs with the implementation of animation? Or perhaps it's just refining the examples?

[domoritz]

I think the main thing is vega/vega#4061 and addressing the comments in this pull request. There is a remaining warning, some unused schema, and the example generation should run (probably need to move this pull request internally).

[domoritz]

@arvind @jonathanzong could you make a plan for wrapping this up? It would be awesome to have this feature officially released and documented.

[joelostblom]

@arvind @jonathanzong Just checking in on this, it would indeed be fantastic to have this features officially released and documented!

[domoritz]

I looked a bit into this in November and tried to address vega/vega#4061 and hade a question for @jheer and @arvind that probably need an answer before we can get this pull request merged vega/vega#4061 (comment).