Appearance

Marks ​

Marks are graphical elements that visualize data through encoding channels such as x and y position, fill color, and r (radius) size. Marks are added to a Plot using the mark directive functions listed below.

Most mark functions take two arguments: a data source and an options object that specifies encoding channels or constant values. To visualize data from a backing database, the from() method should be used to specify the data source. For example, from("data", { filterBy: sel }) indicates that data should be drawn from the database table "data", interactively filtered by the selection sel.

js
import { barY, from, plot } from "@uwdata/vgplot";
plot(
  barY(from("data"), { x: "a", y: "b", fill: "steelblue", opacity: 0.5 })
)

The example above specifies a bar chart with bars oriented vertically. Data is drawn from the "data" table, with the column "a" mapped to an ordinal x axis and the column "b" mapped to the y axis. The fill option is the constant CSS color "steelblue" and the opacity is a constant 0.5. For encoding channels, strings are interpreted as column names unless they match a reserved constant for that key, such as a CSS color name for the fill or stroke options.

If an explicit array of data values is provided instead of a backing from(tableName) reference, vgplot will visualize that data without issuing any queries to the database. This functionality is particularly useful for adding manual annotations, such as custom rules or text labels.

Marks that only add reference lines or shapes (e.g., frame, axisX, gridY, hexgrid, graticule, sphere) do not require corresponding data, and take only options.

Marks use the semantics of Observable Plot. For example, mark variants may indicate not only shapes but also data type assumptions. The barY mark above assumes a discrete (ordinal) x axis and will produce a band scale, whereas the related rectY mark instead assumes a continuous x axis and by default will produce a linear scale.

Area ​

An area mark, with areaX and areaY variants. When feasible, the areaX and areaY marks will perform M4 optimization to limit the number of sample points returned from the database. Use from("data", { optimize: false }) to disable this behavior. For supported options, see the Observable Plot area documentation.

Arrow ​

The arrow mark provides line segments with arrow heads. For supported options, see the Observable Plot arrow documentation.

Axis ​

To go beyond the built-in axis generation, the axis mark supports explicit inclusion of axes, along with control over drawing order. The provided mark directives are axisX and axisY (for standard axes) as well as axisFx and axisFy (for facet axes). For supported options, see the Observable Plot axis documentation.

Bar ​

The barX and barY marks draw rectangles, and should be used when one dimension is ordinal and the other is quantitative. For supported options, see the Observable Plot bar documentation.

Cell ​

The cell mark, with cellX and cellY variants, draws rectangles positioned in two ordinal dimensions. For supported options, see the Observable Plot cell documentation.

Contour ​

The contour mark draws isolines to delineate regions above and below a particular continuous value. It is often used to convey densities as a height field. The special column name "density" can be used to map density values to the fill or stroke options.

The supported options are:

  • x: The x dimension encoding channel
  • y: The y dimension encoding channel
  • fill: The contour fill color
  • stroke: The contour stroke color
  • thresholds: The number of contour thresholds to include (default 10)
  • bandwidth: The kernel density bandwidth for smoothing, in pixels (default 20)
  • interpolate: The binning interpolation method to use, one of "linear" (default) or "none"
  • pixelSize: The grid cell size in screen pixels (default 2); ignored when width and height options are provided
  • width: The number of grid bins to include along the x dimension
  • height: The number of grid bins to include along the y dimension
  • pad: The bin padding, one of 0 (default) to make the bins flush with the maximum domain value, or 1 to include extra padding for the final bin
  • Other standard mark options including fillOpacity and strokeWidth

Delaunay ​

Given set of points in x and y, the Delaunay marks compute the Delaunay triangulation, its dual the Voronoi tessellation, and the convex hull. The supported marks are voronoi, voronoiMesh, delaunayLink, delaunayMesh, and hull. For more, see the Observable Plot delaunay documentation.

Density 1D ​

The 1D density marks show smoothed point cloud densities along one dimension. The densityX and densityY marks bin the data, count the number of records that fall into each bin, smooth the resulting counts, then plot the smoothed distribution (by default using an area mark). The densityX mark maps density values to the x dimension automatically, while densityY maps the density values to the y dimension.

The supported options are:

  • x: The x dimension encoding channel, used with densityY
  • y: The y dimension encoding channel, used with densityX
  • type: The mark type to use (default areaX or areaY)
  • bins: The number of bins (default 1024)
  • bandwidth: The kernel density bandwidth for smoothing, in pixels (default 20)
  • Any options accepted by the mark type, including stroke and fill

