31:T52c,md` By *declarative*, we mean that you can provide a high-level specification of *what* you want the visualization to include, in terms of *data*, *graphical marks*, and *encoding channels*, rather than having to specify *how* to implement the visualization in terms of for-loops, low-level drawing commands, *etc*. The key idea is that you declare links between data fields and visual encoding channels, such as the x-axis, y-axis, color, *etc*. The rest of the plot details are handled automatically. Building on this declarative plotting idea, a surprising range of simple to sophisticated visualizations can be created using a concise grammar. To learn more about the motivation and basic concepts behind Vega-Lite, watch the [Vega-Lite presentation video from OpenVisConf 2017](https://www.youtube.com/watch?v=9uaHRWj04D4). This notebook walks through the basic process of creating visualizations with Vega-Lite. Vega-Lite uses [JavaScript Object Notation (JSON)](https://en.wikipedia.org/wiki/JSON) as a stand-alone file format for describing charts. _Are you new to JavaScript and/or Observable? This notebook assumes basic familiarity with both. For a crash course, see [A Minimal Introduction to JavaScript and Observable](https://observablehq.com/@uwdata/a-minimal-introduction-to-javascript-and-observable)!_ `32:T40a,md` _Seattle exhibits both the least-rainiest and most-rainiest months!_ Above we use the \`quantitative\` type to instruct Vega-Lite to treat \`precip\` as a quantitative field (that is, a real-valued number). We see that grid lines and axis titles are automatically added as well. So far, we've seen \`nominal\` and \`quantitative\` types. The complete set of type-specific field methods is: - \`nominal\` indicates a *nominal* type (unordered, categorical data), - \`ordinal\` indicates an *ordinal* type (rank-ordered data), - \`quantitative\` indicates a *quantitative* type (numerical magnitudes), - \`temporal\` indicates a *temporal* type (corresponding to [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) values), What do you think will happen to our chart if we treat \`precip\` as a nominal or ordinal variable, rather than a quantitative variable? _Modify the code above and find out!_ We will take a closer look at data types and encoding channels in the next notebook. `33:T57c,{ // create an interval selection over an x-axis encoding const brush = { name: 'brush', select: 'interval', encodings: ['x'] }; // determine opacity based on brush const opacity = { condition: { param: 'brush', value: 0.9 }, // if in brush... value: 0.1 // else }; // an overview histogram of cars per year // add the interval brush to select cars over time const overview = { mark: 'bar', encoding: { x: { field: 'Year', type: 'ordinal', timeUnit: 'year', // extract year unit, treat as ordinal axis: { title: null, labelAngle: 0 } // no title, no label angle }, y: { aggregate: 'count', title: null }, // counts, no axis title opacity // modulate bar opacity based on the brush selection }, params: [ brush ], // add interval brush selection to the chart width: 400, // use the full default chart width height: 50 // set chart height to 50 pixels }; // a detail scatterplot of horsepower vs. mileage const detail = { mark: 'point', encoding: { x: { field: 'Horsepower', type: 'quantitative' }, y: { field: 'Miles_per_Gallon', type: 'quantitative' }, opacity // modulate point opacity based on the brush selection } }; // vertically concatenate (vconcat) charts return render({ data: { values: cars }, vconcat: [ overview, detail ] }); }34:T57b,md`

## Coda: Exporting and Publishing a Visualization Once you have visualized your data, perhaps you would like to publish it somewhere else on the web. To save an exported image, you can simply right-click a visualization and select "Save Image As..." from the context menu, assuming the default [canvas](https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API) rendering option is used. _Scroll up and try saving one of the images generated above!_ To include a Vega-Lite visualization on your own web page, you can use the [vega-embed JavaScript package](https://github.com/vega/vega-embed). Here is a basic HTML template, where your Vega-Lite JSON specification should be stored in the \`spec\` JavaScript variable: \`\`\`html

\`\`\` For more information on embedding Vega-Lite, see the [vega-embed documentation](https://github.com/vega/vega-embed). `35:[] 2f:{"title":"Introduction to Vega-Lite (JSON version)","cells":[{"id":0,"value":"md`# Introduction to Vega-Lite (JSON version)\n\n[**Vega-Lite**](https://vega.github.io/vega-lite) is a declarative language for interactive data visualization. Vega-Lite offers a powerful and concise visualization grammar for quickly building a wide range of statistical graphics.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":19,"value":" $\"Vega-Lite$ ","pinned":false,"hidden":false,"mode":"md"},{"id":21,"value":"$31","pinned":false,"hidden":false,"mode":"ojs"},{"id":8,"value":"md`\n

\n## Imports\n\nTo start, we will import the \\`render\\` method from the \\`vega-lite-api\\` library. This method takes a Vega-Lite JSON specification as input and returns a rendered webpage element. We will use Vega-Lite version 5:\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":10,"value":"import {render} from '@vega/vega-lite-api-v5'","pinned":true,"hidden":false,"mode":"ojs"},{"id":67,"value":"md`... and a \\`printTable\\` utility for formatting data tables:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":65,"value":"import {printTable} from '@uwdata/data-utilities'","pinned":true,"hidden":false,"mode":"ojs"},{"id":29,"value":"md`\n

\n## Data\n\nData 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.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":38,"value":"md`\nWhen using Vega-Lite, datasets may be pre-loaded as an array of objects, or provided via a URL to load a network-accessible dataset. As we will see, the named columns of the data frame are an essential piece of plotting with Vega-Lite.\n\nIn these notebooks, we will often use datasets from the [vega-datasets](https://github.com/vega/vega-datasets) repository:\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":56,"value":"data = require('vega-datasets@2') // import vega_datasets","pinned":true,"hidden":false,"mode":"ojs"},{"id":59,"value":"cars = data['cars.json']() // load and parse cars data","pinned":true,"hidden":false,"mode":"ojs"},{"id":63,"value":"printTable(cars.slice(0, 5)) // display the first five rows","pinned":true,"hidden":false,"mode":"ojs"},{"id":73,"value":"md`All datasets in the vega-datasets collection can also be accessed via URLs:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":75,"value":"data['cars.json'].url","pinned":true,"hidden":false,"mode":"ojs"},{"id":362,"value":"md`_Open the URL above in a separate browser tab if you want to examine the raw data file!_`","pinned":false,"hidden":false,"mode":"ojs"},{"id":54,"value":"md`\n

\n### Weather Data\n\nStatistical visualization in Vega-Lite begins with [\"tidy\"](http://vita.had.co.nz/papers/tidy-data.html) data frames. Here, we'll start by creating a simple data frame (\\`df\\`) containing the average precipitation (\\`precip\\`) for a given \\`city\\` and \\`month\\` — written in JSON format:\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":32,"value":"df = [\n {\"city\": \"Seattle\", \"month\": \"Apr\", \"precip\": 2.68},\n {\"city\": \"Seattle\", \"month\": \"Aug\", \"precip\": 0.87},\n {\"city\": \"Seattle\", \"month\": \"Dec\", \"precip\": 5.31},\n {\"city\": \"New York\", \"month\": \"Apr\", \"precip\": 3.94},\n {\"city\": \"New York\", \"month\": \"Aug\", \"precip\": 4.13},\n {\"city\": \"New York\", \"month\": \"Dec\", \"precip\": 3.58},\n {\"city\": \"Chicago\", \"month\": \"Apr\", \"precip\": 3.62},\n {\"city\": \"Chicago\", \"month\": \"Aug\", \"precip\": 3.98},\n {\"city\": \"Chicago\", \"month\": \"Dec\", \"precip\": 2.56},\n];","pinned":true,"hidden":false,"mode":"ojs"},{"id":81,"value":"md`Or, in a more human-friendly format:\n\n${printTable(df, null, null)}\n`\n","pinned":false,"hidden":false,"mode":"ojs"},{"id":468,"value":"md`\n

\n## Marks and Encodings\n\nGiven the weather data above, we can specify how we would like the data to be visualized with Vega-Lite. We first indicate what kind of graphical *mark* (geometric shape) we want to use to represent the data. We can create a new Vega-Lite mark instance as an object with a \\`mark\\` property.\n\nWe then pass the data using the \\`data\\` property. We pass an object with a \\`values\\` key to indicate that our data is preloaded (other possibilities include loading data directly from a \\`url\\`).\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":104,"value":"render({\n mark: 'point',\n data: { values: df }\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":108,"value":"md`\nHere 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.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":132,"value":"md`\nTo visually separate the points, we can map various *encoding channels* (or just *channels* for short) to fields in the dataset. For example, we can encode the data field \\`city\\` using the \\`y\\` channel, which represents the y-axis position of the points. To specify this, use the \\`encoding\\` key with an object containing definitions for specific channels.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":110,"value":"render({\n mark: 'point',\n data: { values: df },\n encoding: {\n y: { field: 'city', type: 'nominal' }\n }\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":115,"value":"md`\nThe \\`encoding\\` property uses 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 channel as an object key. To visualize a field, we indicate the field name along with a *data type* to guide the visualization design. Here we encode the \\`city\\` field as a \\`nominal\\` type, indicating unordered, categorical values:\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":126,"value":"render({\n mark: 'point',\n data: { values: df },\n encoding: {\n y: { field: 'city', type: 'nominal' }\n }\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":122,"value":"md`\nThough we've now separated the data by one attribute, we still have multiple points overlapping within each category. Let's further separate these by adding an \\`x\\` encoding channel, mapped to the quantitative \\`precip\\` field:\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":142,"value":"render({\n mark: 'point',\n data: { values: df },\n encoding: {\n x: { field: 'precip', type: 'quantitative' },\n y: { field: 'city', type: 'nominal' }\n }\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":147,"value":"$32","pinned":false,"hidden":false,"mode":"ojs"},{"id":153,"value":"md`\n

\n## Data Transformation: Aggregation\n\nTo allow for more flexibility in how data are visualized, Vega-Lite has a built-in syntax for *aggregation* of data. For example, we can compute the average of all values by specifying an aggregation function along with the field name:\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":158,"value":"render({\n mark: 'point',\n data: { values: df },\n encoding: {\n x: { aggregate: 'average', field: 'precip' },\n y: { field: 'city', type: 'nominal' }\n }\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":164,"value":"md`\nNow within each x-axis category, we see a single point reflecting the *average* of the values within that category. Because we are averaging, Vega-Lite automatically assumes the result has a quantitative type. However, you can add a \\`type\\` property to specify a different treatment, if desired.\n\n_Does Seattle really have the lowest average precipitation of these cities? (It does!) Still, how might this plot mislead? Which months are included? What counts as precipitation?_\n\nVega-Lite supports a variety of aggregation functions, including \\`count\\`, \\`min\\` (minimum), \\`max\\` (maximum), \\`average\\`, \\`median\\`, and \\`stdev\\` (standard deviation). In a later notebook, we will take a tour of data transformations, including aggregation, sorting, filtering, and creation of new derived fields using calculation formulas.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":178,"value":"md`\n

\n## Changing the Mark Type\n\nLet's say we want to represent our aggregated values using rectangular bars rather than circular points. We can change our \\`mark\\` type from \\`\"point\"\\` to \\`\"bar\"\\`:\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":181,"value":"render({\n mark: 'bar',\n data: { values: df },\n encoding: {\n x: { aggregate: 'average', field: 'precip' },\n y: { field: 'city', type: 'nominal' }\n }\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":183,"value":"md`\nBecause the nominal field \\`city\\` is mapped to the \\`y\\`-axis, the result is a horizontal bar chart. To get a vertical bar chart, we can simply swap the \\`x\\` and \\`y\\` assignments:\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":186,"value":"render({\n mark: 'bar',\n data: { values: df },\n encoding: {\n y: { aggregate: 'average', field: 'precip' },\n x: { field: 'city', type: 'nominal' }\n }\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":189,"value":"md`\n

\n## Customizing a Visualization\n\nBy default Vega-Lite makes some choices about properties of the visualization, but these can be changed using methods to customize the look of the visualization. For example, we can modify scale properties using the \\`scale\\` property, set titles using the \\`title\\` property, and we can specify the color of the mark by passing an object to the \\`mark\\` property with a \\`color\\` property containing a valid [CSS color string](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value):\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":192,"value":"render({\n mark: { type: 'point', color: 'firebrick' },\n data: { values: df },\n encoding: {\n x: { field: 'precip', type: 'quantitative', scale: { type: 'log' }, title: 'Log-Scaled Precipitation' },\n y: { field: 'city', type: 'nominal', title: 'City' }\n }\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":196,"value":"md`A subsequent notebook will explore the various options available for scales, axes, and legends to create customized charts.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":198,"value":"md`\n

\n## Multiple Views\n\nAs we've seen above, a basic Vega-Lite visualization represents a plot with a single mark type. What about more complicated diagrams, involving multiple charts or layers? Using a set of *view composition* operators, Vega-Lite can take multiple chart definitions and combine them to create more complex views.\n\nAs a starting point, let's plot the cars dataset in a line chart, showing the average mileage by the year of manufacture:\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":200,"value":"render({\n mark: 'line',\n data: { values: cars },\n encoding: {\n x: { field: 'Year', type: 'temporal' },\n y: { aggregate: 'average', field: 'Miles_per_Gallon' }\n }\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":204,"value":"md`\nTo augment this plot, we might like to add \\`circle\\` marks for each averaged data point. (The \\`circle\\` mark is a shorthand for \\`point\\` marks that used filled circles.)\n\nWe can start by defining each chart separately: first a line plot, then a scatter plot. We can then use the \\`layer\\` operator to combine the two into a layered chart.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":208,"value":"{\n const line = {\n mark: 'line',\n data: { values: cars },\n encoding: {\n x: { field: 'Year', type: 'temporal' },\n y: { aggregate: 'average', field: 'Miles_per_Gallon' }\n }\n };\n\n const point = {\n mark: 'circle',\n data: { values: cars },\n encoding: {\n x: { field: 'Year', type: 'temporal' },\n y: { aggregate: 'average', field: 'Miles_per_Gallon' }\n }\n };\n \n return render({ layer: [line, point] });\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":220,"value":"md`\nWe can also create this chart by *reusing* a previous chart definition! Rather than completely re-write a chart, we can start with the line chart, then copy and overwrite that mark definition with a different mark type:\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":225,"value":"{\n const line = {\n mark: 'line',\n data: { values: cars },\n encoding: {\n x: { field: 'Year', type: 'temporal' },\n y: { aggregate: 'average', field: 'Miles_per_Gallon' }\n }\n };\n \n return render({ layer: [line, {...line, mark: 'circle'}] });\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":238,"value":"md`\n_(The need to place points on lines is so common, the \\`line\\` mark also includes a shorthand to generate a new layer for you. Trying setting \\`point: true\\` within the \\`mark\\` object!)_\n\nNow, what if we'd like to see this chart alongside other plots, such as the average horsepower over time?\n\nWe can use *concatenation* operators to place multiple charts side-by-side, either vertically or horizontally. Here, we'll use the \\`hconcat\\` method to perform horizontal concatenation of two charts:\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":245,"value":"{\n const mpg = {\n mark: 'line',\n data: { values: cars },\n encoding: {\n x: { field: 'Year', type: 'temporal' },\n y: { aggregate: 'average', field: 'Miles_per_Gallon' }\n }\n };\n\n const hp = {\n mark: 'line',\n data: { values: cars },\n encoding: {\n x: { field: 'Year', type: 'temporal' },\n y: { aggregate: 'average', field: 'Horsepower' }\n }\n };\n \n return render({\n hconcat: [\n { layer: [mpg, { ...mpg, mark: 'circle' }] },\n { layer: [hp, { ...hp, mark: 'circle' }] }\n ]\n });\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":249,"value":"md`\n_We can see that, in this dataset, over the 1970s and early '80s the average fuel efficiency improved while the average horsepower decreased._\n\nA later notebook will focus on *view composition*, including not only layering and concatenation, but also the \\`facet\\` operator for splitting data into sub-plots and the \\`repeat\\` operator to concisely generate concatenated charts from a template.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":254,"value":"md`\n

\n## Interactivity\n\nIn addition to basic plotting and view composition, one of Vega-Lite's more exciting features is its support for interaction.\n\nStarting with a scatter plot, we can add a basic (yet valuable!) form of interactivity – tooltips upon mouse hover – by including a \\`tooltip\\` encoding channel:\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":257,"value":"render({\n mark: 'point',\n data: { values: cars },\n encoding: {\n x: { field: 'Horsepower', type: 'quantitative' },\n y: { field: 'Miles_per_Gallon', type: 'quantitative' },\n color: { field: 'Origin' },\n tooltip: [ {field: 'Name'}, {field: 'Origin'} ] // show the Name and Origin fields in a tooltip\n }\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":266,"value":"md`\nFor more complex interactions, such as linked charts and cross-filtering, Vega-Lite provides a *selection* abstraction for defining interactive selections and then binding them to components of a chart. We will cover this is in detail in a later notebook.\n\nBelow is a more complex example. The upper histogram shows the count of cars per year and uses an interactive selection to modify the opacity of points in the lower scatter plot, which shows horsepower versus mileage.\n\n_Drag an interval in the upper chart and see how it affects the points in the lower chart. As you examine the code, **don't worry if parts don't make sense yet!** This is an aspirational example; we will fill in all the needed details over the course of the different notebooks._\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":270,"value":"$33","pinned":true,"hidden":false,"mode":"ojs"},{"id":303,"value":"$34","pinned":false,"hidden":false,"mode":"ojs"},{"id":316,"value":"md`\n

\n## Next Steps\n\n🎉 Hooray, you've completed the introduction to Vega-Lite! In the [next notebook](https://observablehq.com/@uwdata/data-types-graphical-marks-and-visual-encoding-channels), we will dive deeper into creating visualizations using Vega-Lite's model of data types, graphical marks, and visual encoding channels.\n`","pinned":false,"hidden":false,"mode":"ojs"}],"files":"$W35","stdlib":"1","titling":"auto"}