Vega-Lite MCP Server

[ { "title": "Overview", "url": "https://vega.github.io/vega-lite/docs/", "content": "Vega-Lite Vega Altair Vega-Lite API Examples Tutorials Documentation Usage Ecosystem GitHub Try Online Overview View Specification Title Width / Height Data / Datasets Transform Aggregate Bin Calculate Density Extent Filter Flatten Fold Impute Join Aggregate Loess Lookup Pivot Quantile Regression Sample Stack Time Unit Window Mark Arc Area Bar Box Plot Circle Error Band Error Bar Geoshape Image Line Point Rect Rule Square Text Tick Trail Encoding Aggregate Axis Band Position Bin Condition Datum Field Format Header Impute Legend Scale Stack Sort Time Unit Type Value Projection View Composition Facet Layer Concat Repeat Resolve Parameter Value Expr Bind Select Config Property Types Date Time Gradient Predicate Tooltip Invalid Data Overview Edit this page Vega-Lite is a high-level grammar for interactive graphics. It provides a concise JSON syntax for supporting rapid generation of interactive multi-view visualizations to support analysis. Vega-Lite can serve as a declarative format for describing and creating data visualizations. To use Vega-Lite, our compiler compiles a Vega-Lite specification into a lower-level, more detailed Vega specifications and rendered using Vega’s compiler. This documentation describes the JSON specification language and how to use Vega-Lite visualizations in a web application. Search Table of Contents Below is an overview of the documentation for Vega-Lite properties. See the specification page for an overview of Vega-Lite specifications. Overview Table of Contents View Specification Documentation Overview Common Properties of Specifications Top-Level Specifications Single View Specifications Layered and Multi-view Specifications View Configuration Title Title Properties Object Title Config Width / Height Documentation Overview Width and Height of Single and Layered Plots Width and Height of Multi-View Displays Data / Datasets Documentation Overview Types of Data Sources Format Data Generators Datasets Transform View-level Transform Property Aggregate Documentation Overview Aggregate in Encoding Field Definition Aggregate Transform Supported Aggregation Operations Argmin / Argmax Bin Documentation Overview Binning in Encoding Field Definition Bin Transform Bin Parameters Ordinal Bin Calculate Calculate Transform Definition Example Density Density Transform Definition Usage Extent Extent Transform Definition Usage Example Filter Flatten Flatten Transform Definition Usage Examples Fold Fold Transform Definition Usage Example Impute Documentation Overview Impute in Encoding Field Definition Impute Transform Join Aggregate Documentation Overview Join Aggregate Field Definition Join Aggregate Transform Definition Examples Loess Loess Transform Definition Usage Example Lookup Lookup Transform Pivot Pivot Transform Definition Usage Example Quantile Quantile Transform Definition Usage Regression Regression Transform Definition Usage Example Sample Sample Transform Definition Usage Example Stack Documentation Overview Stack in Encoding Field Definition Stack Transform Time Unit Documentation Overview Time Unit in Encoding Field Definition Time Unit Transform UTC time Time Unit Parameters Window Documentation Overview Window Field Definition Window Transform Definition Window Only Operation Reference Examples Mark Documentation Overview Mark Types Mark Definition Object Mark Config Mark Style Config Arc Documentation Overview Arc Mark Properties Examples Arc Config Faceted Pie Charts Area Documentation Overview Area Mark Properties Examples Area Config Bar Documentation Overview Bar Mark Properties Examples Bar Config Box Plot Documentation Overview Box Plot Mark Properties Types of Box Plot Dimension & Orientation The Parts of Box Plots Color, Size, and Opacity Encoding Channels Tooltip Encoding Channels Mark Config Box Plot with Pre-Calculated Summaries Circle Circle Mark Properties Examples Circle Config Error Band Documentation Overview Error Band Mark Properties Comparing the usage of Error Band to the usage of Error Bar Using Error Band to Aggregate Raw Data Using Error Band to Visualize Aggregated Data Dimension The Parts of Error Band Color, and Opacity Encoding Channels Tooltip Encoding Channels Mark Config Error Bar Documentation Overview Error Bar Mark Properties Using Error Bars to Aggregate Raw Data Using Error Bars to Visualize Aggregated Data Dimension & Orientation The Parts of Error Bars Color, and Opacity Encoding Channels Tooltip Encoding Channels Mark Config Geoshape Geoshape Config Image Documentation Overview Image Mark Properties Examples Image Config Line Documentation Overview Line Mark Properties Examples Line Config Point Documentation Overview Point Mark Properties Examples Point Config Rect Documentation Overview Rect Mark Properties Examples Rect Config Rule Documentation Overview Rule Mark Properties Examples Rule Config Square Square Mark Properties Example: Scatterplot with Square Square Config Text Documentation Overview Text Mark Properties Examples Text Con", "category": "introduction", "source": "vega-lite" }, { "title": "Mark", "url": "https://vega.github.io/vega-lite/docs/mark.html", "content": "Vega-Lite Vega Altair Vega-Lite API Examples Tutorials Documentation Usage Ecosystem GitHub Try Online Overview View Specification Title Width / Height Data / Datasets Transform Aggregate Bin Calculate Density Extent Filter Flatten Fold Impute Join Aggregate Loess Lookup Pivot Quantile Regression Sample Stack Time Unit Window Mark Arc Area Bar Box Plot Circle Error Band Error Bar Geoshape Image Line Point Rect Rule Square Text Tick Trail Encoding Aggregate Axis Band Position Bin Condition Datum Field Format Header Impute Legend Scale Stack Sort Time Unit Type Value Projection View Composition Facet Layer Concat Repeat Resolve Parameter Value Expr Bind Select Config Property Types Date Time Gradient Predicate Tooltip Invalid Data Mark Edit this page Marks are the basic visual building block of a visualization. They provide basic shapes whose properties (such as position, size, and color) can be used to visually encode data, either from a data field, or a constant value. The mark property of a single view specification can either be (1) a string describing a mark type or (2) a mark definition object. // Single View Specification { \"data\": ... , \"mark\": ... , // mark \"encoding\": ... , ... } Documentation Overview Mark Types Mark Definition Object General Mark Properties Position and Offset Properties Color Properties Stroke Style Properties Hyperlink Properties Mark Config Mark Style Config Example: Styling Labels Mark Types Vega-Lite supports the following primitive mark types: \"area\", \"bar\", \"circle\", \"line\", \"point\", \"rect\", \"rule\", \"square\", \"text\", \"tick\", and \"geoshape\". In general, one mark instance is generated per input data element. However, line and area marks represent multiple data elements as a contiguous line or shape. In addition to primitive marks, Vega-Lite also support composite marks, which are “macros” for complex layered graphics that contain multiple primitive marks. Supported composite mark types include \"boxplot\", \"errorband\", \"errorbar\". For example, a bar chart has mark as a simple string \"bar\". Mark Definition Object // Single View Specification { ... \"mark\": { \"type\": ..., // mark ... }, ... } To customize properties of a mark, users can set mark to be a mark definition object instead of a string describing mark type. The rest of this section lists standard mark properties for primitive mark types. Additionally, some marks may have special mark properties (listed in their documentation page). For example, point marks support shape and size properties in addition to these standard properties. Note: If mark property encoding channels are specified, these mark properties will be overridden. General Mark Properties Property Type Description type String Required. The mark type. This could a primitive mark type (one of \"bar\", \"circle\", \"square\", \"tick\", \"line\", \"area\", \"point\", \"geoshape\", \"rule\", and \"text\") or a composite mark type (\"boxplot\", \"errorband\", \"errorbar\"). aria Boolean | ExprRef A boolean flag indicating if ARIA attributes should be included (SVG output only). If false, the “aria-hidden” attribute will be set on the output SVG element, removing the mark item from the ARIA accessibility tree. cursor String | ExprRef The mouse cursor used over the mark. Any valid CSS cursor type can be used. description String | ExprRef A text description of the mark item for ARIA accessibility (SVG output only). If specified, this property determines the “aria-label” attribute. style String | String[] A string or array of strings indicating the name of custom styles to apply to the mark. A style is a named collection of mark property defaults defined within the style configuration. If style is an array, later styles will override earlier styles. Any mark properties explicitly defined within the encoding will override a style default. Default value: The mark’s name. For example, a bar mark will have style \"bar\" by default. Note: Any specified style will augment the default style. For example, a bar mark with \"style\": \"foo\" will receive from config.style.bar and config.style.foo (the specified style \"foo\" has higher precedence). tooltip Number | String | Boolean | TooltipContent | ExprRef | Null The tooltip text string to show upon mouse hover or an object defining which fields should the tooltip be derived from. If tooltip is true or {\"content\": \"encoding\"}, then all fields from encoding will be used. If tooltip is {\"content\": \"data\"}, then all fields that appear in the highlighted data point will be used. If set to null or false, then no tooltip will be used. See the tooltip documentation for a detailed discussion about tooltip in Vega-Lite. Default value: null clip Boolean | ExprRef Whether a mark be clipped to the enclosing group’s width and height. invalid String | Null Invalid data mode, which defines how the marks and corresponding scales should represent invalid values (null and NaN in continuous scales without defined output for invalid values). \"filter\" — Exclude all invalid values ", "category": "marks", "source": "vega-lite" }, { "title": "Encoding", "url": "https://vega.github.io/vega-lite/docs/encoding.html", "content": "Vega-Lite Vega Altair Vega-Lite API Examples Tutorials Documentation Usage Ecosystem GitHub Try Online Overview View Specification Title Width / Height Data / Datasets Transform Aggregate Bin Calculate Density Extent Filter Flatten Fold Impute Join Aggregate Loess Lookup Pivot Quantile Regression Sample Stack Time Unit Window Mark Arc Area Bar Box Plot Circle Error Band Error Bar Geoshape Image Line Point Rect Rule Square Text Tick Trail Encoding Aggregate Axis Band Position Bin Condition Datum Field Format Header Impute Legend Scale Stack Sort Time Unit Type Value Projection View Composition Facet Layer Concat Repeat Resolve Parameter Value Expr Bind Select Config Property Types Date Time Gradient Predicate Tooltip Invalid Data Encoding Edit this page An integral part of the data visualization process is encoding data with visual properties of graphical marks. The encoding property of a single view specification represents the mapping between encoding channels (such as x, y, or color) and data fields, constant visual values, or constant data values (datum). // Specification of a Single View { \"data\": ... , \"mark\": ... , \"encoding\": { // Encoding // Position Channels \"x\": ..., \"y\": ..., \"x2\": ..., \"y2\": ..., \"xError\": ..., \"yError\": ..., \"xError2\": ..., \"yError2\": ..., // Polar Position Channels \"theta\": ..., \"radius\": ..., \"theta2\": ..., \"radius2\": ..., // Geographic Position Channels \"longitude\": ..., \"latitude\": ..., \"longitude2\": ..., \"latitude2\": ..., // Mark Properties Channels \"color\": ..., \"opacity\": ..., \"fillOpacity\": ..., \"strokeOpacity\": ..., \"strokeWidth\": ..., \"strokeDash\": ..., \"size\": ..., \"angle\": ..., \"shape\": ..., // Text and Tooltip Channels \"text\": ..., \"tooltip\": ..., // Hyperlink Channel \"href\": ..., // Description Channel \"description\": ..., // Level of Detail Channel \"detail\": ..., // Key Channel \"key\": ..., // Order Channel \"order\": ..., // Facet Channels \"facet\": ..., \"row\": ..., \"column\": ... }, ... } Encoding Channels The keys in the encoding object are encoding channels. Vega-Lite supports the following groups of encoding channels Position Channels: x, y, x2, y2, xError, yError, xError2, yError2 Position Offset Channels: xOffset, yOffset Polar Position Channels: theta, theta2, radius, radius2 Geographic Position Channels: longitude, latitude, longitude2, latitude2 Mark Property Channels: angle, color (and fill / stroke), opacity, fillOpacity, strokeOpacity, shape, size, strokeDash, strokeWidth Text and Tooltip Channels: text, tooltip Hyperlink Channel: href Description Channel: description Level of Detail Channel: detail Key Channel: key Order Channel: order Facet Channels: facet, row, column Channel Definition Each channel definition object must be one of the following: Field definition, which describes the data field encoded by the channel. Value definition, which describes an encoded constant visual value. Datum definition, which describes a constant data value encoded via a scale. Field Definition // Specification of a Single View { ..., \"encoding\": { // Encoding ...: { \"field\": ..., \"type\": ..., ... }, ... }, ... } To encode a particular field in the data set with an encoding channel, the channel’s field definition must describe the field name and its data type. To facilitate data exploration, Vega-Lite also provides inline field transforms (aggregate, bin, sort, stack, and timeUnit) as a part of a field definition in addition to the top-level transform. All field definitions support the following properties: Property Type Description field Field Required. A string defining the name of the field from which to pull a data value or an object defining iterated values from the repeat operator. See also: field documentation. Notes: 1) Dots (.) and brackets ([ and ]) can be used to access nested objects (e.g., \"field\": \"foo.bar\" and \"field\": \"foo['bar']\"). If field names contain dots or brackets but are not nested, you can use \\\\ to escape dots and brackets (e.g., \"a\\\\.b\" and \"a\\\\[0\\\\]\"). See more details about escaping in the field documentation. 2) field is not required if aggregate is count. type String The type of measurement (\"quantitative\", \"temporal\", \"ordinal\", or \"nominal\") for the encoded field or constant value (datum). It can also be a \"geojson\" type for encoding ‘geoshape’. Vega-Lite automatically infers data types in many cases as discussed below. However, type is required for a field if: (1) the field is not nominal and the field encoding has no specified aggregate (except argmin and argmax), bin, scale type, custom sort order, nor timeUnit or (2) if you wish to use an ordinal scale for a field with bin or timeUnit. Default value: 1) For a data field, \"nominal\" is the default data type unless the field encoding has aggregate, channel, bin, scale type, sort, or timeUnit that satisfies the following criteria: \"quantitative\" is the default type if (1) the encoded field contains bin or aggregate except \"argmin\" and \"argmax\", (2) the encoding channel is latitude or lon", "category": "encoding", "source": "vega-lite" }, { "title": "Type", "url": "https://vega.github.io/vega-lite/docs/type.html", "content": "Vega-Lite Vega Altair Vega-Lite API Examples Tutorials Documentation Usage Ecosystem GitHub Try Online Overview View Specification Title Width / Height Data / Datasets Transform Aggregate Bin Calculate Density Extent Filter Flatten Fold Impute Join Aggregate Loess Lookup Pivot Quantile Regression Sample Stack Time Unit Window Mark Arc Area Bar Box Plot Circle Error Band Error Bar Geoshape Image Line Point Rect Rule Square Text Tick Trail Encoding Aggregate Axis Band Position Bin Condition Datum Field Format Header Impute Legend Scale Stack Sort Time Unit Type Value Projection View Composition Facet Layer Concat Repeat Resolve Parameter Value Expr Bind Select Config Property Types Date Time Gradient Predicate Tooltip Invalid Data Type Edit this page If a field is specified, the channel definition must describe the encoded data’s type based on their level of measurement. The supported data types are: \"quantitative\", \"temporal\", \"ordinal\", \"nominal\", and \"geojson\". Property Type Description type String The type of measurement (\"quantitative\", \"temporal\", \"ordinal\", or \"nominal\") for the encoded field or constant value (datum). It can also be a \"geojson\" type for encoding ‘geoshape’. Vega-Lite automatically infers data types in many cases as discussed below. However, type is required for a field if: (1) the field is not nominal and the field encoding has no specified aggregate (except argmin and argmax), bin, scale type, custom sort order, nor timeUnit or (2) if you wish to use an ordinal scale for a field with bin or timeUnit. Default value: 1) For a data field, \"nominal\" is the default data type unless the field encoding has aggregate, channel, bin, scale type, sort, or timeUnit that satisfies the following criteria: \"quantitative\" is the default type if (1) the encoded field contains bin or aggregate except \"argmin\" and \"argmax\", (2) the encoding channel is latitude or longitude channel or (3) if the specified scale type is a quantitative scale. \"temporal\" is the default type if (1) the encoded field contains timeUnit or (2) the specified scale type is a time or utc scale \"ordinal\" is the default type if (1) the encoded field contains a custom sort order, (2) the specified scale type is an ordinal/point/band scale, or (3) the encoding channel is order. 2) For a constant value in data domain (datum): \"quantitative\" if the datum is a number \"nominal\" if the datum is a string \"temporal\" if the datum is a date time object Note: Data type describes the semantics of the data rather than the primitive data types (number, string, etc.). The same primitive data type can have different types of measurement. For example, numeric data can represent quantitative, ordinal, or nominal data. Data values for a temporal field can be either a date-time string (e.g., \"2015-03-07 12:32:17\", \"17:01\", \"2015-03-16\". \"2015\") or a timestamp number (e.g., 1552199579097). When using with bin, the type property can be either \"quantitative\" (for using a linear bin scale) or \"ordinal\" (for using an ordinal bin scale). When using with timeUnit, the type property can be either \"temporal\" (default, for using a temporal scale) or \"ordinal\" (for using an ordinal scale). When using with aggregate, the type property refers to the post-aggregation data type. For example, we can calculate count distinct of a categorical field \"cat\" using {\"aggregate\": \"distinct\", \"field\": \"cat\"}. The \"type\" of the aggregate output is \"quantitative\". Secondary channels (e.g., x2, y2, xError, yError) do not have type as they must have exactly the same type as their primary channels (e.g., x, y). See also: type documentation. Quantitative Quantitative data expresses some kind of quantity. Typically this is numerical data. For example 7.3, 42.0, 12.1. Quantitative data can represent either the ratio or interval level of measurement. By default, Vega-Lite includes zero values in the x, y, and size scales for quantitative fields, which is more appropriate for ratio data. However, you can manually set the scale’s zero property to false if you have interval data. Temporal Temporal data supports date-times and times such as \"2015-03-07 12:32:17\", \"17:01\", \"2015-03-16\", \"2015\", 1552199579097 (timestamp). Note that when a \"temporal\" type is used for a field, Vega-Lite will treat it as a continuous field and thus will use a time scale to map its data to visual values. For example, the following bar chart shows the mean precipitation for different months. Ordinal Ordinal data represents ranked order (1st, 2nd, …) by which the data can be sorted. However, as opposed to quantitative data, there is no notion of relative degree of difference between them. For illustration, a “size” variable might have the following values small, medium, large, extra-large. We know that medium is larger than small and same for extra-large larger than large. However, we cannot compare the magnitude of relative difference, for example, between (1) small and medium and (2) medium and large. Similarly,", "category": "data-types", "source": "vega-lite" }, { "title": "Scale", "url": "https://vega.github.io/vega-lite/docs/scale.html", "content": "Vega-Lite Vega Altair Vega-Lite API Examples Tutorials Documentation Usage Ecosystem GitHub Try Online Overview View Specification Title Width / Height Data / Datasets Transform Aggregate Bin Calculate Density Extent Filter Flatten Fold Impute Join Aggregate Loess Lookup Pivot Quantile Regression Sample Stack Time Unit Window Mark Arc Area Bar Box Plot Circle Error Band Error Bar Geoshape Image Line Point Rect Rule Square Text Tick Trail Encoding Aggregate Axis Band Position Bin Condition Datum Field Format Header Impute Legend Scale Stack Sort Time Unit Type Value Projection View Composition Facet Layer Concat Repeat Resolve Parameter Value Expr Bind Select Config Property Types Date Time Gradient Predicate Tooltip Invalid Data Scale Edit this page Scales are functions that transform a domain of data values (numbers, dates, strings, etc.) to a range of visual values (pixels, colors, sizes). Internally, Vega-Lite uses Vega scales, which are derived from the d3-scale library. For more background about scales, please see “Introducing d3-scale” by Mike Bostock. Vega-Lite automatically creates scales for fields that are mapped to position and mark property channels. To customize the scale of a field, users can provide a scale object as a part of the field definition to customize scale properties (e.g., type, domain, and range). // A Single View or a Layer Specification { ..., \"mark/layer\": ..., \"encoding\": { \"x\": { \"field\": ..., \"type\": ..., \"scale\": { // scale \"type\": ..., ... }, ... }, \"y\": ..., ... }, ... } Besides the scale property of each encoding channel, the top-level configuration object (config) also provides scale config (config: {scale: {...}}) for setting default scale properties for all scales. For more information about guides that visualize the scales, please see the axes and legends pages. Documentation Overview Scale Types Scale Domains Example: Customizing Domain for a Time Scale Example: Clipping or Removing Unwanted Data Points Example: Using domainRaw to bind domain interactively Scale Ranges Example: Setting Color Range based on a Field Example: Setting Range Min/Max Color Schemes 1. Set a custom scheme. 2. Setting the range property to an array of valid CSS color strings. 3. Change the default color schemes using the range config. Common Scale Properties Continuous Scales Linear Scales Power Scales Square Root Scales Logarithmic Scales Symlog Scales Time and UTC Scales Piecewise and Diverging Scales Discrete Scales Ordinal Scales Band and Point Scales Discretizing Scales Bin-Linear Scales Bin-Ordinal Scales Bins Parameter Quantile Scales Quantize Scales Threshold Scales Disabling Scale Configuration Scale Config Padding Range Scale Output for Invalid Values Other Range Config Scale Types The type property can be specified to customize the scale type. Property Type Description type String The type of scale. Vega-Lite supports the following categories of scale types: 1) Continuous Scales – mapping continuous domains to continuous output ranges (\"linear\", \"pow\", \"sqrt\", \"symlog\", \"log\", \"time\", \"utc\". 2) Discrete Scales – mapping discrete domains to discrete (\"ordinal\") or continuous (\"band\" and \"point\") output ranges. 3) Discretizing Scales – mapping continuous domains to discrete output ranges \"bin-ordinal\", \"quantile\", \"quantize\" and \"threshold\". Default value: please see the scale type table. By default, Vega-Lite use the following scale types for the following data types and encoding channels: Nominal / Ordinal Quantitative Bin-Quantitative1 Temporal X, Y Band / Point2 Linear Linear Time Size, Opacity Point Linear Linear Time Color Ordinal Linear Bin-Ordinal Linear Shape Ordinal N/A N/A N/A 1 Quantitative fields with the bin transform. 2 For positional (x and y) nominal and ordinal fields, \"band\" scale is the default scale type for bar, image, rect, and rule marks while \"point\" is the default scales for all other marks. Scale Domains By default, a scale in Vega-Lite draws domain values directly from a channel’s encoded field. Users can specify the domain property of a scale to customize its domain values. To sort the order of the domain of the encoded, the sort property of a field definition can be specified. Property Type Description domain Null[] | String[] | Number[] | Boolean[] | DateTime[] | ExprRef[] | String | ParameterExtent | DomainUnionWith | ExprRef Customized domain values in the form of constant values or dynamic values driven by a parameter. 1) Constant domain for quantitative fields can take one of the following forms: A two-element array with minimum and maximum values. To create a diverging scale, this two-element array can be combined with the domainMid property. An array with more than two entries, for Piecewise quantitative scales. A string value \"unaggregated\", if the input field is aggregated, to indicate that the domain should include the raw data values prior to the aggregation. 2) Constant domain for temporal fields can be a two-element array with minimum and m", "category": "scales", "source": "vega-lite" }, { "title": "Axis", "url": "https://vega.github.io/vega-lite/docs/axis.html", "content": "Vega-Lite Vega Altair Vega-Lite API Examples Tutorials Documentation Usage Ecosystem GitHub Try Online Overview View Specification Title Width / Height Data / Datasets Transform Aggregate Bin Calculate Density Extent Filter Flatten Fold Impute Join Aggregate Loess Lookup Pivot Quantile Regression Sample Stack Time Unit Window Mark Arc Area Bar Box Plot Circle Error Band Error Bar Geoshape Image Line Point Rect Rule Square Text Tick Trail Encoding Aggregate Axis Band Position Bin Condition Datum Field Format Header Impute Legend Scale Stack Sort Time Unit Type Value Projection View Composition Facet Layer Concat Repeat Resolve Parameter Value Expr Bind Select Config Property Types Date Time Gradient Predicate Tooltip Invalid Data Axis Edit this page Axes provide axis lines, ticks, and labels to convey how a positional range represents a data range. Simply put, axes visualize scales. By default, Vega-Lite automatically creates axes with default properties for x and y channels when they encode data fields. User can set the axis property of x- or y-field definition to an object to customize axis properties or set axis to null to remove the axis. Besides axis property of a field definition, the configuration object (config) also provides axis config (config: {axis: {...}}) for setting default axis properties for all axes. Documentation Overview Axis Properties General Example: Using Axis minExtent to Align Multi-View Plots Domain Labels Example: Using Axis labelExpr to Display Initial Letters of Month Name Ticks Example: Using Axis tickBand to Show Grid Between Marks Title Example: Customize Title Grid Conditional Axis Properties Example: Conditional Axis Properties and Multi-Line Axis Label Axis Config Axis Properties // A Single View or a Layer Specification { ..., \"mark/layer\": ..., \"encoding\": { \"x\": { \"field\": ..., \"type\": ..., \"axis\": { // Axis ... }, ... }, \"y\": ..., ... } } To customize axis, you can specify an axis object in an encoding channel’s definition. This section lists all properties of axes. See also: This interactive article demonstrates axes and legends in the underlying Vega language. General Property Type Description aria Boolean | ExprRef A boolean flag indicating if ARIA attributes should be included (SVG output only). If false, the “aria-hidden” attribute will be set on the output SVG group, removing the axis from the ARIA accessibility tree. Default value: true bandPosition Number | ExprRef An interpolation fraction indicating where, for band scales, axis ticks should be positioned. A value of 0 places ticks at the left edge of their bands. A value of 0.5 places ticks in the middle of their bands. Default value: 0.5 description String | ExprRef A text description of this axis for ARIA accessibility (SVG output only). If the aria property is true, for SVG output the “aria-label” attribute will be set to this description. If the description is unspecified it will be automatically generated. maxExtent Number | ExprRef The maximum extent in pixels that axis ticks and labels should use. This determines a maximum offset value for axis titles. Default value: undefined. minExtent Number | ExprRef The minimum extent in pixels that axis ticks and labels should use. This determines a minimum offset value for axis titles. Default value: 30 for y-axis; undefined for x-axis. orient String | ExprRef The orientation of the axis. One of \"top\", \"bottom\", \"left\" or \"right\". The orientation can be used to further specialize the axis type (e.g., a y-axis oriented towards the right edge of the chart). Default value: \"bottom\" for x-axes and \"left\" for y-axes. offset Number | ExprRef The offset, in pixels, by which to displace the axis from the edge of the enclosing group or data rectangle. Default value: derived from the axis config’s offset (0 by default) position Number | ExprRef The anchor position of the axis in pixels. For x-axes with top or bottom orientation, this sets the axis group x coordinate. For y-axes with left or right orientation, this sets the axis group y coordinate. Default value: 0 style String | String[] A string or array of strings indicating the name of custom styles to apply to the axis. A style is a named collection of axis property defined within the style configuration. If style is an array, later styles will override earlier styles. Default value: (none) Note: Any specified style will augment the default style. For example, an x-axis mark with \"style\": \"foo\" will use config.axisX and config.style.foo (the specified style \"foo\" has higher precedence). translate Number | ExprRef Coordinate space translation offset for axis layout. By default, axes are translated by a 0.5 pixel offset for both the x and y coordinates in order to align stroked lines with the pixel grid. However, for vector graphics output these pixel-specific adjustments may be undesirable, in which case translate can be changed (for example, to zero). Default value: 0.5 zindex Number A non-negative integer indicating ", "category": "axes", "source": "vega-lite" }, { "title": "Legend", "url": "https://vega.github.io/vega-lite/docs/legend.html", "content": "Vega-Lite Vega Altair Vega-Lite API Examples Tutorials Documentation Usage Ecosystem GitHub Try Online Overview View Specification Title Width / Height Data / Datasets Transform Aggregate Bin Calculate Density Extent Filter Flatten Fold Impute Join Aggregate Loess Lookup Pivot Quantile Regression Sample Stack Time Unit Window Mark Arc Area Bar Box Plot Circle Error Band Error Bar Geoshape Image Line Point Rect Rule Square Text Tick Trail Encoding Aggregate Axis Band Position Bin Condition Datum Field Format Header Impute Legend Scale Stack Sort Time Unit Type Value Projection View Composition Facet Layer Concat Repeat Resolve Parameter Value Expr Bind Select Config Property Types Date Time Gradient Predicate Tooltip Invalid Data Legend Edit this page Similar to axes, legends visualize scales. However, whereas axes aid interpretation of scales with positional ranges, legends aid interpretation of scales with ranges such as colors, shapes and sizes. By default, Vega-Lite automatically creates legends with default properties for color, opacity, size, and shape channels when they encode data fields. User can set the legend property of a mark property channel’s field definition to an object to customize legend properties or set legend to null to remove the legend. Besides legend property of a field definition, the configuration object (config) also provides legend config (config: {legend: {...}}) for setting default legend properties for all legends. Legend Types Combined Legend Legend Properties General Gradient Labels Symbols Symbol Layout Title Legend Config Legend Types By default, Vega-Lite automatically generates gradient legends for color channels with non-binned quantitative fields and temporal fields. Otherwise, symbol legends are generated. Combined Legend If multiple channels encode the same fields, Vega-Lite automatically combines their legends. For example, the following plot uses both color and shape to encode Origin; as a result, its legend shows the encoded colors and shapes. Legend Properties // A Single View or a Layer Specification { ..., \"mark/layer\": ..., \"encoding\": { \"x\": ..., \"y\": ..., \"color\": { \"field\": ..., \"type\": ..., \"legend\": { // legend ... }, ... }, ... } } To customize legends, you can specify a legend object in an encoding channel’s definition. This section lists all properties of legends. See also: This interactive article demonstrates axes and legends in the underlying Vega language. General Property Type Description aria Boolean | ExprRef A boolean flag indicating if ARIA attributes should be included (SVG output only). If false, the “aria-hidden” attribute will be set on the output SVG group, removing the legend from the ARIA accessibility tree. Default value: true cornerRadius Number | ExprRef Corner radius for the full legend. description String | ExprRef A text description of this legend for ARIA accessibility (SVG output only). If the aria property is true, for SVG output the “aria-label” attribute will be set to this description. If the description is unspecified it will be automatically generated. direction String The direction of the legend, one of \"vertical\" or \"horizontal\". Default value: For top-/bottom-oriented legends, \"horizontal\" For left-/right-oriented legends, \"vertical\" For top/bottom-left/right-oriented legends, \"horizontal\" for gradient legends and \"vertical\" for symbol legends. fillColor Null | Color | ExprRef Background fill color for the full legend. legendX Number | ExprRef Custom x-position for legend with orient “none”. legendY Number | ExprRef Custom y-position for legend with orient “none”. offset Number | ExprRef The offset in pixels by which to displace the legend from the data rectangle and axes. Default value: 18. orient String The orientation of the legend, which determines how the legend is positioned within the scene. One of \"left\", \"right\", \"top\", \"bottom\", \"top-left\", \"top-right\", \"bottom-left\", \"bottom-right\", \"none\". Default value: \"right\" padding Number | ExprRef The padding between the border and content of the legend group. Default value: 0. strokeColor Null | Color | ExprRef Border stroke color for the full legend. type String The type of the legend. Use \"symbol\" to create a discrete legend and \"gradient\" for a continuous color gradient. Default value: \"gradient\" for non-binned quantitative fields and temporal fields; \"symbol\" otherwise. tickCount TickCount | ExprRef The desired number of tick values for quantitative legends. values Number[] | String[] | Boolean[] | DateTime[] | ExprRef Explicitly set the visible legend values. zindex Number A non-negative integer indicating the z-index of the legend. If zindex is 0, legend should be drawn behind all chart elements. To put them in front, use zindex = 1. Gradient Property Type Description gradientLength Number | ExprRef The length in pixels of the primary axis of a color gradient. This value corresponds to the height of a vertical gradient or the width of a horizontal gradient. Defa", "category": "legends", "source": "vega-lite" }, { "title": "Transformation", "url": "https://vega.github.io/vega-lite/docs/transform.html", "content": "Vega-Lite Vega Altair Vega-Lite API Examples Tutorials Documentation Usage Ecosystem GitHub Try Online Overview View Specification Title Width / Height Data / Datasets Transform Aggregate Bin Calculate Density Extent Filter Flatten Fold Impute Join Aggregate Loess Lookup Pivot Quantile Regression Sample Stack Time Unit Window Mark Arc Area Bar Box Plot Circle Error Band Error Bar Geoshape Image Line Point Rect Rule Square Text Tick Trail Encoding Aggregate Axis Band Position Bin Condition Datum Field Format Header Impute Legend Scale Stack Sort Time Unit Type Value Projection View Composition Facet Layer Concat Repeat Resolve Parameter Value Expr Bind Select Config Property Types Date Time Gradient Predicate Tooltip Invalid Data Transformation Edit this page Data transformations in Vega-Lite are described via either view-level transforms (the transform property) or field transforms inside encoding (bin, timeUnit, aggregate, sort, and stack). When both types of transforms are specified, the view-level transforms are executed first based on the order in the array. Then the inline transforms are executed in this order: bin, timeUnit, aggregate, sort, and stack. View-level Transform Property { \"data\": ... , \"transform\": [ ... ], \"mark\": ... , \"encoding\": ... , ... } The View-level transform object is an array of objects describing transformations. The transformations are executed in the order in which they are specified in the array. Vega-Lite’s transform supports the following types of transformations: Aggregate Bin Calculate Density Extent Filter Flatten Fold Impute Join Aggregate Lookup Pivot Quantile Regression and Loess Regression Sample Stack Time Unit Window Edit this page and submit a pull request!", "category": "transforms", "source": "vega-lite" }, { "title": "Aggregation", "url": "https://vega.github.io/vega-lite/docs/aggregate.html", "content": "Vega-Lite Vega Altair Vega-Lite API Examples Tutorials Documentation Usage Ecosystem GitHub Try Online Overview View Specification Title Width / Height Data / Datasets Transform Aggregate Bin Calculate Density Extent Filter Flatten Fold Impute Join Aggregate Loess Lookup Pivot Quantile Regression Sample Stack Time Unit Window Mark Arc Area Bar Box Plot Circle Error Band Error Bar Geoshape Image Line Point Rect Rule Square Text Tick Trail Encoding Aggregate Axis Band Position Bin Condition Datum Field Format Header Impute Legend Scale Stack Sort Time Unit Type Value Projection View Composition Facet Layer Concat Repeat Resolve Parameter Value Expr Bind Select Config Property Types Date Time Gradient Predicate Tooltip Invalid Data Aggregation Edit this page To aggregate data in Vega-Lite, users can either use the aggregate property of an encoding field definition or the aggregate transform inside the transform array. Aggregate summarizes a table as one record for each group. To preserve the original table structure and instead add a new column with the aggregate values, use the join aggregate transform. Documentation Overview Aggregate in Encoding Field Definition Aggregate Transform Aggregated Field Definition for Aggregate Transform Supported Aggregation Operations Argmin / Argmax Example: Labeling Line Chart Aggregate in Encoding Field Definition // A Single View or a Layer Specification { ..., \"mark/layer\": ..., \"encoding\": { \"x\": { \"aggregate\": ..., // aggregate \"field\": ..., \"type\": \"quantitative\", ... }, \"y\": ..., ... }, ... } The aggregate property of a field definition can be used to compute aggregate summary statistics (e.g., median, min, max) over groups of data. If at least one fields in the specified encoding channels contain aggregate, the resulting visualization will show aggregate data. In this case, all fields without aggregation function specified are treated as group-by fields1 in the aggregation process. For example, the following bar chart aggregates mean of Acceleration, grouped by the number of Cylinders. Note: aggregated fields are quantitative by default while unaggregated (group by) fields in aggregated encodings are nominal by default. The detail channel can be used to specify additional summary and group-by fields without mapping the field(s) to any visual properties. For example, the following plots add Origin as a group by field. 1The group-by fields are also known as independent/condition variables in statistics and dimensions in Business Intelligence. Similarly, the aggregate fields are known as dependent variables and measures. Aggregate Transform // Any View Specification { ... \"transform\": [ { // Aggregate Transform \"aggregate\": [{\"op\": ..., \"field\": ..., \"as\": ...}], \"groupby\": [...] } ... ], ... } For example, here is the same bar chart which aggregates mean of Acceleration, grouped by the number of Cylinders, but this time using the aggregate property as part of the transform. An aggregate transform in the transform array has the following properties: Property Type Description aggregate AggregatedFieldDef[] Required. Array of objects that define fields to aggregate. groupby String[] The data fields to group by. If not specified, a single group containing all data objects will be used. Aggregated Field Definition for Aggregate Transform Property Type Description op String Required. The aggregation operation to apply to the fields (e.g., \"sum\", \"average\", or \"count\"). See the full list of supported aggregation operations for more information. field String The data field for which to compute aggregate function. This is required for all aggregation operations except \"count\". as String Required. The output field names to use for each aggregated field. Note: It is important you parse your data types explicitly, especially if you are likely to have null values in your dataset and automatic type inference will fail. Supported Aggregation Operations The supported aggregation operations are: Operation Description count The total count of data objects in the group. Note: ‘count’ operates directly on the input objects and return the same value regardless of the provided field. valid The count of field values that are not null, undefined or NaN. values A list of data objects in the group. missing The count of null or undefined field values. distinct The count of distinct field values. sum The sum of field values. product The product of field values. mean The mean (average) field value. average The mean (average) field value. Identical to mean. variance The sample variance of field values. variancep The population variance of field values. stdev The sample standard deviation of field values. stdevp The population standard deviation of field values. stderr The standard error of field values. median The median field value. q1 The lower quartile boundary of field values. q3 The upper quartile boundary of field values. ci0 The lower boundary of the bootstrapped 95% confidence interval of t", "category": "transforms", "source": "vega-lite" }, { "title": "Binning", "url": "https://vega.github.io/vega-lite/docs/bin.html", "content": "Vega-Lite Vega Altair Vega-Lite API Examples Tutorials Documentation Usage Ecosystem GitHub Try Online Overview View Specification Title Width / Height Data / Datasets Transform Aggregate Bin Calculate Density Extent Filter Flatten Fold Impute Join Aggregate Loess Lookup Pivot Quantile Regression Sample Stack Time Unit Window Mark Arc Area Bar Box Plot Circle Error Band Error Bar Geoshape Image Line Point Rect Rule Square Text Tick Trail Encoding Aggregate Axis Band Position Bin Condition Datum Field Format Header Impute Legend Scale Stack Sort Time Unit Type Value Projection View Composition Facet Layer Concat Repeat Resolve Parameter Value Expr Bind Select Config Property Types Date Time Gradient Predicate Tooltip Invalid Data Binning Edit this page Binning discretizes numeric values into a set of bins. A common use case is to create a histogram. There are two ways to define binning in Vega-Lite: the bin property in encoding field definitions and the bin transform. Documentation Overview Binning in Encoding Field Definition Example: Histogram Example: Histogram with Ordinal Scale Example: Binned color Example: Using Vega-Lite with Binned data Bin Transform Example: Histogram with Bin Transform Bin Parameters Example: Customizing Max Bins Ordinal Bin Binning in Encoding Field Definition // A Single View or a Layer Specification { ..., \"mark/layer\": ..., \"encoding\": { \"x\": { \"bin\": ..., // bin \"field\": ..., \"type\": \"quantitative\", ... }, \"y\": ..., ... }, ... } You can directly bin an encoding field by using the bin property in a field definition. Property Type Description bin Boolean | BinParams | String | Null A flag for binning a quantitative field, an object defining binning parameters, or indicating that the data for x or y channel are binned before they are imported into Vega-Lite (\"binned\"). If true, default binning parameters will be applied. If \"binned\", this indicates that the data for the x (or y) channel are already binned. You can map the bin-start field to x (or y) and the bin-end field to x2 (or y2). The scale and axis will be formatted similar to binning in Vega-Lite. To adjust the axis ticks based on the bin step, you can also set the axis’s tickMinStep property. Default value: false See also: bin documentation. Example: Histogram Mapping binned values and its count to a bar mark produces a histogram. Example: Histogram with Ordinal Scale While binned field has \"quantitative\" type by default, setting the binned field’s type to \"ordinal\" produces a histogram with an ordinal scale. Example: Binned color You can use binning to discretize color scales. Vega-Lite automatically creates legends with range labels. Example: Using Vega-Lite with Binned data If you have data that is already binned outside of Vega-Lite, setting the bin property to \"binned\" will trigger Vega-Lite to render scales and axes similar to setting the bin property in encoding field definitions. Note that you have to specify field names that encode the start and end of each bin. To adjust the axis ticks based on the bin step, you can set bin to e.g. {\"binned\": true, \"step\": 2}. Bin Transform // Any View Specification { ... \"transform\": [ {\"bin\": ..., \"field\": ..., \"as\" ...} // Bin Transform ... ], ... } The bin transform in the transform array has the following properties: Property Type Description bin Boolean | BinParams Required. An object indicating bin properties, or simply true for using default bin parameters. field String Required. The data field to bin. as String | String[] Required. The output fields at which to write the start and end bin values. This can be either a string or an array of strings with two elements denoting the name for the fields for bin start and bin end respectively. If a single string (e.g., \"val\") is provided, the end field will be \"val_end\". Example: Histogram with Bin Transform Instead of using the bin property of a field definition, you can also use a bin transform to derive a new field (e.g., bin_IMDB_Rating), and encode the new field with bin property of a field definition set to binned instead. While binning in transform is more verbose than in encoding, it can be useful if you want to perform additional calculation before encoding the data. Bin Parameters If bin is true, default binning properties are used. To customize binning properties, you can set bin to a bin definition object, which can have the following properties: Property Type Description anchor Number A value in the binned domain at which to anchor the bins, shifting the bin boundaries if necessary to ensure that a boundary aligns with the anchor value. Default value: the minimum bin extent value base Number The number base to use for automatic bin determination (default is base 10). Default value: 10 divide Number[] Scale factors indicating allowable subdivisions. The default value is [5, 2], which indicates that for base 10 numbers (the default base), the method may consider dividing bin sizes by 5 and/or 2. For example, for an ", "category": "transforms", "source": "vega-lite" }, { "title": "Time Unit", "url": "https://vega.github.io/vega-lite/docs/timeunit.html", "content": "Vega-Lite Vega Altair Vega-Lite API Examples Tutorials Documentation Usage Ecosystem GitHub Try Online Overview View Specification Title Width / Height Data / Datasets Transform Aggregate Bin Calculate Density Extent Filter Flatten Fold Impute Join Aggregate Loess Lookup Pivot Quantile Regression Sample Stack Time Unit Window Mark Arc Area Bar Box Plot Circle Error Band Error Bar Geoshape Image Line Point Rect Rule Square Text Tick Trail Encoding Aggregate Axis Band Position Bin Condition Datum Field Format Header Impute Legend Scale Stack Sort Time Unit Type Value Projection View Composition Facet Layer Concat Repeat Resolve Parameter Value Expr Bind Select Config Property Types Date Time Gradient Predicate Tooltip Invalid Data Time Unit Edit this page Time unit is used to discretize times in Vega-Lite. It can be used (1) with the timeUnit property of encoding field definitions, (2) as a standalone transform, or (3) with the timeUnit property of a field predicate. Vega-Lite supports the following time units: \"year\" - Gregorian calendar years. \"quarter\" - Three-month intervals, starting in one of January, April, July, and October. \"month\" - Calendar months (January, February, etc.). \"date\" - Calendar day of the month (January 1, January 2, etc.). \"week\" - Sunday-based weeks. Days before the first Sunday of the year are considered to be in week 0, the first Sunday of the year is the start of week 1, the second Sunday week 2, etc.. \"day\" - Day of the week (Sunday, Monday, etc.). \"dayofyear\" - Day of the year (1, 2, …, 365, etc.). \"hours\" - Hours of the day (12:00am, 1:00am, etc.). \"minutes\" - Minutes in an hour (12:00, 12:01, etc.). \"seconds\" - Seconds in a minute (12:00:00, 12:00:01, etc.). \"milliseconds\" - Milliseconds in a second. Vega-Lite time units can also be a string of consecutive time units to indicate desired intervals of time. For example, yearmonthdate indicates chronological time sensitive to year, month, and date (but not to hours, minutes, or seconds). The specifier monthdate is sensitive to month and date, but not year, which can be useful for binning time values to look at seasonal patterns only. By default, all time units represent date time using local time. To use UTC time, you can add the utc prefix (e.g., \"utcyear\", \"utcyearmonth\"). For timeUnit in encoding, you can also add \"binned\" prefix (e.g., \"binnedyearmonth\" or \"binnedutcyearmonth\") for Chronological time units (i.e., units that are truncated date times, as opposed to circle time units, which bin data to parts of date times). Documentation Overview Time Unit in Encoding Field Definition Time Unit’s Band Time Unit with Ordinal Fields Time Unit Transform UTC time Input Output Time Unit Parameters Example: Customizing Step Time Unit in Encoding Field Definition // A Single View or a Layer Specification { ..., \"mark/layer\": ..., \"encoding\": { \"x\": { \"timeUnit\": ..., // time unit \"field\": ..., \"type\": \"temporal\", ... }, \"y\": ..., ... }, ... } A field definition can include a timeUnit property. For example, the chart below shows temperature in Seattle aggregated by month. Using timeUnit with rect-based marks (including bar, rect, and image) will treat time units as intervals. You can also add \"binned\" prefix if your data has already been binned and want Vega-Lite to apply the right formatting, including the right bands for the interval, to your charts. By default, bar marks are placed from the beginning of a time interval (e.g., “month”) to the end of the interval. Setting bandPosition to 0 moves the bar to center-align with ticks. Time Unit’s Band By default, Vega-Lite encodes fields with timeUnit using the initial position of a time unit (which is equivalent to having band = 0). However, one can set the band property to be 0.5 to use place each data point in the middle of each time unit band. Time Unit with Ordinal Fields By default, fields with time units have “temporal” type and thus use time scales. However, time units can be also used with a discrete scale. For example, you can cast the field to have an \"ordinal\" type. Time Unit Transform // Any View Specification { ..., \"transform\": [ {\"timeUnit\": ..., \"field\": ..., \"as\": ...} // TimeUnit Transform ... ], ... } A timeUnit transform in the transform array has the following properties: Property Type Description timeUnit TimeUnit | TimeUnitTransformParams Required. The timeUnit. field String Required. The data field to apply time unit. as String Required. The output field to write the timeUnit value. In the example below, we use the time unit transform to extract the month component of the dates. We can then visualize the hottest temperature. Note that Vega-Lite will not automatically format the axis if the timeUnit is applied outside encoding so we have to format it manually. For this reason, you should prefer time units as part of encoding definitions. UTC time Input To parse data in local time or UTC time, there are three cases: Times are parsed as UTC time if the date strings a", "category": "transforms", "source": "vega-lite" }, { "title": "Filter Transform", "url": "https://vega.github.io/vega-lite/docs/filter.html", "content": "Vega-Lite Vega Altair Vega-Lite API Examples Tutorials Documentation Usage Ecosystem GitHub Try Online Overview View Specification Title Width / Height Data / Datasets Transform Aggregate Bin Calculate Density Extent Filter Flatten Fold Impute Join Aggregate Loess Lookup Pivot Quantile Regression Sample Stack Time Unit Window Mark Arc Area Bar Box Plot Circle Error Band Error Bar Geoshape Image Line Point Rect Rule Square Text Tick Trail Encoding Aggregate Axis Band Position Bin Condition Datum Field Format Header Impute Legend Scale Stack Sort Time Unit Type Value Projection View Composition Facet Layer Concat Repeat Resolve Parameter Value Expr Bind Select Config Property Types Date Time Gradient Predicate Tooltip Invalid Data Filter Transform Edit this page The filter transform removes objects from a data stream based on a provided filter expression or filter object. // Any View Specification { ... \"transform\": [ {\"filter\": ...} // Filter Transform ... ], ... } Vega-Lite filter transforms must have the filter property describing the predicate for the filtering condition. Property Type Description filter Predicate Required. The filter property must be a predication definition, which can take one of the following forms: 1) an expression string, where datum can be used to refer to the current data object. For example, {filter: \"datum.b2 > 60\"} would make the output data includes only items that have values in the field b2 over 60. 2) one of the field predicates: equal, lt, lte, gt, gte, range, oneOf, or valid, 3) a selection predicate, which define the names of a selection that the data point should belong to (or a logical composition of selections). 4) a logical composition of (1), (2), or (3). Edit this page and submit a pull request!", "category": "transforms", "source": "vega-lite" }, { "title": "Selection Parameters", "url": "https://vega.github.io/vega-lite/docs/selection.html", "content": "Vega-Lite Vega Altair Vega-Lite API Examples Tutorials Documentation Usage Ecosystem GitHub Try Online Overview View Specification Title Width / Height Data / Datasets Transform Aggregate Bin Calculate Density Extent Filter Flatten Fold Impute Join Aggregate Loess Lookup Pivot Quantile Regression Sample Stack Time Unit Window Mark Arc Area Bar Box Plot Circle Error Band Error Bar Geoshape Image Line Point Rect Rule Square Text Tick Trail Encoding Aggregate Axis Band Position Bin Condition Datum Field Format Header Impute Legend Scale Stack Sort Time Unit Type Value Projection View Composition Facet Layer Concat Repeat Resolve Parameter Value Expr Bind Select Config Property Types Date Time Gradient Predicate Tooltip Invalid Data Selection Parameters Edit this page // A Single View Specification { ..., \"params\": [ // An array of named parameters. { \"name\": ..., \"select\": { // Selection \"type\": ..., ... } } ], \"mark\": ..., \"encoding\": ..., ... } Selection parameters define data queries that are driven by direct manipulation user input (e.g., mouse clicks or drags). A parameter becomes a selection when the select property is specified. This page discusses different properties of a selection. Documentation Overview Common Selection Properties type Selection Projection with encodings and fields Current Limitations on clear resolve Point Selection Properties toggle Nearest Current Limitations Interval Selection Properties mark translate zoom Common Selection Properties For both selection types, the select object can take the following properties: Property Type Description type String Required. Determines the default event processing and data query for the selection. Vega-Lite currently supports two selection types: \"point\" – to select multiple discrete data values; the first value is selected on click and additional values toggled on shift-click. \"interval\" – to select a continuous range of data values on drag. encodings String[] An array of encoding channels. The corresponding data field values must match for a data tuple to fall within the selection. See also: The projection with encodings and fields section in the documentation. fields String[] An array of field names whose values must match for a data tuple to fall within the selection. See also: The projection with encodings and fields section in the documentation. on VegaEventStream | String A Vega event stream (object or selector) that triggers the selection. For interval selections, the event stream must specify a start and end. See also: on examples in the documentation. clear VegaEventStream | String | Boolean Clears the selection, emptying it of all values. This property can be a Event Stream or false to disable clear. Default value: dblclick. See also: clear examples in the documentation. resolve String With layered and multi-view displays, a strategy that determines how selections’ data queries are resolved when applied in a filter transform, conditional encoding rule, or scale domain. One of: \"global\" – only one brush exists for the entire SPLOM. When the user begins to drag, any previous brushes are cleared, and a new one is constructed. \"union\" – each cell contains its own brush, and points are highlighted if they lie within any of these individual brushes. \"intersect\" – each cell contains its own brush, and points are highlighted only if they fall within all of these individual brushes. Default value: global. See also: resolve examples in the documentation. type A selection’s type determines which data values fall within it by default: For point selections, only values that have been directly interacted with (e.g., those that have been clicked on) are considered to be “selected.” For interval selections, values that fall within both the horizontal (x) and vertical (y) extents are considered to be “selected.” Selection Projection with encodings and fields In the scatterplot example below, highlight multiplea single: Cylinder(s) Origin(s). With interval selections, we can use the projection to restrict the region to just the horizontal (x) and/or vertical (y) dimensions. Current Limitations Selections projected over aggregated fields/encodings can only be used within the same view they are defined in. Interval selections can only be projected using encodings. Interval selections projected over binned or timeUnit fields remain continuous selections. Thus, if the visual encoding discretizes them, conditional encodings will no longer work. Instead, use a layered view as shown in the example below. The bar mark discretizes the binned Acceleration field. As a result, to highlight selected bars, we use a second layered view rather than a conditional color encoding within the same view. function buildProjection(id) { buildSpecOpts(id, 'selection_project_'); } on The on property modifies the event that triggers the selection. For instance, a single rectangle in the heatmap below can now be selected on mouse hover instead. clear The clear property identifie", "category": "interaction", "source": "vega-lite" }, { "title": "Condition", "url": "https://vega.github.io/vega-lite/docs/condition.html", "content": "Vega-Lite Vega Altair Vega-Lite API Examples Tutorials Documentation Usage Ecosystem GitHub Try Online Overview View Specification Title Width / Height Data / Datasets Transform Aggregate Bin Calculate Density Extent Filter Flatten Fold Impute Join Aggregate Loess Lookup Pivot Quantile Regression Sample Stack Time Unit Window Mark Arc Area Bar Box Plot Circle Error Band Error Bar Geoshape Image Line Point Rect Rule Square Text Tick Trail Encoding Aggregate Axis Band Position Bin Condition Datum Field Format Header Impute Legend Scale Stack Sort Time Unit Type Value Projection View Composition Facet Layer Concat Repeat Resolve Parameter Value Expr Bind Select Config Property Types Date Time Gradient Predicate Tooltip Invalid Data Condition Edit this page // A Single View or a Layer Specification { ..., \"mark/layer\": ..., \"encoding\": { ...: { // Conditional encoding channel definition (if-clause) \"condition\": { // Parameter name or a test predicate \"param/test\": ..., // Field / value definition if the data is included in the `param` or if the `test` predicate is satisfied \"field/value\": ..., ... }, // (Optional else-clause) Field / value definition if the data is NOT included in the `param` / if the `test` predicate is NOT satisfied \"field/value\": ..., ... }, ... }, ... } For mark property channels as well as text and tooltip channels, the condition property of their channel definitions can be used to determine encoding rules based on whether data values satisfy a parameter (e.g. fall withing a selection parameter) or satisfy a test predicate. There are two ways to specify the condition: (1) Specifying param name: Property Type Description param String Required. Filter using a parameter name. empty Boolean For selection parameters, the predicate of empty selections returns true by default. Override this behavior, by setting this property empty: false. (2) Specifying a test predicate: Property Type Description test Predicate Required. Predicate for triggering the condition In addition, there are two ways to encode the data that satisfy the specified condition: Combining one conditional field definition with a single base value or datum definition. Combining one or more conditional datum or value definitions with a field, datum, or value definition. Conditional Field Definition // A Single View or a Layer Specification { ..., \"mark/layer\": ..., \"encoding\": { ...: { // A conditional field definition (if-clause) \"condition\": { // Parameter name or a test predicate \"param/test\": ..., // Field if the data is included in the `param` or if the `test` predicate is satisfied \"field\": ..., \"type\": ..., ... }, // (Optional else-clause) value if the data is NOT included in the `param` / if the `test` predicate is NOT satisfied \"value/datum\": ... }, ... }, ... } A conditional field definition uses a data-driven encoding rule when marks satisfy a parameter (e.g. fall within a selection parameter) or satisfy a logical predicate. A value definition can be specified as the “else” case when the condition is not satisfied otherwise. A condition field definition must contain either a param name or a test predicate in addition to the encoded field name and its data type like a typical field definition. In addition, a condition field definition may contain other encoding properties including transformation functions (aggregate, bin, timeUnit) as well as scale and legend (for mark property channels) or format (for text and tooltip channels). For example, in the following plot, the color of rect marks is driven by a conditional field definition. Drag an interval selection and observe that marks are colored based on their aggregated count if they lie within the interval, and are grey otherwise. Note: When using a conditional field definition, only value or datum may be specified as the else (outer) branch. Conditional Value Definition // A Single View or a Layer Specification { ..., \"mark/layer\": ..., \"encoding\": { ...: { // A conditional value definition (if-clause) \"condition\": { // Parameter name or a test predicate \"param/test\": ..., // Value if the data is included in the `param` or if the `test` predicate is satisfied \"value/datum\": ... }, // (Optional else-clause) field if the data is NOT included in the `param` / if the `test` predicate is NOT satisfied \"field\": ... , \"type\": ..., ... }, ... }, ... } Condition value definitions and conditional datum definitions use a constant value encoding when data satisfy a parameter (e.g. fall withing a selection parameter) or satisfy a logical predicate. Another field, datum, or value definition can be specified as the “else” case when the condition is not satisfied. A condition value/datum definition must contain either a param name or a test predicate in addition to the encoded constant value or constant data value (datum). For example, in the visualization below, a conditional value definition causes marks that fall within a dragged interval to be larger than those that lie outside it.", "category": "interaction", "source": "vega-lite" }, { "title": "Layering views", "url": "https://vega.github.io/vega-lite/docs/layer.html", "content": "Vega-Lite Vega Altair Vega-Lite API Examples Tutorials Documentation Usage Ecosystem GitHub Try Online Overview View Specification Title Width / Height Data / Datasets Transform Aggregate Bin Calculate Density Extent Filter Flatten Fold Impute Join Aggregate Loess Lookup Pivot Quantile Regression Sample Stack Time Unit Window Mark Arc Area Bar Box Plot Circle Error Band Error Bar Geoshape Image Line Point Rect Rule Square Text Tick Trail Encoding Aggregate Axis Band Position Bin Condition Datum Field Format Header Impute Legend Scale Stack Sort Time Unit Type Value Projection View Composition Facet Layer Concat Repeat Resolve Parameter Value Expr Bind Select Config Property Types Date Time Gradient Predicate Tooltip Invalid Data Layering views Edit this page Sometimes, it’s useful to superimpose one chart on top of another. You can accomplish this by using the layer operator. This operator is one of Vega-Lite’s view composition operators. To define a layered chart, put multiple specifications into an array under the layer property. { \"layer\": [ ... // Single or layered view specifications ] } In addition to common properties of a view specification, a layer specification has the following properties: Property Type Description layer LayerSpec[] | UnitSpec[] Required. Layer or single view specifications to be layered. Note: Specifications inside layer cannot use row and column channels as layering facet specifications is not allowed. Instead, use the facet operator and place a layer inside a facet. width Number | String | Object The width of a visualization. For a plot with a continuous x-field, width should be a number. For a plot with either a discrete x-field or no x-field, width can be either a number indicating a fixed width or an object in the form of {step: number} defining the width per discrete step. (No x-field is equivalent to having one discrete step.) To enable responsive sizing on width, it should be set to \"container\". Default value: Based on config.view.continuousWidth for a plot with a continuous x-field and config.view.discreteWidth otherwise. Note: For plots with row and column channels, this represents the width of a single view and the \"container\" option cannot be used. See also: width documentation. height Number | String | Object The height of a visualization. For a plot with a continuous y-field, height should be a number. For a plot with either a discrete y-field or no y-field, height can be either a number indicating a fixed height or an object in the form of {step: number} defining the height per discrete step. (No y-field is equivalent to having one discrete step.) To enable responsive sizing on height, it should be set to \"container\". Default value: Based on config.view.continuousHeight for a plot with a continuous y-field and config.view.discreteHeight otherwise. Note: For plots with row and column channels, this represents the height of a single view and the \"container\" option cannot be used. See also: height documentation. view ViewBackground An object defining the view background’s fill and stroke. Default value: none (transparent) encoding SharedEncoding A shared key-value mapping between encoding channels and definition of fields in the underlying layers. projection Projection An object defining properties of the geographic projection shared by underlying layers. resolve Resolve Scale, axis, and legend resolutions for view composition specifications. Please note that you can only layer single or layered views to guarantee that the combined views have a compatible layout. For instance, it is not clear how a composed view with two views side-by-side could be layered on top of a single view. Example A layered chart consistent of multiple charts that are drawn on top of each other. We will start by creating specifications for the individual layers and eventually combine them in a single layer spec. The first chart is a line chart that shows the stock price of different stocks over time. The second chart shows the mean price of individual stocks with a rule mark. The rule mark is a special mark that can span the whole width/height of a single view specification. To layer these two charts on top of each other, we have to put the two specifications in the same layer array. Note that we can leave data at the top level as both layers use the same data. See the example gallery for more layering examples. Combined Scales and Guides When you have different scales in different layers, the scale domains are unioned so that all layers can use the same scale. In the example above, Vega-Lite automatically uses a common y-axis and color legend. We can disable this by setting the resolve property. The default resolutions for layer are shared scales, axes, and legends. In the chart below, we set the y-scales of the different layers to be independent with \"resolve\": {\"scale\": {\"y\": \"independent\"}}. Edit this page and submit a pull request!", "category": "composition", "source": "vega-lite" }, { "title": "Concatenating views", "url": "https://vega.github.io/vega-lite/docs/concat.html", "content": "Vega-Lite Vega Altair Vega-Lite API Examples Tutorials Documentation Usage Ecosystem GitHub Try Online Overview View Specification Title Width / Height Data / Datasets Transform Aggregate Bin Calculate Density Extent Filter Flatten Fold Impute Join Aggregate Loess Lookup Pivot Quantile Regression Sample Stack Time Unit Window Mark Arc Area Bar Box Plot Circle Error Band Error Bar Geoshape Image Line Point Rect Rule Square Text Tick Trail Encoding Aggregate Axis Band Position Bin Condition Datum Field Format Header Impute Legend Scale Stack Sort Time Unit Type Value Projection View Composition Facet Layer Concat Repeat Resolve Parameter Value Expr Bind Select Config Property Types Date Time Gradient Predicate Tooltip Invalid Data Concatenating views Edit this page To place views side-by-side, Vega-Lite’s view composition provides the following concatenation operators: hconcat - horizontal concatenation vconcat - vertical concatenation concat - general concatenation (wrappable) If you concatenate similar views where the only difference is the field that is used in an encoding, use the repeat operator. Documentation Overview Horizontal Concatenation Example Vertical Concatenation Example General (Wrappable) Concatenation Example Resolve Concat Configuration Horizontal Concatenation To put multiple views into a column, set the \"hconcat\" to an array of view specifications. { \"hconcat\": [ ... // Specifications ], ... } In addition to common properties of a view specification, a horizontal concat specification has the following properties: Property Type Description hconcat Any Example Vertical Concatenation To put multiple views into a row, set the \"vconcat\" to an array of view specifications. { \"vconcat\": [ ... // Specifications ], ... } In addition to common properties of a view specification, a vertical concat specification has the following properties: Property Type Description vconcat Any Example General (Wrappable) Concatenation To put multiple views into a flexible flow layout, set the \"concat\" to an array of view specifications and specify the \"columns\" property to set the number of maximum items per rows. { \"concat\": [ ... // Specifications ], \"columns\": ..., ... } In addition to common properties of a view specification, a general concat specification has the following properties: Property Type Description concat Any columns Any Example Resolve The default resolutions for concatenation are independent scales and axes for position channels and shared scales and legends for all other channels. Currently, Vega-Lite does not support shared axes for concatenated views. Concat Configuration // Top-level View Specification { ..., \"config\": { // Configuration Object \"concat\": { // - Concat Configuration \"spacing\": ..., \"columns\": ..., }, ... } } The concat configuration supports the following properties: Property Type Description columns Number The number of columns to include in the view composition layout. Default value: undefined – An infinite number of columns (a single row) will be assumed. This is equivalent to hconcat (for concat) and to using the column channel (for facet and repeat). Note: 1) This property is only for: the general (wrappable) concat operator (not hconcat/vconcat) the facet and repeat operator with one field/repetition definition (without row/column nesting) 2) Setting the columns to 1 is equivalent to vconcat (for concat) and to using the row channel (for facet and repeat). spacing Number The default spacing in pixels between composed sub-views. Default value: 20 Edit this page and submit a pull request!", "category": "composition", "source": "vega-lite" }, { "title": "Faceting a Plot into a Trellis Plot", "url": "https://vega.github.io/vega-lite/docs/facet.html", "content": "Vega-Lite Vega Altair Vega-Lite API Examples Tutorials Documentation Usage Ecosystem GitHub Try Online Overview View Specification Title Width / Height Data / Datasets Transform Aggregate Bin Calculate Density Extent Filter Flatten Fold Impute Join Aggregate Loess Lookup Pivot Quantile Regression Sample Stack Time Unit Window Mark Arc Area Bar Box Plot Circle Error Band Error Bar Geoshape Image Line Point Rect Rule Square Text Tick Trail Encoding Aggregate Axis Band Position Bin Condition Datum Field Format Header Impute Legend Scale Stack Sort Time Unit Type Value Projection View Composition Facet Layer Concat Repeat Resolve Parameter Value Expr Bind Select Config Property Types Date Time Gradient Predicate Tooltip Invalid Data Faceting a Plot into a Trellis Plot Edit this page A Trellis plot (or small multiple) is a series of similar plots that displays different subsets of the same data, facilitating comparison across subsets. There are two ways to facet views in Vega-Lite: First, the facet operator is one of Vega-Lite’s view composition operators. This is the most flexible way to create faceted plots and allows composition with other operators. Second, as a shortcut you can use the facet, column, or row encoding channels. Documentation Overview Facet Operator Facet Field Definition Row/Column Facet Mapping Facet Headers Example Row-Facet Wrapped Facet Facet, Row, and Column Encoding Channels Facet Field Definition Examples Row Facet (with Row Encoding) Grid Facet (with Row and column Encoding) Wrapped Facet (with Facet Encoding) Resolve Facet Configuration Facet Operator To create a faceted view, define how the data should be faceted in facet and how each facet should be displayed in the spec. { \"facet\": { ... // Facet definition }, \"spec\": ... // Specification } In addition to common properties of a view specification, a facet specification has the following properties: Property Type Description facet FacetFieldDef | FacetMapping Required. Definition for how to facet the data. One of: 1) a field definition for faceting the plot by one field 2) An object that maps row and column channels to their field definitions spec LayerSpec | UnitSpec Required. A specification of the view that gets faceted. columns Number The number of columns to include in the view composition layout. Default value: undefined – An infinite number of columns (a single row) will be assumed. This is equivalent to hconcat (for concat) and to using the column channel (for facet and repeat). Note: 1) This property is only for: the general (wrappable) concat operator (not hconcat/vconcat) the facet and repeat operator with one field/repetition definition (without row/column nesting) 2) Setting the columns to 1 is equivalent to vconcat (for concat) and to using the row channel (for facet and repeat). Facet Field Definition A facet field definition has the following properties: Property Type Description bin Boolean | BinParams | Null A flag for binning a quantitative field, an object defining binning parameters, or indicating that the data for x or y channel are binned before they are imported into Vega-Lite (\"binned\"). If true, default binning parameters will be applied. If \"binned\", this indicates that the data for the x (or y) channel are already binned. You can map the bin-start field to x (or y) and the bin-end field to x2 (or y2). The scale and axis will be formatted similar to binning in Vega-Lite. To adjust the axis ticks based on the bin step, you can also set the axis’s tickMinStep property. Default value: false See also: bin documentation. field Field Required. A string defining the name of the field from which to pull a data value or an object defining iterated values from the repeat operator. See also: field documentation. Notes: 1) Dots (.) and brackets ([ and ]) can be used to access nested objects (e.g., \"field\": \"foo.bar\" and \"field\": \"foo['bar']\"). If field names contain dots or brackets but are not nested, you can use \\\\ to escape dots and brackets (e.g., \"a\\\\.b\" and \"a\\\\[0\\\\]\"). See more details about escaping in the field documentation. 2) field is not required if aggregate is count. timeUnit TimeUnit | String | TimeUnitParams Time unit (e.g., year, yearmonth, month, hours) for a temporal field. or a temporal field that gets casted as ordinal. Default value: undefined (None) See also: timeUnit documentation. type String The type of measurement (\"quantitative\", \"temporal\", \"ordinal\", or \"nominal\") for the encoded field or constant value (datum). It can also be a \"geojson\" type for encoding ‘geoshape’. Vega-Lite automatically infers data types in many cases as discussed below. However, type is required for a field if: (1) the field is not nominal and the field encoding has no specified aggregate (except argmin and argmax), bin, scale type, custom sort order, nor timeUnit or (2) if you wish to use an ordinal scale for a field with bin or timeUnit. Default value: 1) For a data field, \"nominal\" is the default data type unle", "category": "composition", "source": "vega-lite" }, { "title": "Repeat a View", "url": "https://vega.github.io/vega-lite/docs/repeat.html", "content": "Vega-Lite Vega Altair Vega-Lite API Examples Tutorials Documentation Usage Ecosystem GitHub Try Online Overview View Specification Title Width / Height Data / Datasets Transform Aggregate Bin Calculate Density Extent Filter Flatten Fold Impute Join Aggregate Loess Lookup Pivot Quantile Regression Sample Stack Time Unit Window Mark Arc Area Bar Box Plot Circle Error Band Error Bar Geoshape Image Line Point Rect Rule Square Text Tick Trail Encoding Aggregate Axis Band Position Bin Condition Datum Field Format Header Impute Legend Scale Stack Sort Time Unit Type Value Projection View Composition Facet Layer Concat Repeat Resolve Parameter Value Expr Bind Select Config Property Types Date Time Gradient Predicate Tooltip Invalid Data Repeat a View Edit this page The repeat operator is part of Vega-Lite’s view composition. It provides a shortcut that creates a view for each entry in an array of fields. This operator generates multiple plots like facet. However, unlike facet it allows full replication of a data set in each view. Documentation Overview Repeat Operator Row/Column/Layer Repeat Mapping Examples Repeated Line Charts Multi-series Line Chart with Repeated Layers Repeated Histogram (Wrapped) Scatterplot Matrix (SPLOM) Resolve Repeat Configuration Repeat Operator To repeat a view, define what fields should be used for each entry. Then define the repeated view in spec with a reference to a repeated field ({\"repeat\": ...}). { \"repeat\": { ... // Repeat definition }, \"spec\": ... // Specification } In addition to common properties of a view specification, a repeat specification has the following properties: Property Type Description repeat Any spec Any columns Any Row/Column/Layer Repeat Mapping The repeat property can be an object with at least one of \"row\", \"column\" and \"layer\" properties, which define the list of fields that should be repeated into a row, a column, or a layer. Note that when you repeat views into layers, the views are superimposed. Even if different layers use different colors, Vega-Lite will not generate a legend and not stack marks such as bars or areas. If you want a legend or stack different fields, use the fold transform to convert your data to long form and then use a color encoding. Property Type Description row String[] An array of fields to be repeated vertically. column String[] An array of fields to be repeated horizontally. Examples Repeated Line Charts For instance, you can use this operator to quickly create an overview over the trends in multiple variables. Note how the field for the y channel refers to a repeated field. \"y\": { \"field\": {\"repeat\": \"repeat\"} ... }, Multi-series Line Chart with Repeated Layers You can also use repeat with layer to create a multi-series line chart. Here we map a repeater field as data value (datum) for the color encoding. Repeated Histogram (Wrapped) Scatterplot Matrix (SPLOM) Repeat can be used to create a scatterplot matrix (SPLOM), where each cell shows a different 2D projection of the same data table. Here, we define both row and column. You can also check the interactive SPLOM example. Resolve The default resolutions for repeat are independent scales and axes for position channels and shared scales and legends for all other channels. Currently, Vega-Lite does not support shared axes for repeated views. Repeat Configuration Since repeat is a shorthand for concatenation, the concat configuration is also used for repeated views. // Top-level View Specification { ..., \"config\": { // Configuration Object \"concat\": { // - Concat Configuration \"spacing\": ..., \"columns\": ..., }, ... } } The repeat configuration supports the following properties: Property Type Description columns Number The number of columns to include in the view composition layout. Default value: undefined – An infinite number of columns (a single row) will be assumed. This is equivalent to hconcat (for concat) and to using the column channel (for facet and repeat). Note: 1) This property is only for: the general (wrappable) concat operator (not hconcat/vconcat) the facet and repeat operator with one field/repetition definition (without row/column nesting) 2) Setting the columns to 1 is equivalent to vconcat (for concat) and to using the row channel (for facet and repeat). spacing Number The default spacing in pixels between composed sub-views. Default value: 20 Edit this page and submit a pull request!", "category": "composition", "source": "vega-lite" } ]