31:Tcf4,# Intro to Vega-Lite: Creating our First Vega-Lite Visualizations Vega-Lite Example Gallery

_This tutorial is part of the [Intro to Vega-Lite Collection](https://observablehq.com/collection/@jonfroehlich/intro-to-vega-lite)_. In this tutorial, you will learn how to create some basic [Vega-Lite](https://vega.github.io/vega-lite/) visualizations. Vega-Lite is a powerful high-level grammar for quickly building a wide range of interactive graphics. Vega-Lite is more powerful than making a chart in Microsoft Excel or Google Sheets, provides more interactivity options than [Tableau](https://www.tableau.com/), and often requires far fewer lines of code than [d3](https://observablehq.com/collection/@d3/learn-d3). There is also a growing community (e.g., see [StackOverflow](https://stackoverflow.com/tags/vega-lite)) and even a popular Vega-Lite variant for Python called [Vega-Altair](https://altair-viz.github.io/). ### Prerequisites We assume that you have completed the [Intro to Observable](https://observablehq.com/@jonfroehlich/observable-tutorial) tutorial. If you're not already familiar with JavaScript, we recommend Observable's [Learn Just Enough JavaScript](https://observablehq.com/@observablehq/learn-javascript-introduction) and Jeff Heer's [A Minimal Introduction to JavaScript](https://observablehq.com/@uwdata/a-minimal-introduction-to-javascript-and-observable). ### Vega-Lite Resources To complement this [introductory Vega-Lite series](https://observablehq.com/collection/@jonfroehlich/intro-to-vega-lite), we also recommend: * The official [Vega-Lite documentation](https://vega.github.io/vega-lite/), which provides details on the API and plentiful examples. Note, however, that the documentation and examples assume you are using the JSON-based approach to Vega-Lite rather than the JavaScript API (see below). * Observable's [four-part Vega-Lite tutorial](https://observablehq.com/collection/@observablehq/observable-for-vega-lite) * Jeff Heer's [Vega-Lite Visualization Curriculum](https://observablehq.com/collection/@uwdata/visualization-curriculum). This is a bit more advanced but has some incredible examples! ### JSON vs. JavaScript API You can use Vega-Lite via [JSON](https://vega.github.io/vega-lite/docs/) or the [JavaScript-based API](https://vega.github.io/vega-lite-api/api/). This tutorial uses the latter—the programmatic **JavaScript version of Vega-Lite**. However, as noted above, the [default documentation](https://vega.github.io/vega-lite/docs/) and most examples on the Vega-Lite website use the JSON specification. To understand the differences between the two, please see our [Vega-Lite: JSON vs. JavaScript](https://observablehq.com/@jonfroehlich/vega-lite-json-vs-javascript-api) API tutorial. ### Acknowledgements This particular notebook is based on [Vega-Lite's official tutorial](https://vega.github.io/vega-lite/tutorials/explore.html) written for the JSON spec and the [Vega-Lite OpenVisConf 2017 talk](https://www.youtube.com/watch?v=9uaHRWj04D4). _Thanks to [Abhishek Babu](https://abhishekbabu.github.io/), [Jeff Heer](https://homes.cs.washington.edu/~jheer/), and [Xia Su](https://xiasu.github.io/) for their help with this notebook._32:T74d,## Data Data in Vega-Lite is assumed to be formatted as a data table (or data frame) consisting of a set of named data *columns*. We will also regularly refer to data columns as data *fields*. Once loaded, the default table representation is an array of JavaScript objects. When using Vega-Lite, datasets may be pre-loaded as an array of objects, or provided via a URL to load a network-accessible dataset. The named columns of the data frame (the headers) are an essential piece of plotting with Vega-Lite as we use them to reference the fields and values. ### The Test Dataset For this tutorial, we will be using a Seattle weather dataset taken from the [National Oceanic and Atmospheric Administration (NOAAA)](https://www.ncdc.noaa.gov/cdo-web/). The dataset is commonly used in Vega-Lite tutorials and is stored on their website [here](https://vega.github.io/vega-lite/data/seattle-weather.csv). For the purposes of the tutorial, we are going to load it as an [Observable file attachment](https://observablehq.com/@observablehq/file-attachments). The dataset is a [CSV file](https://en.wikipedia.org/wiki/Comma-separated_values) with columns for: * min/max temperature (in Celsius) * precipitation (in millimeter) * wind (in meter/second) * weather type Each row represents a day, and we have data from January 1st, 2012 to December 31st, 2015. Feel free to open the dataset in Excel or Google Sheets. Here's what it looks like in Excel:

Below, we'll load the data and examine it within Observable. _Update (May 4, 2022): One of the Vega-Lite team members reached out to me to note that while the `seattle-weather.csv` does derive from NOAAA, the `weather` field is derived from this [`weather.py`](https://github.com/vega/vega-datasets/blob/next/scripts/weather.py) script._33:T703,### Loading the Data To begin, we'll load some test data using Observable's built-in [`File Attachment`](https://observablehq.com/@observablehq/file-attachments) functionality. We could also point Vega-Lite directly to a url. To use Observable's [File Attachment](https://observablehq.com/@observablehq/file-attachments) method, first open the **Data** pane by clicking the icon in the floating menu on the right. From there, click the plus (`+`) sign next to **File attachments** to upload a file. In this case, I uploaded the [`seattle-weather.csv`](https://github.com/vega/vega-datasets/blob/next/data/seattle-weather.csv) from the [vega-datasets repo](https://github.com/vega/vega-datasets/tree/next/data). Later, we'll learn how to point directly to online datasets via urls.34:T56e,### Vega-Lite Basics To create a Vega-Lite visualization, we need to specify both the **data** and a **graphical encoding**. Vega-Lite supports a variety of basic [mark types](https://vega.github.io/vega-lite/docs/mark.html), including [area](https://vega.github.io/vega-lite/docs/area.html), [bar](https://vega.github.io/vega-lite/docs/bar.html), [circle](https://vega.github.io/vega-lite/docs/circle.html), [line](https://vega.github.io/vega-lite/docs/line.html), [point](https://vega.github.io/vega-lite/docs/point.html), [rect](https://vega.github.io/vega-lite/docs/rect.html), [rule](https://vega.github.io/vega-lite/docs/rule.html), [square](https://vega.github.io/vega-lite/docs/square.html), [text](https://vega.github.io/vega-lite/docs/text.html), [tick](https://vega.github.io/vega-lite/docs/tick.html), and [geoshape](https://vega.github.io/vega-lite/docs/geoshape.html). In addition to these primitive marks, Vega-Lite supports composite marks that combine multiple primitives together like [boxplot](https://vega.github.io/vega-lite/docs/boxplot.html), [errorband](https://vega.github.io/vega-lite/docs/errorband.html), and [errorbar](https://vega.github.io/vega-lite/docs/errorbar.html). But let's start with a **simple point**. We can create a point mark using `vl.markPoint()`, and then pass the data to the `data()` method. Finally, we invoke `render()` to draw the plot:35:T42d,There are five supported data types: ["quantitative"](https://vega.github.io/vega-lite/docs/type.html#quantitative), ["temporal"](https://vega.github.io/vega-lite/docs/type.html#temporal), ["ordinal"](https://vega.github.io/vega-lite/docs/type.html#ordinal), ["nominal"](https://vega.github.io/vega-lite/docs/type.html#nominal), and ["geojson"](https://vega.github.io/vega-lite/docs/type.html#geojson). With the exception of "geojson", all have shorthand methods: - `fieldN()` indicates a [*nominal*](https://vega.github.io/vega-lite/docs/type.html#nominal) type (unordered, categorical data), - `fieldO()` indicates an [*ordinal*](https://vega.github.io/vega-lite/docs/type.html#ordinal) type (rank-ordered data), - `fieldQ()` indicates a [*quantitative*](https://vega.github.io/vega-lite/docs/type.html#quantitative) type (numerical magnitudes), - `fieldT()` indicates a [*temporal*](https://vega.github.io/vega-lite/docs/type.html#temporal) type (corresponding to [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) values),36:T920,## Vega-Lite Encodings In the above example, we encoded the **`temp_max`** field into the **`x`** position. It's easy to encode other variables in a Vega-Lite plot using position, color, size, and other channels. There are more than a dozen different types of [encodings](https://vega.github.io/vega-lite/docs/encoding.html) in Vega-Lite, including: - **[Position channels](https://vega.github.io/vega-lite/docs/encoding.html#position)**, - **`x`**: horizontal (x-axis) position of the mark. - **`y`**: vertical (y-axis) position of the mark. - **[Mark property channels](https://vega.github.io/vega-lite/docs/encoding.html#mark-prop)**: - **`size`**: Size of the mark. May correspond to area or length, depending on the mark type. - **`color`**: Mark color, specified as a [legal CSS color](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value). - **`shape`**: Plotting symbol shape for `point` marks. - **`opacity`**: Mark opacity, ranging from 0 (fully transparent) to 1 (fully opaque). - **[Text and tooltip channels](https://vega.github.io/vega-lite/docs/encoding.html#text)**: - **`text`**: Text for the [text mark](https://vega.github.io/vega-lite/docs/text.html) - **`tooltip`**: Tooltip text to display upon mouse hover over the mark. - **[Order](https://vega.github.io/vega-lite/docs/encoding.html#order)**: Mark ordering, determines line/area point order and drawing order. - **[Facet channels](https://vega.github.io/vega-lite/docs/encoding.html#facet)**: - **`column`**: Facet the data into horizontally-aligned subplots. - **`row`**: Facet the data into vertically-aligned subplots. Encodings can be combined with the different types of graphical marks like [**`markPoint()`**](https://vega.github.io/vega-lite/docs/point.html), [**`markLine()`**](https://vega.github.io/vega-lite/docs/line.html), [**`markCircle()`**](https://vega.github.io/vega-lite/docs/circle.html), [**`markBar()`**](https://vega.github.io/vega-lite/docs/bar.html), [**`markText()`**](https://vega.github.io/vega-lite/docs/text.html), _etc._ Please see Jeff Heer's fantastic Observable-based introduction to [Vega-Lite's encodings and graphical marks](https://observablehq.com/@uwdata/data-types-graphical-marks-and-visual-encoding-channels). Below, we'll start exploring other types of encodings and graphical marks.37:T73d,{ const histogram = vl.markBar({tooltip: true}) .data(seattleWeatherTyped) .encode( vl.x().fieldQ('temp_max').bin(true).title("Max Temperature (Celsius)"), vl.y().aggregate("count") ); const meanRule = vl.markRule({color: '#E45756CC', size: 2}) .data(seattleWeatherTyped) .encode( vl.x().fieldQ('temp_max').aggregate('mean'), vl.tooltip([{ field : "temp_max", aggregate: 'mean', title : "Mean", format: '0.1f' }] ) ); const meanLabel = vl.markText({ color: '#E45756CC', align: 'left', dx:3, y: 10 }) .data(seattleWeatherTyped) .encode( vl.x().mean('temp_max'), vl.text().mean('temp_max').format('0.1f'), ); const meanLabelTitle = vl.markText({ color: '#E45756CC', fontWeight: 'bold', align: 'left', dx:3, y: -5 }) .data(seattleWeatherTyped) .encode( vl.x().mean('temp_max'), vl.text().value('Mean Max Temp'), ); const medianRule = vl.markRule({color: '#F58518CC', size: 2}) .data(seattleWeatherTyped) .encode( vl.x().fieldQ('temp_max').aggregate('median'), vl.tooltip([{ field : "temp_max", aggregate: 'median', title : "Median" }] ) ); const medianLabel = vl.markText({ color: '#F58518CC', align: 'right', dx: -4, y: 10 }) .data(seattleWeatherTyped) .encode( vl.x().median('temp_max'), vl.text().median('temp_max').format('0.1f'), ); const medianLabelTitle = vl.markText({ color: '#F58518CC', fontWeight: 'bold', align: 'right', dx: -4, y: -5 }) .data(seattleWeatherTyped) .encode( vl.x().median('temp_max'), vl.text().value('Median Max Temp'), ); return vl.layer(histogram, meanRule, medianRule, meanLabel, meanLabelTitle, medianLabel, medianLabelTitle).render(); }38:T41b,## Vega-Lite and JSON Now that you have some experience with Vega-Lite, we'd like to again bring up how there are two ways to create Vega-Lite visualizations: 1. Via **JSON**, which is what the primary [Vega-Lite documentation](https://vega.github.io/vega-lite/docs/) is written in, and 2. Via **JavaScript** using the [JavaScript-based API](https://vega.github.io/vega-lite-api/), which is unfortunately less documented. We have created a tutorial specifically to explore this difference called [**Vega-Lite: JSON vs. JavaScript API**](https://observablehq.com/@jonfroehlich/vega-lite-json-vs-javascript-api). The notebook also explains how to use the online [Vega-Lite editor](https://vega.github.io/editor/#/url/vega-lite/N4KABGBEAkDODGALApgWwIaQFxUQFzwAdYsB6UgN2QHN0A6agSz0QFcAjOxge1IRQyUa6ALQAbZskoBWOgCtY3AHaQANOCgATdHkw5gkVgCcx2LTvSl46I7HmKVAX3URIGIwGszBvAE9CyGaQhNyMSnhqUABmjGJiyJpmeEasyM4akMhK8NyaYdTeGq4AHt6QMchiiTiQABLctsghAO7IRpGQfgFBAI6s6OHMOoxUkOkQrr5lFVVBALKxyLAA+gFGywDi6HHKHV2BNX0DeEMno44aF45AA) to author and debug visualizations.39:T42b,## Next Steps 🎉 Hooray, you've completed a basic introduction to Vega-Lite! For next steps, please see our [**Basic Time Series Plots in Vega-Lite**](https://observablehq.com/@jonfroehlich/basic-time-series-plots-in-vega-lite) as well as our [**Intro to Interaction with Vega Lite**](https://observablehq.com/@jonfroehlich/intro-to-interaction-in-vega-lite) notebooks. We also recommend Jeff Heer's [Vega-Lite Data Visualization Curriculum](https://observablehq.com/@uwdata/data-visualization-curriculum): * [Data Types, Graphical Marks, and Visual Encoding Channels](https://observablehq.com/@uwdata/data-types-graphical-marks-and-visual-encoding-channels) * [Data Transformation](https://observablehq.com/@uwdata/data-transformation) * [Scales, Axes, and Legends](https://observablehq.com/@uwdata/scales-axes-and-legends) * [Multi-View Composition](https://observablehq.com/@uwdata/multi-view-composition) * [Interaction](https://observablehq.com/@uwdata/interaction) * [Cartographic Visualization](https://observablehq.com/@uwdata/cartographic-visualization)3a:T488,## Resources * [Introduction to Vega-Lite](https://vega.github.io/vega-lite/tutorials/getting_started.html), Vega-Lite Docs * [A collection of Vega-Lite examples in Observable](https://observablehq.com/collection/@vega/vega-lite-api), Vega * [Observable for Vega-Lite](https://observablehq.com/collection/@observablehq/observable-for-vega-lite), Observable * [Vega-Lite in Observable: A Crash Course](https://youtu.be/ZV_Yjcs5WtM), Observable video on YouTube * [Vega-Lite Example Gallery](https://vega.github.io/vega-lite/examples/), Vega-Lite Docs * [Data Visualization in Data Science](https://vda-lab.github.io/visualisation-tutorial/index.html), Visual Data Analysis Lab * [Intro to Vega-Lite](https://observablehq.com/@mitvis/intro-vega-lite), MIT Visualization Group * [Vega-Lite Data Visualization Curriculum](https://observablehq.com/@uwdata/data-visualization-curriculum), Jeff Heer, Dominik Moritz, Jake VanderPlas, and Brock Craft. * [Vega-Lite: A Grammar of Interactive Graphics](https://youtu.be/9uaHRWj04D4), Wongsuphasawat, Moritz, Satyanarayan, OpenVis 2017 * [Vega-Lite API 5](https://observablehq.com/@vega/vega-lite-api-v5), Jeff Heer, 20213b:[{"id":"b69eee4465a97092b320a2935c7c22d92350256c04bff8e254ae27d600f1b4d395eaf264ca2f6f082a0fa4ae8dc0b6e5732bcc19f2f6d7d6532720cb6d1304ca","href":"https://static.observableusercontent.com/files/b69eee4465a97092b320a2935c7c22d92350256c04bff8e254ae27d600f1b4d395eaf264ca2f6f082a0fa4ae8dc0b6e5732bcc19f2f6d7d6532720cb6d1304ca","name":"image@1.png","type":"image/png","lastModified":1650998546402.886,"size":122723},{"id":"fb627ce33135e75ca4f8ecd302db893754ffae4981b5051adb0c100cfeeadff7bd64ec166479236ddf2ee7640cc0c485487e4ba9b4eaf5913e08dd7af4375532","href":"https://static.observableusercontent.com/files/fb627ce33135e75ca4f8ecd302db893754ffae4981b5051adb0c100cfeeadff7bd64ec166479236ddf2ee7640cc0c485487e4ba9b4eaf5913e08dd7af4375532","name":"seattle-weather@2.csv","type":"text/csv","lastModified":1650808840222.574,"size":121416}] 2f:{"title":"Intro to Vega-Lite: Creating our First Vega-Lite Visualizations","cells":[{"id":0,"value":"$31","pinned":false,"hidden":false,"mode":"md"},{"id":382,"value":"toc()","pinned":false,"hidden":false,"mode":"ojs"},{"id":111,"value":"## Import Required Libraries\nTo begin, we need to import the libraries needed for this notebook. Typically, imports go at the bottom of Observable notebooks but we'll put them up here for clarity. First and most importantly, we need to import [Vega-Lite](https://observablehq.com/@vega/vega-lite-api-v5): ","pinned":false,"hidden":false,"mode":"md"},{"id":14,"value":"import {vl} from '@vega/vega-lite-api-v5'","pinned":true,"hidden":false,"mode":"ojs"},{"id":116,"value":"Then we'll import a few utility methods from [`data-utilities`](https://observablehq.com/@jonfroehlich/data-utilities), which derives from the [UW Interactive Data Lab](https://idl.cs.washington.edu/). Each import line represents a named cell that we're importing with the syntax `import {named cell} from \"@notebookurl\"`","pinned":false,"hidden":false,"mode":"md"},{"id":34,"value":"import {printTable} from '@jonfroehlich/data-utilities'","pinned":true,"hidden":false,"mode":"ojs"},{"id":410,"value":"import {printTableTypes} from '@jonfroehlich/data-utilities'","pinned":true,"hidden":false,"mode":"ojs"},{"id":786,"value":"You can view the imported notebooks simply by clicking on them above (they are hyperlinked). ","pinned":false,"hidden":false,"mode":"md"},{"id":471,"value":"$32","pinned":false,"hidden":false,"mode":"md"},{"id":54,"value":"$33","pinned":false,"hidden":false,"mode":"md"},{"id":62,"value":"#### File attachments\nTo use a file, we pass the filename to the `FileAttachment` function from [Observable's standard library](https://observablehq.com/@observablehq/stdlib).","pinned":false,"hidden":false,"mode":"md"},{"id":27,"value":"seattleWeatherFile = FileAttachment(\"seattle-weather@2.csv\");","pinned":true,"hidden":false,"mode":"ojs"},{"id":79,"value":"#### Data parsing\nNow, let's parse the file. Observable has a number of built-in parsers for common data formats like [comma-separated value (CSV)](https://en.wikipedia.org/wiki/Comma-separated_values) and [JavaScript Object Notation (JSON)](https://en.wikipedia.org/wiki/JSON).\n\nBy default, the built-in parser for CSV files is [d3-dsv](https://github.com/d3/d3-dsv). We can call this simply by using the `.csv()` method on the file.","pinned":false,"hidden":false,"mode":"md"},{"id":81,"value":"seattleWeather = seattleWeatherFile.csv()","pinned":true,"hidden":false,"mode":"ojs"},{"id":32,"value":"To explore the data, let's print out the first 5 rows using the [`printTable()`](https://observablehq.com/@jonfroehlich/data-utilities#printTableHeader) utility function.\n\n${printTable(seattleWeather.slice(0, 5), null, null)}\n","pinned":false,"hidden":false,"mode":"md"},{"id":69,"value":"What do you notice about the data? Just as we did with Tableau, when you first load a dataset, it's important to analyze the data schema and data types.\n\nYou might notice that all of the data was loaded as **strings**—as indicated by the quotation marks `\" \"` around the data in the table—rather than more specific, field-relevant data types like **dates** and **numeric types**. In fact, we can check this with the `printTableTypes` function, which prints out each data field and its type.","pinned":false,"hidden":false,"mode":"md"},{"id":240,"value":"printTableTypes(seattleWeather);","pinned":true,"hidden":false,"mode":"ojs"},{"id":269,"value":"As we can see from above, all of the types are currently strings. Let's try this again but tell the CSV parser to automatically infer field types (which, by default, uses [d3.autoType](https://observablehq.com/@d3/d3-autotype)).","pinned":false,"hidden":false,"mode":"md"},{"id":96,"value":"seattleWeatherTyped = seattleWeatherFile.csv({typed: true})","pinned":true,"hidden":false,"mode":"ojs"},{"id":101,"value":"Let's again print out the first 5 rows to see what may have changed:\n${printTable(seattleWeatherTyped.slice(0, 5), null, null)}","pinned":false,"hidden":false,"mode":"md"},{"id":107,"value":"You might notice now that not everything is strings. Good! Let's also use `printTableTypes` again to verify:","pinned":false,"hidden":false,"mode":"md"},{"id":263,"value":"printTableTypes(seattleWeatherTyped);","pinned":true,"hidden":false,"mode":"ojs"},{"id":274,"value":"Is this what we were expecting? Yes, we now have a mixture of **strings**, **dates**, and **numbers**? This is what we want!","pinned":false,"hidden":false,"mode":"md"},{"id":306,"value":"## Our First Vega-lite Visualization\nNow that we've explored our data a bit, we're ready to create our first Vega-Lite visualization. Let's start simply and build a univariate visualization of only one data field: the maximum temperature data `temp_max`.\n${printTable(seattleWeatherTyped.slice(0, 8), [\"temp_max\"], 40)}","pinned":false,"hidden":false,"mode":"md"},{"id":1288,"value":"This example roughly follows the weather example from the OpenVis 2017 Vega-Lite talk.\n\n","pinned":false,"hidden":false,"mode":"md"},{"id":322,"value":"$34","pinned":false,"hidden":false,"mode":"md"},{"id":318,"value":"vl.markPoint() // specify the point mark\n.data(seattleWeatherTyped) // specify data\n.render(); // render the vis","pinned":true,"hidden":false,"mode":"ojs"},{"id":1103,"value":"Here the rendering consists of one point per row in the dataset, all plotted on top of each other, since we have not yet specified positions for these points.","pinned":false,"hidden":false,"mode":"md"},{"id":431,"value":"### Creating a univariate scatterplot\nTo visually separate the points, we can map various encoding channels (or just channels for short) to fields in the dataset.\n\nSo, let's build on the above code by creating a one-dimensional plot of `temp_max`. We'll graph `temp_max` along the x-axis by adding an encoding for `x` and specifying the `field` and its data type (_e.g.,_ 'Nominal' _vs._ 'Quantitative'). ","pinned":false,"hidden":false,"mode":"md"},{"id":295,"value":"vl.markPoint()\n .data(seattleWeatherTyped)\n .encode(vl.x().field('temp_max').type('quantitative')) // encode temp_max as x position\n .render();","pinned":true,"hidden":false,"mode":"ojs"},{"id":1110,"value":"### Marks and encodings\nThe [**`encode()`**](https://vega.github.io/vega-lite/docs/encoding.html) method builds a key-value mapping between encoding channels (such as `x`, `y`, `color`, `shape`, `size`, *etc.*) to fields in the dataset, accessed by field name. We provide a channel encoding using the `vl.` methods along with a *data type* to guide the visualization design. Here, we encode the `temp_max` field as a *quantitative* type, indicating numerical measurements.","pinned":false,"hidden":false,"mode":"md"},{"id":447,"value":"You might correctly infer that to use a y-axis encoding, we need to simply swap `vl.x()` to `vl.y()` and you would be right! 🙌","pinned":false,"hidden":false,"mode":"md"},{"id":454,"value":"vl.markPoint()\n .data(seattleWeatherTyped)\n .encode(vl.y().field('temp_max').type('quantitative')) // encode temp_max as y position\n .render();","pinned":true,"hidden":false,"mode":"ojs"},{"id":325,"value":"For brevity, we can use the shorthand `fieldQ()` to specify both the field name and data type simultaneously. ","pinned":false,"hidden":false,"mode":"md"},{"id":326,"value":"vl.markPoint()\n .data(seattleWeatherTyped)\n .encode(vl.x().fieldQ('temp_max')) // use fieldQ shorthand\n .render();","pinned":true,"hidden":false,"mode":"ojs"},{"id":686,"value":"$35","pinned":false,"hidden":false,"mode":"md"},{"id":492,"value":"### Aggregation operations\nWe can also apply [aggregation operations](https://vega.github.io/vega-lite/docs/aggregate.html#ops) on fields. For example, we can graph the `mean` temperature across all `temp_max` points. In this case, we also turned on tooltips, so mouse over the point to see the average value.","pinned":false,"hidden":false,"mode":"md"},{"id":501,"value":"vl.markPoint({tooltip:true})\n .data(seattleWeatherTyped)\n .encode(vl.x().fieldQ('temp_max').aggregate(\"mean\")) // calculate mean\n .height(40)\n .render()","pinned":true,"hidden":false,"mode":"ojs"},{"id":815,"value":"Though this aggregation isn't very interesting here, this will be a powerful feature as you will soon see. Vega-Lite supports a variety of aggregation functions, including `count`, `min` (minimum), `max` (maximum), `average`, `median`, and `stdev` (standard deviation). See [Jeff Heer's Data Transformations in Vega-Lite](https://observablehq.com/@uwdata/data-transformation) to learn more about data transformations, including aggregation, sorting, filtering, and creation of new derived fields using calculation formulas\n\nFor now, let's return to our previous chart and add titles.","pinned":false,"hidden":false,"mode":"md"},{"id":462,"value":"### Adding titles\nWe can also specify the graph and x-axis titles:","pinned":false,"hidden":false,"mode":"md"},{"id":516,"value":"vl.markPoint()\n .data(seattleWeatherTyped)\n .title(\"Daily Max Temperatures in Seattle 2012 - 2015\") // add graph title\n .encode(vl.x().fieldQ('temp_max').title(\"Temperature (Celsius)\")) // add x-axis title\n .render();","pinned":true,"hidden":false,"mode":"ojs"},{"id":1682,"value":"$36","pinned":false,"hidden":false,"mode":"md"},{"id":1993,"value":"## Our first Scatterplot\nLet's say we wanted to explore the relationship between minimum and maximum daily temperatures in Seattle. We could encode min daily temperatures in the **`x`** position and max daily temperatures in the **`y`** position to make a **scatter plot**. \n\nThis only takes one more line of code. Neat!","pinned":false,"hidden":false,"mode":"md"},{"id":1687,"value":"vl.markPoint()\n .data(seattleWeatherTyped)\n .title(\"Relationship Between Min/Max Temperatures in Seattle 2012 - 2015\")\n .encode(\n vl.x().fieldQ('temp_min').title(\"Min Temp (C)\"),\n vl.y().fieldQ('temp_max').title(\"Max Temp (C)\") // add in y encoding\n ).render();","pinned":true,"hidden":false,"mode":"ojs"},{"id":1981,"value":"### Changing the mark type\nWe could also easily change the mark type to a [square](https://vega.github.io/vega-lite/docs/square.html):","pinned":false,"hidden":false,"mode":"md"},{"id":1985,"value":"vl.markSquare({opacity: 0.5}) // change mark type to square, change default opacity\n .data(seattleWeatherTyped)\n .title(\"Relationship Between Min/Max Temperatures in Seattle 2012 - 2015\")\n .encode(\n vl.x().fieldQ('temp_min').title(\"Min Temp (C)\"),\n vl.y().fieldQ('temp_max').title(\"Max Temp (C)\")\n ).render();","pinned":true,"hidden":false,"mode":"ojs"},{"id":1695,"value":"As expected, there appears to be a correlation between a day's minimum temperature and its maximum.\n\n### Adding a third channel: color\nWe could also encode a **third channel**, in this case the nominal **weather** field, which has categories such as fog, rain, and snow. Recall that the weather category looks like this:\n${printTable(seattleWeatherTyped.slice(0, 8), [\"temp_min\", \"temp_max\", \"weather\"], 40)}\n\nLet's also change the mark from a to a [**`markCircle()`**](https://vega.github.io/vega-lite/docs/circle.html). ","pinned":false,"hidden":false,"mode":"md"},{"id":1701,"value":"vl.markCircle({opacity: 0.6}) // change mark to circle and set opacity\n .data(seattleWeatherTyped)\n .title(\"Relationship Between Min/Max Temperatures in Seattle 2012 - 2015\")\n .encode(\n vl.x().fieldQ('temp_min').title(\"Min Temp (C)\"),\n vl.y().fieldQ('temp_max').title(\"Max Temp (C)\"),\n vl.color().fieldN('weather')\n ).render();","pinned":true,"hidden":false,"mode":"ojs"},{"id":1723,"value":"It might be helpful to specifically **control** the **color** **palette** so that the hues more closely match the underlying semantics of the weather. For example, assigning yellow to sun, blue to rain, gray to fog. We can pass in a color palette like this:","pinned":false,"hidden":false,"mode":"md"},{"id":1727,"value":"vl.markCircle({opacity: 0.5})\n .data(seattleWeatherTyped)\n .title(\"Relationship Between Min/Max Temperatures in Seattle 2012 - 2015\")\n .encode(\n vl.x().fieldQ('temp_min').title(\"Min Temp (C)\"),\n vl.y().fieldQ('temp_max').title(\"Max Temp (C)\"),\n vl.color().fieldN('weather').scale({range: [\"#aec7e8\", \"#c7c7c7\", \"#1f77b4\",\"#9467bd\", \"#e7ba52\"] }) // add color\n ).render();","pinned":true,"hidden":false,"mode":"ojs"},{"id":1772,"value":"Because we are going to **re-use this color palette**, it makes sense to save it in a variable that we can use across cells. So, let's do that now.","pinned":false,"hidden":false,"mode":"md"},{"id":1774,"value":"weatherColorPalette = [\"#aec7e8\", \"#c7c7c7\", \"#1f77b4\",\"#9467bd\", \"#e7ba52\"]; ","pinned":true,"hidden":false,"mode":"ojs"},{"id":1711,"value":"### Add a fourth channel: size\nAs our final encoding, let's visualize a fourth dimension by encoding precipitation as mark size. The precipitation field looks like:\n${printTable(seattleWeatherTyped.slice(0, 8), [\"temp_min\", \"temp_max\", \"weather\", \"precipitation\"], 40)}","pinned":false,"hidden":false,"mode":"md"},{"id":1715,"value":"vl.markCircle({opacity: 0.6})\n .data(seattleWeatherTyped)\n .title(\"Relationship Between Min/Max Temperatures in Seattle 2012 - 2015\")\n .encode(\n vl.x().fieldQ('temp_min').title(\"Min Temp (C)\"),\n vl.y().fieldQ('temp_max').title(\"Max Temp (C)\"),\n vl.color().fieldN('weather').scale({range: weatherColorPalette }), \n vl.size().fieldQ('precipitation')\n ).render();","pinned":true,"hidden":false,"mode":"ojs"},{"id":1853,"value":"But the problem with the above is that we can no longer see sunny days—because often their precipitation values are zero! So, what should we do?","pinned":false,"hidden":false,"mode":"md"},{"id":1847,"value":"### Specifying an output range for size\nFirst, let's examine the data. The min and max precipitation across our dataset is **${Math.min(...seattleWeatherTyped.map(item => item.precipitation))}** and **${Math.max(...seattleWeatherTyped.map(item => item.precipitation))}**, respectively.\n\n","pinned":false,"hidden":false,"mode":"md"},{"id":1914,"value":"minMaxPrecipitation = [\n { \"Precipitation\": \"min\", \"Extents\": Math.min(...seattleWeatherTyped.map(item => item.precipitation)) },\n { \"Precipitation\": \"max\", \"Extents\": Math.max(...seattleWeatherTyped.map(item => item.precipitation)) },\n]","pinned":false,"hidden":false,"mode":"ojs"},{"id":1921,"value":"printTable(minMaxPrecipitation)","pinned":true,"hidden":false,"mode":"ojs"},{"id":1919,"value":"So, let's **remap** **${minMaxPrecipitation[0].Extents}-${minMaxPrecipitation[1].Extents}** to **different mark sizes**. To do this, we need to use [Vega-Lite's Scale](https://vega.github.io/vega-lite/docs/scale.html) functionality. Specifically, Scale refers to the [Domain](https://vega.github.io/vega-lite/docs/scale.html#domain) (the data input \"range\") and the [Range](https://vega.github.io/vega-lite/docs/scale.html#range) (the output \"range\"). For point and circle marks, the size channel mapping is proportional to the square root of the size value.\n\nAs we want to modify the visual output—that is, the mark area sizes—we want to modify the [Range](https://vega.github.io/vega-lite/docs/scale.html#range).","pinned":false,"hidden":false,"mode":"md"},{"id":1849,"value":"vl.markCircle({opacity: 0.6})\n .data(seattleWeatherTyped)\n .title(\"Relationship Between Min/Max Temperatures in Seattle 2012 - 2015\")\n .encode(\n vl.x().fieldQ('temp_min').title(\"Min Temp (C)\"),\n vl.y().fieldQ('temp_max').title(\"Max Temp (C)\"),\n vl.color().fieldN('weather').scale({range: weatherColorPalette }), \n vl.size().fieldQ('precipitation').scale({range:[5, 500]}) // modify output range so sunny days visible \n ).render();","pinned":true,"hidden":false,"mode":"ojs"},{"id":1759,"value":"### Adding tooltips\nIf we want to add [tooltips](https://vega.github.io/vega-lite/docs/tooltip.html), simply \"turn on\" tooltips for a given mark.","pinned":false,"hidden":false,"mode":"md"},{"id":1761,"value":"vl.markCircle({opacity: 0.6, tooltip: true})\n .data(seattleWeatherTyped)\n .title(\"Relationship Between Min/Max Temperatures in Seattle 2012 - 2015\")\n .encode(\n vl.x().fieldQ('temp_min').title(\"Min Temp (C)\"),\n vl.y().fieldQ('temp_max').title(\"Max Temp (C)\"),\n vl.color().fieldN('weather').scale({range: weatherColorPalette }), \n vl.size().fieldQ('precipitation').scale({range:[4, 500]})\n ).render();","pinned":true,"hidden":false,"mode":"ojs"},{"id":1765,"value":"You can also format the tooltip by specifying certain fields to show. In this case, we'll only show `temp_min` and `temp_max`","pinned":false,"hidden":false,"mode":"md"},{"id":1767,"value":"vl.markCircle({opacity: 0.6, tooltip: true})\n .data(seattleWeatherTyped)\n .title(\"Relationship Between Min/Max Temperatures in Seattle 2012 - 2015\")\n .encode(\n vl.x().fieldQ('temp_min').title(\"Min Temp (C)\"),\n vl.y().fieldQ('temp_max').title(\"Max Temp (C)\"),\n vl.color().fieldN('weather').scale({range: weatherColorPalette }), \n vl.size().fieldQ('precipitation').scale({range:[4, 500]}),\n vl.tooltip(['temp_min', 'temp_max']) // only show temp min and max\n ).render();","pinned":true,"hidden":false,"mode":"ojs"},{"id":1780,"value":"We can even show fields in the tooltip that we did not specifically encode in the visualization. In this case, let's also show the wind and date fields.\n\n${printTable(seattleWeatherTyped.slice(0, 5), null, null)}","pinned":false,"hidden":false,"mode":"md"},{"id":1782,"value":"vl.markCircle({opacity: 0.6, tooltip: true})\n .data(seattleWeatherTyped)\n .title(\"Relationship Between Min/Max Temperatures in Seattle 2012 - 2015\")\n .encode(\n vl.x().fieldQ('temp_min').title(\"Min Temp (C)\"),\n vl.y().fieldQ('temp_max').title(\"Max Temp (C)\"),\n vl.color().fieldN('weather').scale({range: weatherColorPalette }), \n vl.size().fieldQ('precipitation').scale({range:[4, 500]}),\n vl.tooltip(['date', 'temp_min', 'temp_max', 'precipitation', 'wind', 'weather']) \n ).render();","pinned":true,"hidden":false,"mode":"ojs"},{"id":1790,"value":"As you likely noticed, the tooltip date field **isn't formatted very nicely**. We can fix this too!","pinned":false,"hidden":false,"mode":"md"},{"id":1798,"value":"vl.markCircle({opacity: 0.6, tooltip: true})\n .data(seattleWeatherTyped)\n .title(\"Relationship Between Min/Max Temperatures in Seattle 2012 - 2015\")\n .encode(\n vl.x().fieldQ('temp_min').title(\"Min Temp (C)\"),\n vl.y().fieldQ('temp_max').title(\"Max Temp (C)\"),\n vl.color().fieldN('weather').scale({range: weatherColorPalette }), \n vl.size().fieldQ('precipitation').scale({range:[4, 500]}),\n vl.tooltip([\n {field : \"date\", type : \"temporal\"},\n {field : \"temp_max\", title : \"max temp\" },\n {field : \"temp_min\", title : \"min temp\" },\n {field : \"precipitation\"},\n {field : \"wind\"},\n {field : \"weather\"},\n ]) \n ).render();","pinned":true,"hidden":false,"mode":"ojs"},{"id":891,"value":"We did it. In only a few lines of code, we created a multi-dimensional scatterplot! 🎉","pinned":false,"hidden":false,"mode":"md"},{"id":895,"value":"## Creating histograms\nLet's now examine a new plot type: how to build a **histogram** in Vega-Lite. A histogram counts the frequency of a field value across bins or buckets. It helps us analyze the distribution and shape of our data. This example closely mirrors the one from Vega-Lite's [OpenVisConf 2017 talk](https://www.youtube.com/watch?v=9uaHRWj04D4)\n\nLet's build up a histogram step-by-step starting with our previous univariate plot. ","pinned":false,"hidden":false,"mode":"md"},{"id":1747,"value":"vl.markPoint()\n .data(seattleWeatherTyped)\n .title(\"Daily Max Temperatures in Seattle 2012 - 2015\")\n .encode(vl.x().fieldQ('temp_max').title(\"Temperature (Celsius)\"))\n .render();","pinned":true,"hidden":false,"mode":"ojs"},{"id":1750,"value":"This univariate scatterplot allows us to see the spread of data—from approximately -8° to 38° C. But we can do better!\n\n### Add binning to x field\nFirst, add the **`.bin(true)` property** to the x encoding. This tells Vega-Lite to bin the `temp_max` field. The bin sizes are automatically chosen—see [**Binning**](https://vega.github.io/vega-lite/docs/bin.html) in the Vega-Lite documentation. Let's also **change the default opacity** of the marks to 0.05 so we can begin to discern frequency patterns—the darker color corresponds to a higher count within the bin.","pinned":false,"hidden":false,"mode":"md"},{"id":1229,"value":"vl.markPoint({opacity: 0.05}) // change default opacity for the mark\n .data(seattleWeatherTyped)\n .title(\"Daily Max Temperatures in Seattle 2012 - 2015\")\n .encode(\n vl.x().fieldQ('temp_max').bin(true),\n )\n .render();","pinned":true,"hidden":false,"mode":"ojs"},{"id":1238,"value":"### Add y encoding: counts of each bin\nNext, let's add a y encoding to the counts of each bin. This will produce a 2-dimensional plot with the binned `temp_max` values in the x-axis and the count of each bin in the y-axis. Just like in Tableau, a count (or sum, mean, median, _etc._) is a type of aggregation, so too here will we use Vega-Lite's [**aggregation functionality**](https://vega.github.io/vega-lite/docs/aggregate.html).","pinned":false,"hidden":false,"mode":"md"},{"id":1243,"value":"vl.markPoint()\n .data(seattleWeatherTyped)\n .title(\"Seattle Daily Max Temperatures 2012 - 2015\")\n .encode(\n vl.x().fieldQ('temp_max').bin(true),\n vl.y().aggregate('count') // add aggregate count\n )\n .render();","pinned":true,"hidden":false,"mode":"ojs"},{"id":1233,"value":"Finally, histograms do not typically use _point_ marks but rather bars (or rectangles), so let's replace `markPoint()` with `markBar()`:","pinned":false,"hidden":false,"mode":"md"},{"id":910,"value":"vl.markBar({tooltip: true})\n .data(seattleWeatherTyped)\n .title(\"Histogram of Daily Max Temperatures in Seattle (2012-2015)\")\n .encode(\n vl.x().fieldQ('temp_max').bin(true),\n vl.y().aggregate(\"count\")\n )\n .render()","pinned":true,"hidden":false,"mode":"ojs"},{"id":916,"value":"### Changing number of bins\nWe can also play around with the number of bins—here, we'll set them to 5.","pinned":false,"hidden":false,"mode":"md"},{"id":918,"value":"vl.markBar()\n .data(seattleWeatherTyped)\n .title(\"Histogram of Daily Max Temperatures in Seattle (2012-2015)\")\n .encode(\n vl.x().fieldQ('temp_max').bin({maxbins: 5}), // try changing the maxbins to see what happens\n vl.y().aggregate(\"count\")\n )\n .render()","pinned":true,"hidden":false,"mode":"ojs"},{"id":922,"value":"Or set the bin set size—here, we'll set them to 2.","pinned":false,"hidden":false,"mode":"md"},{"id":924,"value":"vl.markBar()\n .data(seattleWeatherTyped)\n .title(\"Histogram of Daily Max Temperatures in Seattle (2012-2015)\")\n .encode(\n vl.x().fieldQ('temp_max').bin({'step' : 2}), // try changing the step value to see what happens\n vl.y().aggregate(\"count\")\n )\n .render()","pinned":true,"hidden":false,"mode":"ojs"},{"id":987,"value":"### Adding annotations\nWe could also add some annotations to the histogram, including a line marking the **mean** value (in **red**) and the **median** value (in **orange**). To do this, we have to use [Vega-Lite's layering system](https://vega.github.io/vega-lite/docs/layer.html), which we won't cover in this notebook (so, we'll hide the code for now—feel free to expand it if you're curious).","pinned":false,"hidden":false,"mode":"md"},{"id":986,"value":"$37","pinned":false,"hidden":false,"mode":"ojs"},{"id":1253,"value":"### How does temperature vary with weather?\nJust as with our scatter plots, we can add a third encoding channel, color, to explore how max temperature patterns differ with the nominal \"weather\" category. Recall that the weather category looks like this:\n${printTable(seattleWeatherTyped.slice(0, 8), [\"temp_max\", \"weather\"], 40)}","pinned":false,"hidden":false,"mode":"md"},{"id":1259,"value":"vl.markBar({tooltip: true})\n .data(seattleWeatherTyped)\n .title(\"Histogram of Daily Max Temperatures in Seattle (2012-2015)\")\n .encode(\n vl.x().fieldQ('temp_max').bin(true),\n vl.y().aggregate(\"count\"),\n vl.color().fieldN('weather') // add weather field as color encoding\n )\n .render()","pinned":true,"hidden":false,"mode":"ojs"},{"id":1292,"value":"### Customize the color to represent the underlying data\nJust as we did with the Scatter Plot above, it's helpful to color things more semantically—so that the colors better correspond to the weather (_e.g.,_ **gold** for sun, **gray** for fog).\n\nRemember that if we want to customize a graph's visual output, we manipulate the [**Range**](https://vega.github.io/vega-lite/docs/scale.html#range). So, set the color range to the **`weatherColorPalette`** variable that we made above.","pinned":false,"hidden":false,"mode":"md"},{"id":1399,"value":"vl.markBar({tooltip: true})\n .data(seattleWeatherTyped)\n .title(\"Histogram of Daily Max Temperatures in Seattle (2012-2015)\")\n .encode(\n vl.x().fieldQ('temp_max').bin(true),\n vl.y().aggregate(\"count\"),\n vl.color().fieldN('weather').scale({ range: weatherColorPalette }) // specify the output colors\n )\n .render()","pinned":true,"hidden":false,"mode":"ojs"},{"id":1402,"value":"We can also add in a domain to control ordering and color mappings. Here, we re-order the legend so that sun is first followed by fog, drizzle, etc. But then we also need to change the range order correspondingly.","pinned":false,"hidden":false,"mode":"md"},{"id":1298,"value":"vl.markBar({tooltip: true})\n .data(seattleWeatherTyped)\n .title(\"Histogram of Daily Max Temperatures in Seattle (2012-2015)\")\n .encode(\n vl.x().fieldQ('temp_max').bin(true),\n vl.y().aggregate(\"count\"),\n vl.color().fieldN('weather')\n .scale({ \n domain: ['sun', 'fog', 'drizzle', 'rain', 'snow'], // specifically set order of domain\n range: [\"#e7ba52\",\"#c7c7c7\",\"#aec7e8\", \"#1f77b4\",\"#9467bd\"], // and specify output range\n })\n )\n .render()","pinned":true,"hidden":false,"mode":"ojs"},{"id":1265,"value":"### Making small multiples\nStacked bar charts make it difficult to compare across values (as they don't share a common y-point).\n\nSo, let's split this stacked bar chart out as small multiples by adding a `column()` encoding. Here, we're able to easily observe that rainy and sunny days are most common, that snow occurs only when its cold (of course!), and that most rainy days are relatively cold as well (the rainy season in Seattle is during winter).","pinned":false,"hidden":false,"mode":"md"},{"id":1271,"value":"vl.markBar({tooltip: true})\n .data(seattleWeatherTyped)\n .title(\"Histogram of Daily Max Temperatures in Seattle (2012-2015)\")\n .encode(\n vl.x().fieldQ('temp_max').bin(true).title('Max Temp'),\n vl.y().aggregate(\"count\").title('Number of Days'),\n vl.color().fieldN('weather').scale({ range: weatherColorPalette}),\n vl.column().fieldN('weather')\n )\n .width(130)\n .height(150)\n .render()","pinned":true,"hidden":false,"mode":"ojs"},{"id":631,"value":"$38","pinned":false,"hidden":false,"mode":"md"},{"id":1177,"value":"### Using Vega-Lite outside of Observable\nFinally, Vega-Lite was built completely independently of Observable—indeed, it is intended for vanilla websites. You can embed Vega-Lite visualizations anywhere. For this, simply step through the [Vega-Lite tutorials](https://vega.github.io/vega-lite/tutorials/getting_started.html). The [\"Publish your Visualization Online\"](https://vega.github.io/vega-lite/tutorials/getting_started.html#embed) section covers how to embed Vega-Lite into webpages (and you'll use the JSON specification rather than the JavaScript API).","pinned":false,"hidden":false,"mode":"md"},{"id":1184,"value":"$39","pinned":false,"hidden":false,"mode":"md"},{"id":3,"value":"$3a","pinned":false,"hidden":false,"mode":"md"},{"id":385,"value":"## Imports","pinned":false,"hidden":false,"mode":"md"},{"id":387,"value":"import {toc} from \"@jonfroehlich/collapsible-toc\"","pinned":false,"hidden":false,"mode":"ojs"},{"id":1566,"value":"import {printVegaLiteJSON} from \"@jonfroehlich/vega-lite-utilities\"","pinned":false,"hidden":false,"mode":"ojs"}],"files":"$W3b","stdlib":"1","titling":"auto"}