---
url: /mosaic/api/vgplot/marks.md
---

**(begin JavaScript API)**

# 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`](./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`](#frame), [`axisX`](#axis), [`gridY`](#grid), [`hexgrid`](#hexgrid), [`graticule`](#geo), [`sphere`](#geo)) do not require corresponding data, and take only *options*.

Marks use the semantics of [Observable Plot](https://observablehq.com/plot/features/marks).
For example, mark variants may indicate not only shapes but also data type assumptions.
The [`barY`](#bar) mark above assumes a discrete (ordinal) *x* axis and will produce a `band` scale, whereas the related [`rectY`](#rect) 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](https://observablehq.com/@uwdata/m4-scalable-time-series-visualization) 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](https://observablehq.com/plot/marks/area).

## Arrow

The `arrow` mark provides line segments with arrow heads.
For supported options, see the [Observable Plot `arrow` documentation](https://observablehq.com/plot/marks/arrow).

## 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](https://observablehq.com/plot/marks/axis).

## 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](https://observablehq.com/plot/marks/bar).

## 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](https://observablehq.com/plot/marks/cell).

## 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](https://observablehq.com/plot/marks/delaunay).

## 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`](#area) or [`areaY`](#area))
* *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`](#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`](#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](https://observablehq.com/plot/marks/dot).

## 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](https://observablehq.com/plot/marks/frame).

## Geo

The `geo` mark draws geographic features—polygons, lines, points, and other geometry—often as thematic maps.
Input data can be provided directly as 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 database 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](https://observablehq.com/plot/marks/geo).

## 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](https://observablehq.com/plot/marks/grid).

## 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`](#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`](#dot))
* *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](https://observablehq.com/plot/marks/hexgrid).

## Image

The `image` mark draws images centered at the given position in *x* and *y*.
For supported options, see the [Observable Plot `image` documentation](https://observablehq.com/plot/marks/image).

## Line

A `line` mark, with `lineX` and `lineY` variants.
When feasible, the `lineX` and `lineY` marks will perform [M4 optimization](https://observablehq.com/@uwdata/m4-scalable-time-series-visualization) 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](https://observablehq.com/plot/marks/line).

## 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`)

## Link

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](https://observablehq.com/plot/marks/link).

## 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`](#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 axis-aligned rectangles defined by *x1*, *y1*, *x2*, and *y2*.
For supported options, see the [Observable Plot `rect` documentation](https://observablehq.com/plot/marks/rect).

## 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](https://observablehq.com/plot/marks/rule).

## 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](https://observablehq.com/plot/marks/text).

## 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`](#rule), and requires a corresponding band scale.
For supported options, see the [Observable Plot `tick` documentation](https://observablehq.com/plot/marks/tick).

## 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](https://observablehq.com/plot/marks/vector).

**(end JavaScript API)**

**(begin Python API)**

# 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`](./plot) using mark directives from `vgplot` (for example `vg.bar_y(...)`).

Most mark functions take a *data* source and an *options* object that specifies encoding channels or constant values.
To visualize data from a backing database, pass a `DataDef` object (from `vg.parquet()`, `vg.csv()`, etc.) or a `vg.source("table")` reference as the first positional argument. Interactive filtering is expressed via the `filter_by` keyword (see the [Python vgplot README](https://pypi.org/project/vgplot/) for details on selection wiring).

```python
import vgplot as vg

vg.plot(
    vg.bar_y(vg.source("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 database-backed source, 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`](#frame), [`axis_x`](#axis), [`grid_y`](#grid), [`hexgrid`](#hexgrid), [`graticule`](#geo), [`sphere`](#geo)) do not require corresponding data, and take only *options*.

Marks use the semantics of [Observable Plot](https://observablehq.com/plot/features/marks).
For example, mark variants may indicate not only shapes but also data type assumptions.
The [`bar_y`](#bar) mark above assumes a discrete (ordinal) *x* axis and will produce a `band` scale, whereas the related [`rect_y`](#rect) mark instead assumes a continuous *x* axis and by default will produce a `linear` scale.

## Area

An `area` mark, with `area_x` and `area_y` variants.
When feasible, the `area_x` and `area_y` marks will perform [M4 optimization](https://observablehq.com/@uwdata/m4-scalable-time-series-visualization) to limit the number of sample points returned from the database.
Use `vg.source("data", optimize=False)` as the mark `data` argument to disable this behavior.
For supported options, see the [Observable Plot `area` documentation](https://observablehq.com/plot/marks/area).

## Arrow

The `arrow` mark provides line segments with arrow heads.
For supported options, see the [Observable Plot `arrow` documentation](https://observablehq.com/plot/marks/arrow).

## 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 `axis_x` and `axis_y` (for standard axes) as well as `axis_fx` and `axis_fy` (for facet axes).
For supported options, see the [Observable Plot `axis` documentation](https://observablehq.com/plot/marks/axis).

## Bar

The `bar_x` and `bar_y` 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](https://observablehq.com/plot/marks/bar).

## Cell

The `cell` mark, with `cell_x` and `cell_y` variants, draws rectangles positioned in two ordinal dimensions.
For supported options, see the [Observable Plot `cell` documentation](https://observablehq.com/plot/marks/cell).

## 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"`
* *pixel\_size*: 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 *fill\_opacity* and *stroke\_width*

## 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`, `voronoi_mesh`, `delaunay_link`, `delaunay_mesh`, and `hull`.
For more, see the [Observable Plot `delaunay` documentation](https://observablehq.com/plot/marks/delaunay).

## Density 1D

The 1D density marks show smoothed point cloud densities along one dimension.
The `density_x` and `density_y` 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 `density_x` mark maps density values to the *x* dimension automatically, while `density_y` maps the density values to the *y* dimension.

The supported *options* are:

* *x*: The x dimension encoding channel, used with `density_y`
* *y*: The y dimension encoding channel, used with `density_x`
* *type*: The mark type to use (default [`area_x`](#area) or [`area_y`](#area))
* *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`](#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"`
* *pixel\_size*: 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 `dense_line` 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`](#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`)
* *pixel\_size*: 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 `dot_x` and `dot_y` 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](https://observablehq.com/plot/marks/dot).

## 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](https://observablehq.com/plot/marks/frame).

## Geo

The `geo` mark draws geographic features—polygons, lines, points, and other geometry—often as thematic maps.
Input data can be provided directly as 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 database 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](https://observablehq.com/plot/marks/geo).

## 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 `grid_x` and `grid_y` (for standard axes) as well as `grid_fx` and `grid_fy` (for facet axes).
For supported options, see the [Observable Plot `grid` documentation](https://observablehq.com/plot/marks/grid).

## Heatmap

The `heatmap` mark is a raster mark with default options for accurate density estimation via smoothing.
The *bandwidth* (`20`), *interpolate* (`"linear"`), and *pixel\_size* (`2`) options are set to produce smoothed density heatmaps.
For all supported options, see the [`raster`](#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`](#dot))
* *bin\_width*: 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](https://observablehq.com/plot/marks/hexgrid).

## Image

The `image` mark draws images centered at the given position in *x* and *y*.
For supported options, see the [Observable Plot `image` documentation](https://observablehq.com/plot/marks/image).

## Line

A `line` mark, with `line_x` and `line_y` variants.
When feasible, the `line_x` and `line_y` marks will perform [M4 optimization](https://observablehq.com/@uwdata/m4-scalable-time-series-visualization) to limit the number of sample points returned from the database.
Use `vg.source("data", optimize=False)` as the mark `data` argument to disable this behavior.
For supported options, see the [Observable Plot `line` documentation](https://observablehq.com/plot/marks/line).

## Regression

The `regression_y` 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`)

## Link

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](https://observablehq.com/plot/marks/link).

## 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`](#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.
* *fill\_opacity*: 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.
* *pixel\_size*: 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 `rect_x` and `rect_y` variants, draws axis-aligned rectangles defined by *x1*, *y1*, *x2*, and *y2*.
For supported options, see the [Observable Plot `rect` documentation](https://observablehq.com/plot/marks/rect).

## Rule

The `rule_x` mark draws a vertical line with a given *x* value, while the `rule_y` mark draws a horizontal line with a given *y* value.
For supported options, see the [Observable Plot `rule` documentation](https://observablehq.com/plot/marks/rule).

## Text

The `text` mark, with `text_x` and `text_y` 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](https://observablehq.com/plot/marks/text).

## Tick

The `tick_x` mark draws a vertical line with a given *x* value, while the `tick_y` mark draws a horizontal line with a given *y* value.
Ticks have an optional secondary position dimension (*y* for `tick_x` and *x* for `tick_y`); this second dimension is ordinal, unlike a [`rule`](#rule), and requires a corresponding band scale.
For supported options, see the [Observable Plot `tick` documentation](https://observablehq.com/plot/marks/tick).

## Vector

The `vector` mark, with `vector_x` and `vector_y` 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](https://observablehq.com/plot/marks/vector).

**(end Python API)**