25:["$","title",null,{"children":"Charting with Vega-Lite | Charles Gonçalves | Observable"}] 49:T4c1,md`# Charting with Vega-Lite So you want to make a chart, _now_. You’ve come to the right place. _Pre-requisites: [A Taste of Observable](/d/4e36c4335cde0fd3), [Introduction to Data](/@observablehq/introduction-to-data)_ For rapid charting and fast [explorations of data](https://en.wikipedia.org/wiki/Exploratory_data_analysis) in Observable, we recommend [Vega-Lite’s JavaScript API](/@vega/vega-lite-api): you get all the classic, standard charts in just a few lines of code, and then build on them with advanced [faceting, layering](layers-facets-concat), and [interactivity](/@vega/vega-lite-cross-filter-example?collection=@vega/vega-lite-api). Vega-Lite is more powerful than making an off-the-shelf chart in Excel, and faster than making a totally custom visualization in D3. With [plenty of examples to learn from](https://vega.github.io/vega-lite/examples/), it’s supported by a broad community, even extending into other languages like Python with [Altair](https://altair-viz.github.io/). This tutorial is itself an Observable notebook, so all the code is live, and we’ll be encouraging you to try these techniques yourself as you go. First, you can import Vega-Lite to this notebook like so:`4a:[{"id":"1c2c8f12f99ab5d1f9bd36419c49fbbb9c6fcf808ec98df7fd2377187fd38bdfcd20bb7c32ccb043e6a0a85011dd4377128d2a5d1bd4d6d48079ab5d8fbc3186","href":"https://static.observableusercontent.com/files/1c2c8f12f99ab5d1f9bd36419c49fbbb9c6fcf808ec98df7fd2377187fd38bdfcd20bb7c32ccb043e6a0a85011dd4377128d2a5d1bd4d6d48079ab5d8fbc3186","name":"cars.json","type":"application/json","lastModified":1681309264189.237,"size":100492}] 29:{"id":"b0f648e11cc9c5e2","slug":null,"title":"Charting with Vega-Lite","thumbnail":"0837f1f7849c13007f81cd7a0f64168f10f9d13335c731ea71d71b81e2df161b","access_level":"public","create_time":"$D2023-04-12T14:21:04.189Z","update_time":"$D2023-04-12T14:22:24.744Z","view_time":null,"first_public_time":"$D2023-04-12T14:21:04.189Z","has_unpublished_edits":null,"fork":{"id":"3c458cfcac4dbda8","slug":"vega-lite","title":"Charting with Vega-Lite","owner":{"id":"f35c755083683fe5","login":"observablehq","name":"Observable"}},"stars":0,"starred":false,"owner":{"type":"team","id":"bea57faf220aebc3","login":"c-goncalves-belo","name":"Charles Gonçalves","avatar_url":"https://avatars-next.observableusercontent.com/4c85e905c4cfc36bc3a3e2af911075858df0ad896524d4021e98f7b16006a721","tier":"starter_2024","bio":"","followed_by_you":false,"follows_you":false},"version":569,"publish_version":null,"role":null,"authored":false,"authors":[{"type":"individual","id":"1785b79c96e37da7","login":"c-goncalves-belo","name":"Charles Gonçalves","avatar_url":"https://avatars-next.observableusercontent.com/4c85e905c4cfc36bc3a3e2af911075858df0ad896524d4021e98f7b16006a721","tier":null,"bio":"","followed_by_you":false,"follows_you":false}],"members":[{"type":"individual","id":"1785b79c96e37da7","login":"c-goncalves-belo","name":"Charles Gonçalves","avatar_url":"https://avatars-next.observableusercontent.com/4c85e905c4cfc36bc3a3e2af911075858df0ad896524d4021e98f7b16006a721","tier":null,"role":"editor"}],"comments":[],"custom_thumbnail":false,"trashed":false,"lapsed":null,"subscribed":null,"forks":0,"collection":null,"type":"notebook","body":{"titling":"auto","title":"Charting with Vega-Lite","cells":[{"id":0,"value":"$49","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":6,"value":"import { vl } from \"@vega/vega-lite-api\"","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":7,"value":"md`And now to make our first chart:`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":13,"value":"vl.markSquare({size: 80}) // Make a scatter chart\n .data(cars) // Using the cars data (below)\n .encode(\n vl.x().fieldQ(\"Horsepower\"), // For x, use the Horsepower field\n vl.y().fieldQ(\"Miles_per_Gallon\"), // For y, use the Miles_per_Gallon field\n vl.tooltip().fieldN(\"Name\") // For tooltips, show the Name field\n )\n .render() // Draw the chart","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":15,"value":"cars = FileAttachment(\"cars.json\").json()","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":17,"value":"md`## How it works\n\nWe’ve charted some car model data! Specifically, we’re looking at how horsepower and gas mileage correlate: as horsepower goes up, miles per gallon tends to go down. You can hover over or tap on different points to see the corresponding car model name.\n\nLet’s step through the pieces making up this chart definition.`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":22,"value":"md`### markCircle()\nThis is the type of chart we’re trying to make. For this example, we chose a scatter plot using circles at each point. Vega-Lite has several other [mark types](https://vega.github.io/vega-lite/docs/mark.html#types) to represent line and bar charts, maps, tables, etc.\n\n${tryIt(`\nPass an option of \\`{ size: 200 }\\` to \\`markCircle()\\`. \nTry \\`markSquare\\` instead of \\`markCircle\\`. \nTry \\`markPoint({ shape: 'diamond' })\\`. \n`)}`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":25,"value":"md`### data()\nWe pass our data to Vega-Lite with the \\`data()\\` method as an array. You can also pass a URL as a string and Vega-Lite will fetch it for you and parse it.\n\nOur data in this case is an array of objects. Each object has the same set of key/value fields:`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":72,"value":"cars[0]","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":88,"value":"md`### encode()\nThere are plenty of ways we can visualize our data. We can use position on the screen (x and y), color, shape, size. The parameters we pass to \\`encode()\\` define an encoding or mapping between our data and the chart. There are [many encodings](https://vega.github.io/vega-lite/docs/encoding.html) available.`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":27,"value":"md`### vl.x().fieldQ(\"Horsepower\"), vl.y().fieldQ(\"Miles_per_Gallon\")\nWe want to see horsepower displayed on the _x_-axis and miles per gallon on the _y_-axis. The string passed to \\`fieldQ()\\` matches the field of an object row. Q stands for _quantitative_ (more on that in a bit).\n\n${tryIt(`\nChange Horsepower to Acceleration. \nSwap what fields are displayed on the _x_- and _y_-axis. \nRemove the _y_ definition altogether. \n`)}`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":213,"value":"md`### vl.tooltip().fieldN(\"Name\")\n\nSimilar to the x and y encodings, we can add tooltips for each point by specifying another field to encode as the tooltip content. Here, we want to see the name of the car model for each point. N stands for _nominal_ (again, more on that a bit later).\n\n${tryIt(`\nChange Name to Origin. \n`)}`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":29,"value":"md`### render()\nFinally, we render and return our chart! \\`render()\\` can take a few options to tweak the output format. Instead of rendering, we can also use \\`toObject()\\` to return the underlying [Vega-Lite JSON specification](https://vega.github.io/vega-lite/docs/) created by the API. This representation can be helpful when debugging the API.\n\n${tryIt(`\nPass the option \\`{ renderer: \"svg\" }\\` to the render method. \nReplace \\`render()\\` with \\`toObject()\\`. \n`)}`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":31,"value":"md`---\n## Another example\n\nHow about counting the number of car models by country of origin?`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":34,"value":"vl.markBar() // Make a bar chart\n .data(cars) // With the cars data again\n .encode(\n vl.y().fieldN(\"Origin\"), // y can come before x: different orders won't break anything\n vl.x().count() // For x, count the number of records\n )\n .render() // Draw the chart","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":110,"value":"md`This is pretty similar to our previous example, with a few key differences:\n### encode() parameter order\nYou may have noticed _y_ came before _x_ this time. The order of encodings doesn’t matter to Vega-Lite. You should choose the order that makes the most sense to you. In this case, we chose to list the independent variable “Origin” before the dependent variable count.`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":111,"value":"md`### fieldN()\n\nLet’s talk about these Q and N suffixes! The \\`N\\` suffix stands for _nominal_. Since the values of Origin are strings like “Japan” and “USA”, we want the field to be interpreted as a nominal or categorical name rather than a quantitative number or value. This helps Vega-Lite determine corresponding scale and axis types.\n\nThe full set of [field types](https://vega.github.io/vega-lite/docs/encoding.html#field-def) are:\n\nMethod | Type | Description | Examples\n--- | --- | ---\n\\`fieldQ()\\` | quantitative | numerical magnitudes | 1, 1.2, 3, 4, $1,230.60\n\\`fieldT()\\` | temporal | corresponding to Date values | 2019-01-02T00:01:23Z, 1996\n\\`fieldN()\\` | nominal | unordered, categorical data | Audi, Ford, Hyundai, Tesla\n\\`fieldO()\\` | ordinal | like nominal, but with an inherent order | small, medium, large\n\n${tryIt(`\nChange \\`fieldN()\\` back to \\`fieldQ()\\` for an undesirable result. \n`)}`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":118,"value":"md`### count()\n\n\\`count()\\` is an [aggregation function](https://vega.github.io/vega-lite/docs/aggregate.html#ops). We’re counting the number of rows, grouping by the other fields (Origin). We’ll talk more about aggregation in Vega-Lite in [Part 2: Vega-Lite Chart Types](vega-lite-chart-types)!\n\n${tryIt(`\nRemove the \\`vl.y().fieldN(\"Origin\")\\` line to see an ungrouped count. \nReplace \\`count()\\` with \\`average(\"Miles_per_Gallon\")\\` to see average gas mileage by country. \n`)}`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":36,"value":"md`---\n## The shape of your data matters\n\nThe _shape_ of your data matters when creating charts. This is true of Vega-Lite and all JavaScript charting libraries.\n\nThe best shape in Vega-Lite’s case is referred to as [tidy data](https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-data.html). Having your data in this shape will benefit you in other data tools like R or Tableau too. The cars dataset we’ve been using is already in this format, where each row represents an “observation” or instance of something and each column represents a “variable.”\n\nTo be clear, you don’t _need_ your data in this exact structure to get a meaningful chart out of Vega-Lite, but to you’ll find it makes things a lot easier to think about and write code for if you do.\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":42,"value":"Inputs.table(cars, { width: 660 })","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":48,"value":"md`---\n## Next\nIn our next notebook, we’ll explore more chart types!\n\nIf you haven’t yet, you should read through [A Taste of Observable](/d/4e36c4335cde0fd3) and [Introduction to Data](/@observablehq/introduction-to-data) before continuing. This tutorial series assumes you already understand the topics covered in those notebooks.`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":401,"value":"html`Next`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":275,"value":"md`---`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":278,"value":"function tryIt(text) {\n const list = text.split(\"\\n\").filter(s => s).map(s => `

– ${s}`);\n return md`\n

\n**Try it yourself:**\n
\n${list.join(\"\")}\n
\n

`;\n}","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"}],"files":"$W4a","stdlib":"1"}} 24:null