[WIP] Revise window transform + Add Docs / Examples

CONTRIBUTING.md

@@ -22,7 +22,7 @@ You can find [tasks with the "Help wanted" label in the issue tracker](https://g
 
 ### Help Create New Examples
 
-To submit a new example, fork our [example Block](https://bl.ocks.org/domoritz/455e1c7872c4b38a58b90df0c3d7b1b9) and send us a [pull request to add a link](https://github.com/vega/vega-lite/edit/master/site/examples/gallery.md) to it to our [example gallery](https://vega.github.io/vega-lite/examples/).
+To submit a new example, fork our [example Block](https://bl.ocks.org/domoritz/455e1c7872c4b38a58b90df0c3d7b1b9) and send us a [pull request to add a link](https://github.com/vega/vega-lite/edit/master/site/examples/index.md) to it to our [example gallery](https://vega.github.io/vega-lite/examples/).
 
 ## Documentation and Website
 

_data/link.yml

@@ -50,13 +50,23 @@ TimeUnit:
   link: timeunit.html
 LookupData:
   link: "lookup.html#lookup-data"
+Window:
+  link: window.html
 
 # Transform - Time Unit
 Month:
   name: Number
 Day:
   name: Number
 
+# Transform - Window
+WindowFieldDef:
+  link: window.html#field-def
+WindowSortField:
+  link: window.html#sort-field-def
+WindowOnlyOp:
+  link: window.html#ops
+
 # Mark
 AnyMark:
   name: Mark

_includes/docs_toc.md

@@ -52,71 +52,64 @@
         - [Time Unit in Encoding Field Definition]({{site.baseurl}}/docs/timeunit.html#encoding)
         - [Time Unit Transform]({{site.baseurl}}/docs/timeunit.html#transform)
         - [UTC time]({{site.baseurl}}/docs/timeunit.html#utc)
+    - [Window]({{site.baseurl}}/docs/window.html)
+        - [Window Field Definition]({{site.baseurl}}/docs/window.html#window-field-definition)
+        - [Window Transform Definition]({{site.baseurl}}/docs/window.html#window-transform-definition)
+        - [
+ Window Only Operation Reference]({{site.baseurl}}/docs/window.html#-window-only-operation-reference)
+        - [Examples]({{site.baseurl}}/docs/window.html#examples)
 - [Mark]({{site.baseurl}}/docs/mark.html)
     - [Documentation Overview]({{site.baseurl}}/docs/mark.html#documentation-overview)
     - [Mark Definition Object]({{site.baseurl}}/docs/mark.html#mark-def)
     - [Mark Config]({{site.baseurl}}/docs/mark.html#config)
     - [Mark Style Config]({{site.baseurl}}/docs/mark.html#style-config)
     - [Area]({{site.baseurl}}/docs/area.html)
         - [Documentation Overview]({{site.baseurl}}/docs/area.html#documentation-overview)
-        - [Area Chart]({{site.baseurl}}/docs/area.html#area-chart)
-        - [Stacked Area Chart]({{site.baseurl}}/docs/area.html#stacked-area-chart)
-        - [Normalized Stacked Area Chart]({{site.baseurl}}/docs/area.html#normalized-stacked-area-chart)
-        - [Streamgraph]({{site.baseurl}}/docs/area.html#streamgraph)
-        - [Ranged Area]({{site.baseurl}}/docs/area.html#ranged)
+        - [Area Mark Properties]({{site.baseurl}}/docs/area.html#properties)
+        - [Examples]({{site.baseurl}}/docs/area.html#examples)
         - [Area Config]({{site.baseurl}}/docs/area.html#config)
     - [Bar]({{site.baseurl}}/docs/bar.html)
         - [Documentation Overview]({{site.baseurl}}/docs/bar.html#documentation-overview)
-        - [Single Bar Chart]({{site.baseurl}}/docs/bar.html#single-bar-chart)
-        - [Bar Chart]({{site.baseurl}}/docs/bar.html#bar-chart)
-        - [Histogram]({{site.baseurl}}/docs/bar.html#histogram)
-        - [Stacked Bar Chart]({{site.baseurl}}/docs/bar.html#stack)
-        - [Layered Bar Chart]({{site.baseurl}}/docs/bar.html#layered-bar-chart)
-        - [Normalized Stacked Bar Chart]({{site.baseurl}}/docs/bar.html#normalized-stacked-bar-chart)
-        - [Grouped Bar Chart]({{site.baseurl}}/docs/bar.html#grouped-bar-chart)
-        - [Ranged Bars]({{site.baseurl}}/docs/bar.html#ranged)
+        - [Bar Mark Properties]({{site.baseurl}}/docs/bar.html#properties)
+        - [Examples]({{site.baseurl}}/docs/bar.html#examples)
         - [Bar Config]({{site.baseurl}}/docs/bar.html#config)
     - [Circle]({{site.baseurl}}/docs/circle.html)
-        - [Scatterplot with Circle]({{site.baseurl}}/docs/circle.html#scatterplot-with-circle)
+        - [Circle Mark Properties]({{site.baseurl}}/docs/circle.html#properties)
+        - [Examples]({{site.baseurl}}/docs/circle.html#examples)
         - [Circle Config]({{site.baseurl}}/docs/circle.html#config)
     - [Line]({{site.baseurl}}/docs/line.html)
         - [Documentation Overview]({{site.baseurl}}/docs/line.html#documentation-overview)
-        - [Line Chart]({{site.baseurl}}/docs/line.html#line-chart)
-        - [Multi-series Line Chart with the Detail Channel]({{site.baseurl}}/docs/line.html#line-detail)
-        - [Connected Scatter Plot (Line Chart with Custom Path)]({{site.baseurl}}/docs/line.html#connected-scatter-plot)
-        - [Line interpolation]({{site.baseurl}}/docs/line.html#line-interpolation)
-        - [Geo Line]({{site.baseurl}}/docs/line.html#geo-line)
+        - [Line Mark Properties]({{site.baseurl}}/docs/line.html#properties)
+        - [Examples]({{site.baseurl}}/docs/line.html#examples)
         - [Line Config]({{site.baseurl}}/docs/line.html#config)
     - [Point]({{site.baseurl}}/docs/point.html)
         - [Documentation Overview]({{site.baseurl}}/docs/point.html#documentation-overview)
-        - [Dot Plot]({{site.baseurl}}/docs/point.html#dot-plot)
-        - [Scatter Plot]({{site.baseurl}}/docs/point.html#scatter-plot)
-        - [Bubble Plot]({{site.baseurl}}/docs/point.html#bubble-plot)
-        - [Scatter Plot with Color and/or Shape]({{site.baseurl}}/docs/point.html#color)
-        - [Geo Point]({{site.baseurl}}/docs/point.html#geo-point)
+        - [Point Mark Properties]({{site.baseurl}}/docs/point.html#properties)
+        - [Examples]({{site.baseurl}}/docs/point.html#examples)
         - [Point Config]({{site.baseurl}}/docs/point.html#config)
     - [Rect]({{site.baseurl}}/docs/rect.html)
         - [Documentation Overview]({{site.baseurl}}/docs/rect.html#documentation-overview)
+        - [Rect Mark Properties]({{site.baseurl}}/docs/rect.html#rect-mark-properties)
+        - [Examples]({{site.baseurl}}/docs/rect.html#examples)
         - [Rect Config]({{site.baseurl}}/docs/rect.html#config)
     - [Rule]({{site.baseurl}}/docs/rule.html)
         - [Documentation Overview]({{site.baseurl}}/docs/rule.html#documentation-overview)
-        - [Width/Height-Spanning Rules]({{site.baseurl}}/docs/rule.html#widthheight-spanning-rules)
-        - [Ranged Rules]({{site.baseurl}}/docs/rule.html#ranged)
+        - [Rule Mark Properties]({{site.baseurl}}/docs/rule.html#properties)
+        - [Examples]({{site.baseurl}}/docs/rule.html#examples)
         - [Rule Config]({{site.baseurl}}/docs/rule.html#config)
     - [Square]({{site.baseurl}}/docs/square.html)
-        - [Scatterplot with Square]({{site.baseurl}}/docs/square.html#scatterplot-with-square)
+        - [Square Mark Properties]({{site.baseurl}}/docs/square.html#properties)
+        - [Example: Scatterplot with Square]({{site.baseurl}}/docs/square.html#example-scatterplot-with-square)
         - [Square Config]({{site.baseurl}}/docs/square.html#config)
     - [Text]({{site.baseurl}}/docs/text.html)
         - [Documentation Overview]({{site.baseurl}}/docs/text.html#documentation-overview)
-        - [Text Table Heatmap]({{site.baseurl}}/docs/text.html#text-table-heatmap)
-        - [Labels]({{site.baseurl}}/docs/text.html#labels)
-        - [Scatterplot with Text]({{site.baseurl}}/docs/text.html#scatterplot-with-text)
-        - [Geo Text]({{site.baseurl}}/docs/text.html#geo-text)
+        - [Text Mark Properties]({{site.baseurl}}/docs/text.html#properties)
+        - [Examples]({{site.baseurl}}/docs/text.html#examples)
         - [Text Config]({{site.baseurl}}/docs/text.html#config)
     - [Tick]({{site.baseurl}}/docs/tick.html)
         - [Documentation Overview]({{site.baseurl}}/docs/tick.html#documentation-overview)
-        - [Dot Plot]({{site.baseurl}}/docs/tick.html#dot-plot)
-        - [Strip Plot]({{site.baseurl}}/docs/tick.html#strip-plot)
+        - [Tick Mark Properties]({{site.baseurl}}/docs/tick.html#properties)
+        - [Examples]({{site.baseurl}}/docs/tick.html#examples)
         - [Tick Config]({{site.baseurl}}/docs/tick.html#config)
     - [Geoshape]({{site.baseurl}}/docs/geoshape.html)
         - [Geoshape Config]({{site.baseurl}}/docs/geoshape.html#config)

_layouts/docs.html

@@ -30,6 +30,8 @@
     url: lookup
   - text: Time Unit
     url: timeunit
+  - text: Window
+    url: window
 - text: Mark
   url: mark
   sub-sidebar:

build/vega-lite-schema.json

@@ -7314,11 +7314,11 @@
       "additionalProperties": false,
       "properties": {
         "as": {
-          "description": "The output name for each field. If none is defined will use the format op_field. For example, count_field for count,\n  and sum_field for sum.",
+          "description": "The output name for each field.",
           "type": "string"
         },
         "field": {
-          "description": "The data fields for which to compute aggregate or window functions. Field can be omitted for operations that do not\noperate over a specific data field, including count, rank, and dense_rank.",
+          "description": "The data field for which to compute the aggregate or window function. This can be omitted for functions that do not operate over a field such as `count`, `rank`, `dense_rank`.",
           "type": "string"
         },
         "op": {
@@ -7330,15 +7330,16 @@
               "$ref": "#/definitions/WindowOnlyOp"
             }
           ],
-          "description": "The operations supported for the window aggregation. See the list of supported operations here:\n   https://vega.github.io/vega-lite/docs/transforms/window.html"
+          "description": "The window or aggregation operations to apply within a window, including `rank`, `lead`, `sum`, `average` or `count`. See the list of all supported operations [here](https://vega.github.io/vega-lite/docs/transforms/window.html)."
         },
         "param": {
-          "description": "Parameter values for the window functions. Parameter value can be null for operations that do not accept a\nparameter.",
+          "description": "Parameter values for the window functions. Parameter values can be omitted for operations that do not accept a parameter.\n\nSee the list of all supported operations and their parameters [here](https://vega.github.io/vega-lite/docs/transforms/window.html).",
           "type": "number"
         }
       },
       "required": [
-        "op"
+        "op",
+        "as"
       ],
       "type": "object"
     },
@@ -7363,9 +7364,11 @@
       "description": "A compartor for fields within the window transform",
       "properties": {
         "field": {
+          "description": "The name of the field to sort.",
           "type": "string"
         },
         "order": {
+          "description": "Whether to sort the field in ascending or descending order.",
           "enum": [
             "ascending",
             "descending"
@@ -7382,7 +7385,7 @@
       "additionalProperties": false,
       "properties": {
         "frame": {
-          "description": "The frame for the window, if none is set the default is `[null, 0]` everything before the\ncurrent item.",
+          "description": "A frame specification as a two-element array indicating how the sliding window should proceed. The array entries should either be a number indicating the offset from the current data object, or null to indicate unbounded rows preceding or following the current data object. The default value is `[null, 0]`, indicating that the sliding window includes the current object and all preceding objects. The value `[-5, 5]` indicates that the window should include five objects preceding and five objects following the current object. Finally, `[null, null]` indicates that the window frame should always include all data objects.\n\n__Default value:__:  `[null, 0]` (includes the current object and all preceding objects)",
           "items": {
             "type": [
               "null",
@@ -7392,18 +7395,18 @@
           "type": "array"
         },
         "groupby": {
-          "description": "The fields to group by.",
+          "description": "The data fields for partitioning the data objects into separate windows. If unspecified, all data points will be a single group.",
           "items": {
             "type": "string"
           },
           "type": "array"
         },
         "ignorePeers": {
-          "description": "Will indicate whether to ignore peer values (items with the same rank) in the window. The default value is `False`.",
+          "description": "Indicates if the sliding window frame should ignore peer values. (Peer values are those considered identical by the sort criteria). The default is false, causing the window frame to expand to include all peer values. If set to true, the window frame will be defined by offset values only. This setting only affects those operations that depend on the window frame, namely aggregation operations and the first_value, last_value, and nth_value window operations.\n\n__Default value:__ `false`",
           "type": "boolean"
         },
         "sort": {
-          "description": "The definitions of how to sort each of the fields in the window.",
+          "description": "A comparator definition for sorting data objects within a window. If two data objects are considered equal by the comparator, they are considered “peer” values of equal rank. If sort is not specified, the order is undefined: data objects are processed in the order they are observed and none are considered peers (the ignorePeers parameter is ignored and treated as if set to `true`).",
           "items": {
             "$ref": "#/definitions/WindowSortField"
           },

examples/compiled/area_horizon.vg.json

@@ -168,9 +168,8 @@
                         "field": "y"
                     },
                     "y2": {
-                        "field": {
-                            "group": "height"
-                        }
+                        "scale": "y",
+                        "value": 0
                     }
                 }
             }
@@ -209,9 +208,8 @@
                         "field": "ny"
                     },
                     "y2": {
-                        "field": {
-                            "group": "height"
-                        }
+                        "scale": "y",
+                        "value": 0
                     }
                 }
             }

examples/compiled/circle_natural_disasters.vg.json

@@ -134,7 +134,6 @@
             "scale": "x",
             "orient": "bottom",
             "title": "Year",
-            "labelOverlap": true,
             "encode": {
                 "labels": {
                     "update": {
@@ -147,6 +146,7 @@
                     }
                 }
             },
+            "labelOverlap": true,
             "zindex": 1
         },
         {

examples/compiled/layer_bar_annotations.vg.json

@@ -360,7 +360,6 @@
             "scale": "x",
             "orient": "bottom",
             "title": "Day",
-            "labelOverlap": true,
             "encode": {
                 "labels": {
                     "update": {
@@ -373,6 +372,7 @@
                     }
                 }
             },
+            "labelOverlap": true,
             "zindex": 1
         },
         {