2a:null 2b:["$","title",null,{"children":"Marks and Channels with Vega-Lite JSON-style Tutorial | ODUCS Vis | Observable"}] 30:T6e5,# Marks and Channels with Vega-Lite JSON-style Tutorial Based on the [Data Types, Graphical Marks, and Visual Encoding Channels tutorial](https://observablehq.com/@uwdata/data-types-graphical-marks-and-visual-encoding-channels) from the [UW Interactive Data Lab](https://idl.cs.washington.edu). I'm focusing here on basic marks and channels in Vega-Lite. See the full tutorial for more information and additional customizations. Marks, channels, and data types are the building blocks of creating charts and visualizations. We will use this terminology in our coding examples. From Chapter 5 in [VAD](https://www.cs.ubc.ca/~tmm/vadbook/): * "*marks* are the basic geometric elements that depcit items or links" * "*channels* control their [marks] appearance" * "the effectiveness of a channel for encoding data depends on its *type*" References: * [Vega-Lite reference](https://vega.github.io/vega-lite/) * [Vega Embed](https://github.com/vega/vega-embed) * [Hello Vega-Embed](https://observablehq.com/@vega/hello-vega-embed) * [Working with Vega-Lite](https://observablehq.com/@didoesdigital/working-with-vega-lite) * [Vega-Lite API vs. JSON Examples](https://observablehq.com/@oducs-vis/vega-lite-api-vs-json?collection=@oducs-vis/cs625) To work along with this tutorial, sign in to Observable with your GitHub info and Fork a copy of this notebook. *If you haven't used JavaScript much, see [A Minimal Introduction to Javascript and Observable](https://observablehq.com/@uwdata/a-minimal-introduction-to-javascript-and-observable) and to help with some of the syntax. If you have used JavaScript a lot, see [Observable JavaScript](https://observablehq.com/@observablehq/observable-javascript) for an overview of what's different from vanilla JavaScript.*31:T509,For the first example, we'll use point marks with the x channel mapped to `fertility` and the y channel mapped to `life_expect`. In Vega-Lite, when you specify the data attribute name, you also specify its data type: * nominal (`type: nominal`) - same as categorical * ordinal (`type: ordinal`) - same as ordered * quantitative (`type: quantitative`) * temporal (`type: temporal`) - time values, corresponding to JavaScript [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) values * Example temporal values include date strings such as `“2019-01-04”` and `“Jan 04 2019”`, as well as standardized date-times such as the [ISO date-time format](https://en.wikipedia.org/wiki/ISO_8601): `“2019-01-04T17:50:35.643Z”`. There are no temporal values in our global development dataset above, as the `year` field is encoded as an integer. * The temporal type in Vega-Lite supports reasoning about time units (year, month, day, hour, etc.), and provides methods for requesting specific time intervals. For more details about temporal data in Vega-Lite, see the [TimeUnit documentation](https://vega.github.io/vega-lite/docs/timeunit.html). Since both `fertility` and `life_expect` are quantitative values, we use `type: "quantitative"`.32:[] 2e:{"id":"6a7a0993f8e7b97f","slug":"marks-and-channels-with-vega-lite-json","title":"Marks and Channels with Vega-Lite JSON-style Tutorial","thumbnail":"778a1d1b1d6762eeb8a73e6c6bb4a2b650d86a803ccfc493bcfba80fa0316d10","access_level":"public","create_time":"$D2024-05-09T20:43:53.686Z","update_time":"$D2024-07-26T20:55:48.262Z","view_time":null,"first_public_time":"$D2024-06-09T19:24:33.920Z","has_unpublished_edits":null,"fork":{"id":"82e744ec7707e5eb","slug":"marks-and-channels-with-vega-lite","title":"Marks and Channels with Vega-Lite Tutorial","owner":{"id":"449a34042f144222","login":"oducs-vis","name":"ODUCS Vis"}},"stars":0,"starred":false,"owner":{"type":"team","id":"449a34042f144222","login":"oducs-vis","name":"ODUCS Vis","avatar_url":"https://avatars-next.observableusercontent.com/9c1b8560739f2a71dc6dad0fa77abdadb4c341b2325e63f1b389383c05c912a7","tier":"education_2026"},"version":625,"publish_version":null,"role":null,"authored":false,"authors":[{"type":"individual","id":"d3a2250b1e6f818d","login":"thu-do","name":"Thu Do","avatar_url":"https://avatars-next.observableusercontent.com/9ef7da497f91a1afdf4c3b9887abf669d24b03a241b851559ad32d73632b9a8d","tier":null}],"members":[{"type":"individual","id":"d3a2250b1e6f818d","login":"thu-do","name":"Thu Do","avatar_url":"https://avatars-next.observableusercontent.com/9ef7da497f91a1afdf4c3b9887abf669d24b03a241b851559ad32d73632b9a8d","tier":null,"role":"editor"},{"type":"individual","id":"54e01b60b9979266","login":"weiglemc","name":"Michele Weigle","avatar_url":"https://avatars-next.observableusercontent.com/89f983e882cae9faa8e22c82afbe47f6f6352237d8ec47c06985ecfb1a108122","tier":null,"role":"editor"},{"type":"team","id":"449a34042f144222","login":"oducs-vis","name":"ODUCS Vis","avatar_url":"https://avatars-next.observableusercontent.com/9c1b8560739f2a71dc6dad0fa77abdadb4c341b2325e63f1b389383c05c912a7","tier":"education_2026","role":"viewer"}],"comments":[],"custom_thumbnail":true,"trashed":false,"lapsed":null,"subscribed":null,"forks":0,"collection":{"id":"954717e5683523fc","slug":"cs625-vega-lite-json","title":"CS625: Vega-Lite (JSON)","owner":{"id":"449a34042f144222","login":"oducs-vis","name":"ODUCS Vis"}},"type":"notebook","body":{"titling":"auto","title":"Marks and Channels with Vega-Lite JSON-style Tutorial","cells":[{"id":0,"value":"$30","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":8,"value":"## Data\n\nFirst, we'll import the dataset that we'll use for this tutorial. We will visualize global health and population measures for countries of the world, recorded over the years 1955 to 2005. The data was collected by the [Gapminder Foundation](https://www.gapminder.org/) and shared in [Hans Rosling's popular TED talk](https://www.youtube.com/watch?v=hVimVzgtD6w). (If you haven't seen the talk, I encourage you to watch it!)\n\nWe'll first load the dataset from the [vega-datasets](https://github.com/vega/vega-datasets) collection into a JavaScript array.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":9,"value":"data = (await require('vega-datasets'))['gapminder.json']()","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":15,"value":"We can preview the data by adding an Observable [Data Table cell](https://observablehq.com/@observablehq/data-table-cell).","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":13,"value":"data","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":19,"value":"For each `country` and `year` (in 5-year intervals), we have measures of fertility in terms of the number of children per woman (`fertility`), life expectancy in years (`life_expect`), and total population (`pop`).","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":21,"value":"Next, we'll create some smaller data arrays that we'll use later. The one below should contain the data only for the year 2000.\n\nNote that we're use `===` for equivalence with numeric values and `==` for strings. `===` is the [strict equality](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Strict_equality) operator, meaning that both the value *and* the datatype must match.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":442,"value":"data_2000 = data.filter((d) => d.year === 2000)","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":26,"value":"You could create a data table cell, but you can also preview the data by clicking on the ► icon next to `Array`.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":31,"value":"This next one has data for countries labeled cluster 1 in the year 2000.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":32,"value":"data_2000c1 = data_2000.filter((d) => d.cluster === 1)","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":37,"value":"We'll also create a dataset that has values only for the US.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":38,"value":"data_US = data.filter((d) => d.country == \"United States\")","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":41,"value":"Finally, we'll have a dataset with only a few countries.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":54,"value":"five_countries = new Set([\n \"United States\",\n \"France\",\n \"Austria\",\n \"Brazil\",\n \"Germany\"\n])","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":42,"value":"data_5countries = data.filter((d) => five_countries.has(d.country))","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":63,"value":"## Vega-Lite JSON-style\n\nFirst, we need to require the Vega Embed statement, which will be used to embed Vega-Lite visualizations into the web page.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":407,"value":"embed = require(\"vega-embed@6\")","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":71,"value":"In Vega-Lite, we first have to decide what type of *mark* will be used ([Vega-Lite mark properties](https://vega.github.io/vega-lite/docs/mark.html#types)).\n\nThen we use encodings (using the `encode` property) to bind data fields to available encoding *channels* for that mark type.\n\nIn this notebook we'll examine the following encoding channels:\n\n- `x`: Horizontal (x-axis) position of the mark.\n- `y`: Vertical (y-axis) position of the mark.\n- `size`: Size of the mark. May correspond to area or length, depending on the mark type.\n- `color`: Mark color, specified as a [legal CSS color](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value).\n- `shape`: Plotting symbol shape for `point` marks.\n \nFor a complete list of available channels, see the [Vega-Lite encoding documentation](https://vega.github.io/vega-lite/docs/encoding.html).","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":79,"value":"$31","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":413,"value":"embed(\n{\n $schema: \"https://vega.github.io/schema/vega-lite/v5.json\",\n height: 300,\n width: 400,\n data: {values: data_2000},\n mark: \"point\", \n encoding: {\n x: {field: \"fertility\", type: \"quantitative\", scale: {zero: true}, title: \"Fertility\"}, \n y: {field: \"life_expect\", type: \"quantitative\", scale: {zero: true}, title: \"Life Expectancy\"}\n }\n})","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":89,"value":"**Q1:** _What happens to the chart above if you change `type: \"quantitative\"` to `type: \"ordinal\"` for the x-axis or the \"fertility\" field? Why?_\n\nCreate a new cell and enter the code below.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":94,"value":"## Adding Channels\n\nWe can apply additional channels to the marks by specifying them inside the `encode` property.\n\nThe size encoding channel sets a mark's size or extent. The meaning of the channel can vary based on the mark type. For point marks, the size channel maps to the pixel area of the plotting symbol, such that the diameter of the point matches the square root of the size value.\n\nA key thing to note is that when you set color inside the `encode` property, it maps the channel to the data. If you set the color in the `mark` property, it sets the color directly (i.e., it's not tied to the data).","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":507,"value":"embed(\n{\n $schema: \"https://vega.github.io/schema/vega-lite/v5.json\",\n height: 300,\n width: 400,\n data: {values: data_2000},\n mark: {type: \"point\", tooltip: true}, \n encoding: {\n x: {field: \"fertility\", type: \"quantitative\", scale: {zero: true}, title: \"Fertility\"}, \n y: {field: \"life_expect\", type: \"quantitative\", scale: {zero: true}, title: \"Life Expectancy\"},\n color: {field: \"cluster\", type: \"nominal\", title: \"Cluster\"},\n size: {field: \"pop\", type: \"quantitative\", title: \"Pop\"}\n }\n})","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":102,"value":"You can see the difference between *mapping* color and *setting* color here.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":518,"value":"embed(\n{\n $schema: \"https://vega.github.io/schema/vega-lite/v5.json\",\n height: 300,\n width: 400,\n data: {values: data_2000},\n mark: {type: \"point\", color: \"blue\", tooltip: true}, \n encoding: {\n x: {field: \"fertility\", type: \"quantitative\", scale: {zero: true}, title: \"Fertility\"}, \n y: {field: \"life_expect\", type: \"quantitative\", scale: {zero: true}, title: \"Life Expectancy\"},\n size: {field: \"pop\", type: \"quantitative\", title: \"Pop\"}\n }\n})","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":109,"value":"**Q2:** _What happens if you set color in both the `mark` and `encoding` properties?_\n\nCreate a new cell and enter the code below.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":120,"value":"## Marks Other than Point\n\nWe can apply the shape channel to point marks using `shape`.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":524,"value":"embed(\n{\n $schema: \"https://vega.github.io/schema/vega-lite/v5.json\",\n height: 300,\n width: 400,\n data: {values: data_2000},\n mark: {type: \"point\", tooltip: true}, \n encoding: {\n x: {field: \"fertility\", type: \"quantitative\", scale: {zero: true}, title: \"Fertility\"}, \n y: {field: \"life_expect\", type: \"quantitative\", scale: {zero: true}, title: \"Life Expectancy\"},\n shape: {field: \"cluster\", type: \"nominal\", title: \"Cluster\"}\n }\n})","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":124,"value":"To use a line mark, we can set the `mark` property to `\"line\"`.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":529,"value":"embed(\n{\n $schema: \"https://vega.github.io/schema/vega-lite/v5.json\",\n height: 300,\n width: 250,\n data: {values: data_US},\n mark: \"line\",\n encoding: {\n x: {field: \"year\", type: \"ordinal\", title: \"Year\"}, \n y: {field: \"fertility\", type: \"quantitative\", scale: {zero: true}, title: \"Fertility\"}\n }\n})","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":144,"value":"**Q3:** _Experiment with different datatypes for `year` in the cell above. Can you explain the differences between using `ordinal`, `nominal`, `quantitative`, and `temporal` in the `type` property? Why doesn't `type: temporal` work?_","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":130,"value":"We can use color to split items by a categorical value. Below, we'll map the color channel to country name and when we use lines, we'll get a different color line for each country.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":547,"value":"embed(\n{\n $schema: \"https://vega.github.io/schema/vega-lite/v5.json\",\n height: 300,\n width: 250,\n data: {values: data_5countries},\n mark: \"line\",\n encoding: {\n x: {field: \"year\", type: \"ordinal\", title: \"Year\"}, \n y: {field: \"fertility\", type: \"quantitative\", scale: {zero: true}, title: \"Fertility\"},\n color: {field: \"country\", type: \"nominal\", title: \"Country\"}\n }\n})","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":135,"value":"Note that the colors used here different hues, so they are appropriate for categorical (or, nominal) data.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":154,"value":"In Vega-Lite (unlike Python Seaborn), when we move from a line mark with `mark: \"line\"` to an area mark with `mark: \"area\"` with multiple categories, the default is to create a *stacked* chart, which doesn't make sense for this particular dataset.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":553,"value":"embed(\n{\n $schema: \"https://vega.github.io/schema/vega-lite/v5.json\",\n height: 300,\n width: 250,\n data: {values: data_5countries},\n mark: \"area\",\n encoding: {\n x: {field: \"year\", type: \"ordinal\", title: \"Year\"}, \n y: {field: \"fertility\", type: \"quantitative\", scale: {zero: true}, title: \"Fertility\"},\n color: {field: \"country\", type: \"nominal\", title: \"Country\"}\n }\n})","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":161,"value":"Now, we'll create a bar chart using a line mark (but called `mark: \"bar\"`) with horizontal spatial region based on country name and position on the vertical axis based on population. ","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":561,"value":"embed(\n{\n $schema: \"https://vega.github.io/schema/vega-lite/v5.json\",\n height: 300,\n width: 400,\n data: {values: data_2000c1},\n mark: \"bar\",\n encoding: {\n x: {field: \"country\", type: \"nominal\", title: \"Country\"}, \n y: {field: \"pop\", type: \"quantitative\", scale: {zero: true}, title: \"Pop\"},\n }\n})","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":167,"value":"We can flip this so it's more readable and map the country name to the vertical spatial region, just by swapping the x and y parameters.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":565,"value":"embed(\n{\n $schema: \"https://vega.github.io/schema/vega-lite/v5.json\",\n height: 400,\n width: 400,\n data: {values: data_2000c1},\n mark: \"bar\",\n encoding: {\n y: {field: \"country\", type: \"nominal\", title: \"Country\"}, \n x: {field: \"pop\", type: \"quantitative\", scale: {zero: true}, title: \"Pop\"},\n }\n})","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":620,"value":"Instead of sorting by the categorical value, we'll usually want to sort by the quantitative value. We can do that here by adding the [`sort`](https://vega.github.io/vega-lite/docs/sort.html) function to the y-axis encoding. The parameter `\"-x\"` says to sort based on the attribute mapped to the x-axis in descending order.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":622,"value":"embed(\n{\n $schema: \"https://vega.github.io/schema/vega-lite/v5.json\",\n height: 400,\n width: 400,\n data: {values: data_2000c1},\n mark: \"bar\",\n encoding: {\n y: {field: \"country\", type: \"nominal\", title: \"Country\", sort: \"-x\"}, \n x: {field: \"pop\", type: \"quantitative\", scale: {zero: true}, title: \"Pop\"},\n }\n})","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"}],"files":"$W32","stdlib":"1"}} 2f:"$2e:body"