DOC: Add window transform example
This example shows that aggregation functions aren't only for aggregate
transforms. By using two aggregation functions within a window transform
we are able to compute z-scores within a calculate transform.
@@ -671,7 +671,10 @@ For example, consider the following cumulative frequency distribution:
sort=[{'field': 'IMDB_Rating'}],
frame=[None, 0],
cumulative_count='count(*)',
- ).mark_area().encode(x='IMDB_Rating:Q', y='cumulative_count:Q')
+ ).mark_area().encode(
+ x='IMDB_Rating:Q',
+ y='cumulative_count:Q',
+ )
First, we pass a sort field definition, which indicates how data objects should be sorted within the window.
Here, movies should be sorted by their IMDB rating.
@@ -699,6 +702,45 @@ last_value None Assigns a value from the last data object in the curren
nth_value Number Assigns a value from the nth data object in the current sliding window frame. If no such object exists, assigns ``null``. Requires a non-negative integer parameter that indicates the offset from the start of the window frame. This operation must have a corresponding entry in the `fields` parameter array.
============ ========= =========================================================================================================================================================================================================================================================================================================================
+While an aggregate transform computes a single value that summarises all data objects, a window transform adds a new property to each data object.
+This new property is computed from the neighbouring data objects: that is, from the data objects delimited by the window field definition.
+For example, consider the following time series of stock prices:
+
+.. altair-plot::
+
+ import altair as alt
+ from vega_datasets import data
+
+ alt.Chart(data.stocks.url).mark_line().encode(
+ x='date:T',
+ y='price:Q',
+ color='symbol:N',
+ )
+
+It's hard to see the overall pattern in the above example, because Google's stock price is much higher than the other stock prices.
+If we plot the `z-scores`_ of the stock prices, rather than the stock prices themselves, then the overall pattern becomes clearer:
+
+.. altair-plot::
+
+ import altair as alt
+ from vega_datasets import data
+
+ alt.Chart(data.stocks.url).transform_window(
+ mean_price='mean(price)',
+ stdev_price='stdev(price)',
+ frame=[None, None],
+ groupby=['symbol'],
+ ).transform_calculate(
+ z_score=(alt.datum.price - alt.datum.mean_price) / alt.datum.stdev_price,
+ ).mark_line().encode(
+ x='date:T',
+ y='z_score:Q',
+ color='symbol:N',
+ )
+
+By using two aggregation functions (``mean`` and ``stdev``) within the window transform, we are able to compute the z-scores within the calculate transform.
+
For more information about the arguments to the window transform, see :class:`WindowTransform` and `the Vega-Lite documentation <https://vega.github.io/vega-lite/docs/window.html>`_.
.. _Vega expression: https://vega.github.io/vega/docs/expressions/
+.. _z-scores: https://en.wikipedia.org/w/index.php?title=Z-score
