feat: frame animations with time encoding and timer param

[jonathanzong]

This change implements basic features of Animated Vega-Lite. With this change, users can create frame animations using a time encoding, a timer point selection, and a filter transform.

This change does not include more complex features e.g.: interpolation, custom predicates, rescale, interactive sliders, or data-driven pausing.

• Adds a time encoding channel
• Adds isTimerSelection function to check if a selection is an animation selections
• Builds _curr animation dataset for timer selections to store the current animation frame
• Adds animation signals to track the elapsed time (anim_clock), current animation value (anim_value), current position in the animation field's domain (t_index), etc.
• When time encoding is present, updates associated marks' from.data to use the animation dataset (current frame).

Relevant issue: #4060

Coauthor: @joshpoll

Example specs

Hop example:

{
  "$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"
    }
  }
}

Gapminder:

{
  "$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"
    }
  }
}

[jonathanzong]

@domoritz @arvind this is ready for review. we were thinking hold off on docs and examples until a later PR, but let us know if you'd rather us include it here

[domoritz]

Thanks. Can we see whether you can run the formatting action as well so we know the formatting doesn't break.

[jonathanzong]

i was able to run yarn format with no problems, we've been using the eslint config

[domoritz]

Great. I was hoping we could get the GitHub action for checking formatting to work somehow.

[joshpoll]

I think it's running in the Runtime, Linting, and Coverage test.

[arvind]

Are these selection-specific signals, or global signals (i.e., one set of signals that are used by all selections)? I think it's the former based on some of the references within. In which case, I think they'll all need to be prefixed by the selection name. Otherwise, if you have multiple timer selections within the same unit spec, you're going to get a duplicate signal error.

[jonathanzong]

i think deciding what's selection-specific vs global matters for two situations:

1. multiple timer selections in the same unit spec

i don't think this should be allowed, because what does it mean to animate a single set of marks two different ways? what's the best way to disallow this?

2. multiple timer selections across multiple unit specs in a multi-view

we ideally want the animation clock ANIM_CLOCK to be global, so we can share a common timer across multiple units. but the problem is that the animation clock needs to know the MAX_RANGE_EXTENT to know when to wrap back around to 0, but this is calculated from the scale for each unit. imo for now this is fine since we didn't consider multi-view in the scope of the paper, but we'll have to figure this out when we think about multi-view / scale resolution. the extent of the clock needs to be determined from the unioned scale or the max of the independent scale extents

[arvind]

How different will these signals be for when we generalize the implementation (eg to have timer-driven interval signals)? Is it worth extracting them to their own selection module and working them in that way for reusability? Happy to punt on that for now, but it'd be useful to spec things through and externalize them while they're more fresh in your head.

[jonathanzong]

i feel like i will have a lot of questions about what changes to make to selections to expose predicates so i think i will opt to punt this from this PR's scope but try to write some thoughts down in a doc

[arvind]

Sorry for the delay, y'all! A great start. I've left line-level comments throughout and will do a more holistic review next. In the meantime, some higher-level thoughts:

• Thanks for including example specs in your PR OP. Could you include them as json specs under examples as well please? That'll slurp them into our CI process (and, I think?, make them easier to expose in the documentation)
• It might behoove us to also include some runtime tests since they've saved our (namely, my) behind a number of times when the compile-time specs appeared to be correctly constructed? (I'm happy to walk through the runtime test infrastructure post-CHI since it's a little complicated).

[jonathanzong]

first round of comments has been addressed. pending todos:

• question here feat: frame animations with time encoding and timer param #8921 (comment)
• find some time to talk about how runtime testing works

[mattijn]

c72cb7d was an attempt to trigger the deployment preview of #9294..

[mattijn]

Hi @jonathanzong and @joshpoll!👋 Would you mind updating this PR so the latest changes from the main repository are also included in this branch?

Im not brave enough to do it myself🙈, but I'm sensing that this is the reason why the new deployment preview is not yet triggering.

[mattijn]

Just thinking about making a map with the trajectory of the upcoming eclipse🥳

[joelostblom]

Just thinking about making a map with the trajectory of the upcoming eclipse🥳

Such a cool idea! Please share if you create it, I would love to see an animated VL chart for this.

Btw, @jonathanzong are you waiting for a review on this branch or are you planning to add more commits (I saw you were still adding more since you last requested a review).

[joshpoll]

I rebased

[jonathanzong]

We are indeed just waiting for a review

[arvind]

Yes, apologies, it's been on my docket for a while but I've been underwater with various other deadlines. My plan is to wrap this up this month 🤞

[mattijn]

Thanks for rebasing @joshpoll! But that didn't trigger the deployment preview either.

@hydrosquall, do you know if these deployment previews only work upon opening a new PR and not on existing PRs?

[hydrosquall]

I thought it would work for existing PRs but evidently not! I can try to see if there are debug logs somewhere later this week

…

On Tue, Apr 9, 2024 at 3:59 PM Mattijn van Hoek ***@***.***> wrote: Thanks for rebasing @joshpoll <https://github.com/joshpoll>! But that didn't trigger the deployment review either. @hydrosquall <https://github.com/hydrosquall>, do you know if these deployment previews only work upon opening a new PR and not on existing PRs? — Reply to this email directly, view it on GitHub <#8921 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACE2MM32ACXSAHERVW2G6XLY4RCAJAVCNFSM6AAAAAAYOFRUNCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDANBVHE2TKMJTGY> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[hydrosquall]

Hm, it looks like I might have to add eligible branch prefixes one at a time, until I figure out how the "include" and "exclude" rules compose (which takes precedence). If you push another commit to this branch that modifies anything in the src/ directory, a preview should build.