31:T62f,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. At its core, Vega-Lite uses [JavaScript Object Notation (JSON)](https://en.wikipedia.org/wiki/JSON) as a stand-alone file format for describing charts. However, to create Vega-Lite visualizations in a more convenient and programmatic way, we will be using the [Vega-Lite API](https://github.com/vega/vega-lite-api), a set of JavaScript methods that produce Vega-Lite JSON specifications as output. _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:T416,md` _Seattle exhibits both the least-rainiest and most-rainiest months!_ Above we use the \`fieldQ\` method 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 (\`fieldN\`) and quantitative types (\`fieldQ\`). The complete set of type-specific field methods is: - \`fieldN()\` indicates a *nominal* type (unordered, categorical data), - \`fieldO()\` indicates an *ordinal* type (rank-ordered data), - \`fieldQ()\` indicates a *quantitative* type (numerical magnitudes), - \`fieldT()\` 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:T4ae,{ // create an interval selection over an x-axis encoding const brush = vl.selectInterval().encodings('x'); // determine opacity based on brush const opacity = vl.opacity().if(brush, vl.value(0.9)).value(0.1); // an overview histogram of cars per year // add the interval brush to select cars over time const overview = vl.markBar() .encode( vl.x().fieldO('Year').timeUnit('year') // extract year unit, treat as ordinal .axis({title: null, labelAngle: 0}), // no title, no label angle vl.y().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 = vl.markPoint() .encode( vl.x().fieldQ('Horsepower'), vl.y().fieldQ('Miles_per_Gallon'), opacity // modulate point opacity based on the brush selection ); // vertically concatenate (vconcat) charts return vl.data(cars).vconcat(overview, detail).render(); }34:T609,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). Take an exported Vega-Lite JSON string, and incorporate it in a web page that imports vega-embed. Here is a basic HTML template, where the JSON specification for your plot produced by \`chart.toObject()\` 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","cells":[{"id":0,"value":"md`# Introduction to Vega-Lite\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 \\`vega-lite-api\\` library. We will use Vega-Lite version 5:\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":10,"value":"import {vl} 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@1') // 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 using the \\`vl.mark*\\` methods.\n\nWe 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:\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":104,"value":"vl.markPoint()\n .data(df)\n .render()","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 \\`encode()\\` method, passing it definitions for specific channels.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":110,"value":"vl.markPoint()\n .data(df)\n .encode(vl.y().field('city').type('nominal'))\n .render()","pinned":true,"hidden":false,"mode":"ojs"},{"id":115,"value":"md`\nThe \\`encode()\\` 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 \\`city\\` field as a *nominal* type, indicating unordered, categorical values.\n\nFor brevity, we can use the shorthand \\`fieldN()\\` method to specify both the field name and a \\`'nominal'\\` type simultaneously:\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":126,"value":"vl.markPoint()\n .data(df)\n .encode(vl.y().fieldN('city'))\n .render()","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":"vl.markPoint()\n .data(df)\n .encode(\n vl.x().fieldQ('precip'),\n vl.y().fieldN('city')\n )\n .render()","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":"vl.markPoint()\n .data(df)\n .encode(\n vl.x().average('precip'),\n vl.y().fieldN('city')\n )\n .render()","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, the Vega-Lite API automatically assumes the result is a quantitative variable. However, you can add a \\`.type()\\` call 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 do this by replacing \\`vl.markPoint\\` with \\`vl.markBar\\`:\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":181,"value":"vl.markBar()\n .data(df)\n .encode(\n vl.x().average('precip'),\n vl.y().fieldN('city')\n )\n .render()","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":"vl.markBar()\n .data(df)\n .encode(\n vl.y().average('precip'),\n vl.x().fieldN('city')\n )\n .render()","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*\\` method 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":"vl.markPoint({color: 'firebrick'})\n .data(df)\n .encode(\n vl.x().fieldQ('precip').scale({type: 'log'}).title('Log-Scaled Precipitation'),\n vl.y().fieldN('city').title('City')\n )\n .render()","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":"vl.markLine()\n .data(cars)\n .encode(\n vl.x().fieldT('Year'),\n vl.y().average('Miles_per_Gallon')\n )\n .render()","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 = vl.markLine().data(cars).encode(\n vl.x().fieldT('Year'),\n vl.y().average('Miles_per_Gallon')\n );\n\n const point = vl.markCircle().data(cars).encode(\n vl.x().fieldT('Year'),\n vl.y().average('Miles_per_Gallon')\n );\n \n return vl.layer(line, point).render();\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 invoke the \\`mark\\` method to generate a new chart definition with a different mark type:\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":225,"value":"{\n const mpg = vl.markLine().data(cars).encode(\n vl.x().fieldT('Year'),\n vl.y().average('Miles_per_Gallon')\n );\n\n return vl.layer(mpg, mpg.markCircle()).render();\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 passing \\`{point:true}\\` to the \\`markLine\\` method!)_\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 = vl.markLine().data(cars).encode(\n vl.x().fieldT('Year'),\n vl.y().average('Miles_per_Gallon')\n );\n \n const hp = mpg.encode(vl.y().average('Horsepower'));\n\n return vl.hconcat(\n vl.layer(mpg, mpg.markCircle()),\n vl.layer(hp, hp.markCircle())\n ).render();\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":"vl.markPoint().data(cars).encode(\n vl.x().fieldQ('Horsepower'),\n vl.y().fieldQ('Miles_per_Gallon'),\n vl.color().fieldN('Origin'),\n vl.tooltip(['Name', 'Origin']) // show the Name and Origin fields in a tooltip\n).render()","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":288,"value":"md`\n

\n## Aside: Examining JSON Output\n\nThe Vega-Lite API converts plot specifications to a [JSON](https://en.wikipedia.org/wiki/JSON)-compatible object format that conforms to the Vega-Lite schema. Using the \\`toObject()\\` method, we can inspect the specification that is sent to Vega-Lite:\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":290,"value":"{\n const plot = vl.markCircle().encode(\n vl.x().average('precip'),\n vl.y().fieldN('city')\n );\n \n return html`

${JSON.stringify(plot.toObject(), 0, 2)}

`; // format JSON data\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":294,"value":"md`\nNotice here that \\`vl.x().average('precip')\\` has been expanded to a structure with a \\`field\\` name, a \\`type\\` for the data (automatically chosen to correspond to averages), and includes an \\`aggregate\\` field.\n\nThe \\`vl.y().fieldN('city')\\` statement has been expanded similarly.\n\nOn a related note: in addition to providing convenience methods, the Vega-Lite API can accept JavaScript objects directly. For example, here is the same chart above, with the encodings provided directly in Vega-Lite JSON format: \n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":299,"value":"{\n const plot = vl.markCircle().encode({\n x: {field: 'precip', type: 'quantitative', aggregate: 'average'},\n y: {field: 'city', type: 'nominal'}\n });\n \n return html`

${JSON.stringify(plot.toObject(), 0, 2)}

`; // format JSON data\n}","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"}