Density 2D ​

The 2D density mark shows smoothed point cloud densities along two dimensions. The mark will bin the data, count the number of records that fall into each bin, smooth the resulting counts, then plot the smoothed distribution (by default using a circular dot mark). The density mark calculates density values that can be mapped to encoding channels such as fill or r using the column name "density".

The supported options are:

  • x: The x dimension encoding channel
  • y: The y dimension encoding channel
  • type: The mark type to use (default dot)
  • bandwidth: The kernel density bandwidth for smoothing, in pixels (default 20)
  • interpolate: The binning interpolation method to use, one of "linear" (default) or "none"
  • pixelSize: The grid cell size in screen pixels (default 2); ignored when width and height options are provided
  • width: The number of grid bins to include along the x dimension
  • height: The number of grid bins to include along the y dimension
  • pad: The bin padding, one of 0 (default) to make the bins flush with the maximum domain value, or 1 to include extra padding for the final bin
  • Any options accepted by the mark type, including fill, stroke, and r

Dense Line ​

Rather than plot point densities, the denseLine mark plots line densities: the mark forms a binned raster grid and "draws" lines into it. To avoid over-weighting steep lines, by default each drawn series will be normalized on a per-column basis to approximate arc length normalization. The values for each series are then aggregated to form the line density, which is then drawn as an image similar to the raster mark.

The supported options are:

  • x: The x dimension encoding channel
  • y: The y dimension encoding channel
  • bandwidth: The kernel density bandwidth for smoothing (default 0)
  • pixelSize: The grid cell size in screen pixels (default 1)
  • pad: The bin padding, one of 1 (default) to include extra padding for the final bin, or 0 to make the bins flush with the maximum domain value.
  • width: The number of grid bins to include along the x dimension
  • height: The number of grid bins to include along the y dimension
  • normalize: Boolean flag (default true) controlling approximate arc length normalization.

Dot ​

The dot mark, with dotX and dotY variants, draws circles or other symbols positioned in x and y as in a scatterplot. The circle and hexagon marks are convenient shorthands for specific shapes. For supported options, see the Observable Plot dot documentation.

Frame ​

The frame mark draws a rectangle around the plot area. It does not take a data argument. For supported options, see the Observable Plot frame documentation.

Geo ​

The geo mark draws geographic features—polygons, lines, points, and other geometry—often as thematic maps. Input data can be provided directly an array of GeoJSON features or geographic data can be loaded and queried directly in DuckDB using the spatial extension.

The geometry option indicates the column name containing GeoJSON features or GeoJSON geometry objects. If geometry is not specified, the mark will interpret input objects as GeoJSON when data is passed in directly. When querying geometry from a DuckDB table, the geometry option will default to 'geom' (the default name for geometry data loaded using the spatial extension's ST_Read function) and will be automatically converted to GeoJSON format in the databse using the ST_asGeoJSON function. If the geometry option is specified, automatic conversion of DuckDB query results is not performed; this enables more fine-grained control, but may require explicit conversion of data to GeoJSON format using ST_asGeoJSON (or equivalently using Mosaic's geojson() SQL helper).

The sphere and graticule marks (which do not accept input data) include the sphere of the Earth and global reference lines, respectively. For other supported options, see the Observable Plot geo documentation.

Grid ​

The grid mark is a specially-configured rule for drawing an axis-aligned grid. To go beyond the built-in axis generation, the grid mark supports explicit inclusion of grid lines, along with control over drawing order. The provided mark directives are gridX and gridY (for standard axes) as well as gridFx and gridFy (for facet axes). For supported options, see the Observable Plot grid documentation.

Heatmap ​

The heatmap mark is a raster mark with default options for accurate density estimation via smoothing. The bandwidth (20), interpolate ("linear"), and pixelSize (2) options are set to produce smoothed density heatmaps. For all supported options, see the raster mark.

Hexbin ​

The hexbin mark bins data into a hexagonal grid and visualizes aggregate functions per bin (e.g., count for binned density). Hexagonal binning and aggregation are pushed to the backing database. Aggregate functions can be used for the mark fill, stroke, or radius size r options.

The supported options are:

  • x: The x dimension encoding channel
  • y: The y dimension encoding channel
  • type: The mark type to use (default hexagon)
  • binWidth: The hexagon bin width in screen pixels (default 20)
  • Any options accepted by the mark type, including fill, stroke, r.

