30:[] 2e:{"title":"Marks and Channels / Observable Plot","cells":[{"id":141,"value":"

Marks and Channels / Observable Plot

Observable Plot › Marks and Channels · API

\n\n# Plot: Marks and Channels\n\nPlot doesn’t have chart types. Instead, it has marks: geometric shapes such as bars, dots, and lines. Yet unlike a conventional graphics system, Plot marks are not positioned in pixels or colored literally. You draw with abstract data!","pinned":false,"hidden":false,"mode":"md"},{"id":204,"value":"To see how, let’s draw using a [dot mark](/@observablehq/plot-dot?collection=@observablehq/plot). A Plot mark is a template for generating shapes from data rather than a single shape. Consider this toy tabular dataset recording fruit sales as an array of {*units*, *fruit*} objects. We’ll hard-code the data here, but more commonly you’d load a CSV [file](/@observablehq/file-attachments?collection=@observablehq/working-with-data).","pinned":false,"hidden":false,"mode":"md"},{"id":294,"value":"sales = [\n {units: 10, fruit: \"peach\"},\n {units: 20, fruit: \"pear\"},\n {units: 40, fruit: \"plum\"},\n {units: 30, fruit: \"plum\"}\n]","pinned":true,"hidden":false,"mode":"ojs"},{"id":832,"value":"To make a plot, we bind columns of data to visual properties of marks. Since these visual properties encode abstract data, we call them *channels*. For example, we can encode the *units* column as the *x*-position and the *fruit* column as the *y*-position.","pinned":false,"hidden":false,"mode":"md"},{"id":206,"value":"Plot.dot(sales, {x: \"units\", y: \"fruit\"}).plot()","pinned":true,"hidden":false,"mode":"ojs"},{"id":229,"value":"The *x*-values {10, 20, …} are numbers representing units sold, not pixels. Under the hood, Plot constructs an implicit linear scale to map the minimum *x* = 10 to the left edge of the plot and the maximum *x* = 40 to the right edge. The *y*-values are strings representing categorical data. Plot therefore constructs an implicit ordinal (*point*) scale to divide the available vertical space evenly for the three distinct *y*-values.","pinned":false,"hidden":false,"mode":"md"},{"id":312,"value":"Named columns are convenient for tabular data represented as an array of objects, but for greater flexibility we can use a function to feed abstract values to a channel. Channel functions are repeatedly invoked for each element in the data, being passed the datum (by convention *d*) and zero-based index (*i*). These functions can also perform data processing; for example, perhaps *units* is in thousands.","pinned":false,"hidden":false,"mode":"md"},{"id":310,"value":"Plot.dot(sales, {x: d => d.units * 1000, y: d => d.fruit}).plot()","pinned":true,"hidden":false,"mode":"ojs"},{"id":299,"value":"Named columns are also nice because they allow Plot to label the axes automatically, making the meaning of the plot more apparent. These labels are lost above, but we could add them back if desired by using the *scale*.**label** option.","pinned":false,"hidden":false,"mode":"md"},{"id":870,"value":"Plot.dot(sales, {x: d => d.units, y: d => d.fruit}).plot({x: {label: \"units →\"}})","pinned":true,"hidden":false,"mode":"ojs"},{"id":201,"value":"An equivalent (and more efficient) way to specify channel values is with parallel arrays. Here it doesn’t really matter what’s in the data as long as each channel has an array of values of the same length as the data. This approach is well-suited to columnar data structures such as [Arquero](/@uwdata/introducing-arquero?collection=@uwdata/arquero).","pinned":false,"hidden":false,"mode":"md"},{"id":788,"value":"index = [0, 1, 2, 3] // any array of suitable length","pinned":true,"hidden":false,"mode":"ojs"},{"id":790,"value":"units = [10, 20, 40, 30] // x₁, x₂, …","pinned":true,"hidden":false,"mode":"ojs"},{"id":794,"value":"fruits = [\"peach\", \"pear\", \"plum\", \"plum\"] // y₁, y₂, …","pinned":true,"hidden":false,"mode":"ojs"},{"id":198,"value":"Plot.dot(index, {x: units, y: fruits}).plot()","pinned":true,"hidden":false,"mode":"ojs"},{"id":192,"value":"Many marks provide default channel definitions for even more concise shorthand. If we pass [[*x₁*, *y₁*], [*x₂*, *y₂*], [*x₃*, *y₃*], [*x₄*, *y₄*]] as data, we can use the dot’s default *x* and *y* channel definitions.","pinned":false,"hidden":false,"mode":"md"},{"id":778,"value":"xy = [\n [10, \"peach\"], // x₁, y₁\n [20, \"pear\"], // x₂, y₂\n [40, \"plum\"], // etc.\n [30, \"plum\"]\n]","pinned":true,"hidden":false,"mode":"ojs"},{"id":178,"value":"Plot.dot(xy).plot()","pinned":true,"hidden":false,"mode":"ojs"},{"id":251,"value":"Plots can have multiple marks. Marks are layered such that the last mark is drawn on top. Each mark has its own data, channels, and options. However, marks share scales. Hence, multiple marks can be used to combine datasets: the scales’ domains are inferred from the *union* of associated data. For example, if you *want* to draw each dot using a separate mark, you can, though it’s less efficient and more verbose.","pinned":false,"hidden":false,"mode":"md"},{"id":249,"value":"Plot.plot({\n marks: [\n Plot.dot([[10, \"peach\"]]), // x₁, y₁\n Plot.dot([[20, \"pear\"]]), // x₂, y₂\n Plot.dot([[40, \"plum\"]]), // etc.\n Plot.dot([[30, \"plum\"]])\n ]\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":704,"value":"Marks can also be used as annotations for values with special meaning, such as the [rule](/@observablehq/plot-rule?collection=@observablehq/plot) at *x* = 0 below.","pinned":false,"hidden":false,"mode":"md"},{"id":356,"value":"Plot.plot({\n marks: [\n Plot.dot(sales, {x: \"units\", y: \"fruit\"}),\n Plot.ruleX([0]) // a rule at x = 0\n ]\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":351,"value":"Plot currently supports about a dozen mark types: [Area](/@observablehq/plot-area?collection=@observablehq/plot), [Bar](/@observablehq/plot-bar?collection=@observablehq/plot), [Cell](/@observablehq/plot-cell?collection=@observablehq/plot), [Dot](/@observablehq/plot-dot?collection=@observablehq/plot), [Frame](/@observablehq/plot-frame?collection=@observablehq/plot), [Line](/@observablehq/plot-line?collection=@observablehq/plot), [Link](/@observablehq/plot-link?collection=@observablehq/plot), [Rect](/@observablehq/plot-rect?collection=@observablehq/plot), [Rule](/@observablehq/plot-rule?collection=@observablehq/plot), [Text](/@observablehq/plot-text?collection=@observablehq/plot), and [Tick](/@observablehq/plot-tick?collection=@observablehq/plot). Mark types do not just determine shape — they also determine which channels and options are supported, and what scales are associated with each channel, if any. Both bar and dot support *x* and *y* position.","pinned":false,"hidden":false,"mode":"md"},{"id":145,"value":"Plot.barX(sales, {x: \"units\", y: \"fruit\"}).plot() // bars extends from x = 0","pinned":true,"hidden":false,"mode":"ojs"},{"id":640,"value":"The [bar mark](/@observablehq/plot-bar?collection=@observablehq/plot) is closely related to the [rect mark](/@observablehq/plot-rect?collection=@observablehq/plot). Both generate a rectangle; the difference is in how the coordinates of the rectangle are specified. For a bar, one side is a quantitative interval (*e.g.*, from 0 to a number of units sold) while the other is an ordinal (or categorical) value (*e.g.*, a fruit name); whereas for a rect, both sides are quantitative intervals. Hence a bar is used for a bar chart but a rect is needed for a histogram.","pinned":false,"hidden":false,"mode":"md"},{"id":366,"value":"The barX’s *x* channel is shorthand for an implicit [stack transform](/@observablehq/plot-stack?collection=@observablehq/plot) on *x*, producing *x1* and *x2* channels. You can define these channels explicitly if preferred.","pinned":false,"hidden":false,"mode":"md"},{"id":369,"value":"Plot.barX(sales, {x1: 0, x2: \"units\", y: \"fruit\"}).plot()","pinned":true,"hidden":false,"mode":"ojs"},{"id":538,"value":"Note that since there are two data points for plums, and because we explicitly set *x1* to zero instead of stacking, there are two overlapping bars hidden above. We can reveal them by setting the *fillOpacity* option. Whereas mark channels vary with data, mark options are shared by all instances of a mark. Both channels and options are specified in the same object (the second argument to the mark constructor, after data). See the mark type reference to know what channels and options are available.","pinned":false,"hidden":false,"mode":"md"},{"id":524,"value":"Plot.barX(sales, {x1: 0, x2: \"units\", y: \"fruit\", fillOpacity: 0.5}).plot()","pinned":true,"hidden":false,"mode":"ojs"},{"id":895,"value":"If our goal is to show the total units sold, we could [group](/@observablehq/plot-group?collection=@observablehq/plot) to sum the values for each fruit instead of stacking. This aggregates the mark’s data along with its *x* and *y* channels, producing a single bar per fruit.","pinned":false,"hidden":false,"mode":"md"},{"id":536,"value":"Plot.barX(sales, Plot.groupY({x: \"sum\"}, {x: \"units\", y: \"fruit\"})).plot()","pinned":true,"hidden":false,"mode":"ojs"},{"id":395,"value":"Bars support a *fill* option, should we desire blue bars instead of inheriting the text color from the surrounding page. We can also add a [rule](/@observablehq/plot-rule?collection=@observablehq/plot) to denote *x* = 0.","pinned":false,"hidden":false,"mode":"md"},{"id":397,"value":"Plot.plot({\n marks: [\n Plot.barX(sales, {x: \"units\", y: \"fruit\", fill: \"steelblue\"}),\n Plot.ruleX([0])\n ]\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":400,"value":"The *fill* option can also be specified as a channel to encode abstract data as color. We can use a categorical color encoding to give each bar a distinct color.","pinned":false,"hidden":false,"mode":"md"},{"id":402,"value":"Plot.plot({\n marks: [\n Plot.barX(sales, {x: \"units\", y: \"fruit\", fill: \"fruit\"}),\n Plot.ruleX([0])\n ]\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":404,"value":"How did Plot know that “fruit” is a field name, while “steelblue” is a color, if both are strings? Plot checks whether the *fill* is a valid CSS color; if it is, it interprets it as an option, and otherwise, as a field name for a channel. To explicitly declare *fill* as a channel, pass a function or an array of values.","pinned":false,"hidden":false,"mode":"md"},{"id":420,"value":"Plot.plot({\n marks: [\n Plot.barX(sales, {x: \"units\", y: \"fruit\", fill: d => d.fruit}),\n Plot.ruleX([0])\n ]\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":474,"value":"If you define the *fill* channel as a function, the function might return literal colors—in the case where all the values are valid CSS colors, Plot passes them through:","pinned":false,"hidden":false,"mode":"md"},{"id":406,"value":"Plot.plot({\n marks: [\n Plot.barX(sales, {x: \"units\", y: \"fruit\", fill: d => d.units > 20 ? \"black\" : \"red\"}),\n Plot.ruleX([0])\n ]\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":414,"value":"However, instead of returning literal colors, you might prefer to return an abstract value and then set the scale’s domain and range as desired. As a benefit, this allows Plot to generate a meaningful color legend. Now you’re thinking with data!","pinned":false,"hidden":false,"mode":"md"},{"id":409,"value":"Plot.plot({\n color: {\n domain: [\"small\", \"big\"],\n range: [\"red\", \"black\"],\n legend: true\n },\n marks: [\n Plot.barX(sales, {x: \"units\", y: \"fruit\", fill: d => d.units > 20 ? \"big\" : \"small\"}),\n Plot.ruleX([0])\n ]\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":737,"value":"Next, let’s dive behind the scenes to take a look at scales.\n\nNext \nAPI Reference","pinned":false,"hidden":false,"mode":"md"}],"files":"$W30","stdlib":"1","titling":"auto"}