Vega 3 Migration MVP

[kanitw]

Marks and Visual Encoding

• [x] The "properties" block of visual encodings has been renamed "encode".

• [x] The "template" encoding directive has been removed. Instead, use the "signal" directive with an expression to perform equivalent text processing. (The "signal" encoding directive now accepts anonymous signal expressions in addition to signal names. You can use these to directly write expressions for visual encodings. For example: {"signal": "datum.field * 2"}.) – @domoritz

• The "band" property now accepts an interpolation fraction between 0 and 1 for placing elements within a scale band, and can now be used in conjunction with a field-based scale mapping. For example, the following encoding places an item at the midpoint of the appropriate scale band: {"scale": "xscale", "field": "foo", "band": 0.5}.

• [ ] The rule mark type now supports arbitrary line segments, and reliably draws a line from point "x", "y" to point "x2", "y2". (later in #1665)

• [x] [@kanitw] Mark definitions no longer allow embedded data transforms (e.g., {"type": "rect", "from": {"data": "table, "transform": [...]}}). Instead, all derived data sources must now be defined within a "data" definition block. However, as of Vega 3, "data" blocks are no longer constrained to only the top-level of a spec: they can be defined within group marks as well! For example, this flexibility allows creation of derived data sets within a faceted group.

• [x] [@kanitw] The "facet" transform is no longer supported. Instead, a new "facet" directive can be applied within a mark "from" block to enable multiple forms of faceting support. For example, the barley.vg.json example facets a group mark like so:

  "from": {
  "facet": {
    "name": "sites",
    "data": "barley",
    "groupby": "site"
  }
  },

  Child marks can visualize the faceted data by name: "from": {"data": "sites"}. The "facet" block also accepts the same parameters as an "aggregate" transform to apply when generating data elements for group mark items. In addition, Vega 3 now supports pre-faceted data, in which a data tuple may contain a nested a set of records. This oft-requested feature allows data to be grouped offline and passed directly to Vega, like so:

  "from": {
  "facet": {
    "name":  "facets",
    "data":  "input", // [{children: [...]}, {children: [...]}]
    "field": "children"
  }
  },

  In this case, each datum in input will back a group mark item, and each corresponding group will contain the data tuples referenced by the "children" field.

• [ ] Vega 3 adds z-index support for changing the layering order of sibling elements. Z-index values are expected to be non-negative integers. All scenegraph items default to a zindex of zero. Higher values indicate elements that should be drawn on top of their sibling marks. Mark, axis and legend definitions accept a "zindex" property, and "zindex" can also be used as an individual visual encoding property (e.g., in a "hover" or "update" set). Z-index sorting is performed at the sibling-level only; for example, it can not be used to force a single item in one mark set to be drawn on top of items in another mark set. Let's do later in #1684

[kanitw]

Signals and Event Processing

Nothing should matter! (Copied noted commented out -- click edit to see)

[kanitw]

View Layout

(moved to #1778)

[kanitw]

Axes and Legends

• [x] Axes no longer have a type parameter. Instead, the orient parameter is now required. Instead of {"type": "x"} use {"orient": "bottom"}, and instead of {"type": "y"} use {"orient": "left"}.
• [x] The "ticks" parameter for suggesting the approximate number of axis ticks has been renamed "tickCount".
• [x] Custom visual properties for axes and legends now reside under an "encode" block and use "enter", "update", and "exit" sub-blocks. If unsure of which to use, a good default is to define an "update" block to ensure all properties are updated.
• [x] datum.data => data.value @domoritz
• Legends now include an optional "type" property. By default, all legends use the "symbol" type, to create a discrete legend. – @domoritz
  • For continuous color scales, the "gradient" type can be used to create a legend containing a continuous color ramp. See the legends.vg.json example for more.
  • [ ] add legend.type syntax to VL
• [x] axis.layer => zindex
• [x] Axis grid is no longer transparent. #1742
• [x] grid now expand to the whole width and height #1779

[kanitw]

Scales

• [x] Following D3 4.0's design, the "ordinal" scale type has now been broken up into three different scale types: "ordinal" (for strict lookup tables), "band" (for spatial ordinal scales) and "point" (spatial ordinal scales with no padding, similar to {"point": true} in Vega 2). – @kanitw
  • [x] check if padding properties in Vega 3 changes. (D3-scale now have innerPadding, outerPadding for bandScale, which does not exist in Vega 2)
  • [x] Update scale.md
  • [ ] revise if ROW and COLUMN scale should accept only POINT scale Later: #1219
• [x] Vega 3 includes D3 4.0's "sequential" scale type and corresponding color scales. Use the "scheme" property to set the range to a named color scale (e.g., "viridis", "plasma", or "magma"). To see the list of supported built-in schemes, or to add new custom schemes, see the vega-scale module. – @domoritz
  • [x] Add support for providing custom scheme @domoritz (Need to decide if scheme or range get higher precedence – I'm leaning toward scheme)
  • [x] Check if "Ordinal color scale has weird color for stacked chart" is still true #1452
• [x] Vega 3 adds a new "index" scale type which maps an ordinal domain to a quantitative range (e.g., as supported by "linear" or "sequential" scales). This is particularly useful for creating ordered color ramps for ordinal data. – @domoritz
• [x] The "category10", "category20" and similar color palettes are no longer available as built-in range names. Instead, they are available using the scale "scheme" property, which can be specified instead of a scale range for "ordinal" and "sequential" scales. However, Vega 3 does support a built-in "category" short-hand for ordinal scale ranges, which can be re-defined as part of the theme configuration. - @kanitw
• [x] Scale domains involving multiple data fields from the same table must now be listed under the "fields" property, not "field". For example, "domain": {"data": "table", "fields": ["fieldA", "fieldB"]}. – @kanitw
• [x] rangeMixins – @kanitw
  • [x] scheme
  • [ ] revise x, y
• [x] bandSize => rangeStep
• [x] Update rangeStep formula to be consistent with D3 – @kanitw

[kanitw]

[@domoritz] Data Transforms

• [x] #1641

• [ ] Vega 3 also introduces a number of new transforms, and modifications to previous transforms (including a dramatically improved "force" transform and improved hierarchical layout support). Web-based documentation is still forthcoming. However, most of these transforms are demonstrated in the example specifications included in this repo. In addition, the parameters accepted by each transform are documented via JSDoc comments in the source code. Please consult the appropriate Vega module repositories for further information.
• [x] Vega 2.x transform "output" maps for determining output field names have been removed. Instead, the relevant transforms accept an "as" parameter that (depending on the transform type) takes either a single string or an ordered array of strings, each representing a desired output field name. See the documentation (including JSDoc source code comments) for individual transforms for more information.
• [x] The "aggregate" transform no longer uses a "summarize" block for defining aggregation operations. In Vega 3, we instead use a flat set of (equal-length) arrays specifying the aggregation fields, operations and output field names:

  {
    "type": "aggregate",
    "groupby": ["category1", "category2"],
    "fields": ["measure1", "measure1", "measure2"],
    "ops": ["min", "max", "median"],
    "as": ["min1", "max1", "median2"]
  }

• [x] A number of transforms now have different default output field names. In most cases, this was done to make the values more easily serve as scenegraph item properties (for example, when using post-encoding transforms).
• For layout transforms suchs as "pie", "stack", and "bin", midpoint calculations (e.g., layout_mid) are no longer included as output. Instead, one can use a "signal" expression to calulate a midpoint. For example, to compute the midpoints after a stack transform: `"y": {"scale": "yscale", "signal": "0.5 * (datum.y0 + datum.y1)"}).
  • [x] bin
  • [x] bin extent
  • [x] stack – @kanitw

• For the "lookup" transform, the "on", "onKey" and "keys" parameters have been renamed "from", "key", and "fields".
• [x] The "filter" transform "test" parameter has been renamed "expr" for consistency with other transforms that take an expression parameter.
• [x] The "formula" transform "field" parameter has been renamed "as".

[kanitw]

View API

(moved to #1780)

[kanitw]

All items here are either done or forked as their own issues in https://github.com/vega/vega-lite/milestone/9, so I'm closing this ;)