Hexgrid ​

The hexgrid mark draws a hexagonal grid spanning the frame. For supported options, see the Observable Plot hexgrid documentation.

Image ​

The image mark draws images centered at the given position in x and y. For supported options, see the Observable Plot image documentation.

Line ​

A line mark, with lineX and lineY variants. When feasible, the lineX and lineY marks will perform M4 optimization to limit the number of sample points returned from the database. Use from("data", { optimize: false }) to disable this behavior. For supported options, see the Observable Plot line documentation.

Regression ​

The regressionY mark draws a regression line and optional confidence interval area for a linear regression fit. The regression calculation is pushed to the backing database.

The supported options are:

  • x: The x dimension (predictor) encoding channel
  • y: The y dimension (predicted) encoding channel
  • ci: The confidence level (default 0.95) to visualize as a confidence band area; use zero or null to suppress
  • precision: The distance (in pixels) between samples of the confidence band (default 4)

The link mark draws straight lines between two points [x1, y1] and [x2, y2] in quantitative dimensions. For supported options, see the Observable Plot link documentation.

Raster ​

The raster mark draws an image whose pixel colors are a function of the underlying data. The x and y data domains are binned into the cells ("pixels") of a raster grid, typically with an aggregate function evaluated over the binned data. The result can be optionally smoothed (blurred) in-browser. To create a smoothed density heatmap, use the heatmap mark; this is a raster mark with different default options.

The supported options are:

  • x: The x dimension encoding channel
  • y: The y dimension encoding channel
  • fill: The pixel fill color. Use the special value "density" to map computed density values to pixel colors. Use an aggregate expression to instead visualize an aggregate value per raster bin. If fill is set to a constant color or to a non-aggregate field, opacity will be used to convey densities. If a non-aggregate (group by) field is provided, multiple rasters are created with a unique categorical color per layer.
  • fillOpacity: The pixel fill opacity. Use the special value "density" to map computed density values to opacity. Use an aggregate expression to instead visualize an aggregate value per raster bin.
  • weight: A data column by which to weight computed densities
  • bandwidth: The kernel density bandwidth for smoothing, in pixels (default 0)
  • interpolate: The binning interpolation method to use. The "none" and "linear" methods are performed in-database and only fill bins corresponding to observed data samples. The other methods are performed in-browser and interpolate to fill all raster pixels. The options are:
    • "none" (default): Map data samples to single bins only.
    • "linear": Linearly distribute the "weight" of a sample across adjacent bin boundaries. Linear binning provides more stable and accurate density estimation upon subsequent smoothing.
    • "nearest": Perform nearest-neighbor interpolation, forming a pixel-level Voronoi diagram.
    • "barycentric": Interpolate over a triangulation of sample points. Pixels outside the convex hull of data samples are extrapolated.
    • "random-walk: Apply a random walk from empty pixels until a sample is found.
  • pixelSize: The grid cell size in screen pixels (default 1); ignored when width and height options are provided
  • width: The number of grid bins to include along the x dimension
  • height: The number of grid bins to include along the y dimension
  • pad: The bin padding, one of 1 (default) to include extra padding for the final bin, or 0 to make the bins flush with the maximum domain value

Rect ​

The rect mark, with rectX and rectY variants, draws draws axis-aligned rectangles defined by x1, y1, x2, and y2. For supported options, see the Observable Plot rect documentation.

Rule ​

The ruleX mark draws a vertical line with a given x value, while the ruleY mark draws a horizontal line with a given y value. For supported options, see the Observable Plot rule documentation.

Text ​

The text mark, with textX and textY variants, draws text at the given position in x and y. It is often used to label other marks. For supported options, see the Observable Plot text documentation.

Tick ​

The tickX draws a vertical line with a given x value, while the tickY mark draws a horizontal line with a given y value. Ticks have an optional secondary position dimension (y for tickX and x for tickY); this second dimension is ordinal, unlike a rule, and requires a corresponding band scale. For supported options, see the Observable Plot tick documentation.

Vector ​

The vector mark, with vectorX and vectorY variants, draws little arrows, typically positioned in x and y quantitative dimensions, with an optional magnitude (length) and direction (rotate), as in a vector field.

The spike mark is equivalent to vector, but changes the default shape, anchor, and color options to draw a more spiky element.

For supported options, see the Observable Plot vector documentation.