# geom-point

Scatterplot layer drawing a marker for each row at `(x, y)`.

Default `stat` is `"identity"` and default `position` is `"identity"`. `fill` paints the marker body; `colour` paints the outline. Shape and alpha can be mapped via [`aes`](../../reference/core/aes.llms.md) or set to fixed values through the layer parameters below.

## Usage

``` typst
geom-point(
  mapping: none,
  data: none,
  size: auto,
  colour: auto,
  fill: auto,
  stroke: auto,
  alpha: auto,
  shape: auto,
  key: auto,
  stat: "identity",
  position: "identity",
  inherit-aes: true,
)
```

## Parameters

| Parameter | Default | Description |
|----|----|----|
| `mapping` | `none` | Layer-specific aesthetic mapping built with [`aes`](../../reference/core/aes.llms.md). Falls back to the plot mapping when `none`. |
| `data` | `none` | Layer-specific dataset, or a function applied to the plot data returning the layer frame. Falls back to the plot data when `none`. |
| `size` | `auto` | Marker size (a Typst length). |
| `colour` | `auto` | Fixed marker outline colour. `auto` resolves via the colour scale, falling back to the theme `ink` only when neither `colour` nor `fill` is set. |
| `fill` | `auto` | Marker body fill. `auto` resolves via the fill scale or a neutral default. |
| `stroke` | `auto` | Marker outline thickness (a Typst length) or stroke dictionary; `none` disables the outline and the `colour` aesthetic. |
| `alpha` | `auto` | Marker opacity in `[0, 1]`. |
| `shape` | `auto` | Marker shape keyword (e.g., `"circle"`, `"square"`, `"triangle"`). `auto` honours the shape scale. |
| `key` | `auto` | Legend glyph override built with a `draw-key-*` helper. `auto` picks the default for the geom. |
| `stat` | `"identity"` | Statistical transform name. Usually left at `"identity"`. |
| `position` | `"identity"` | Position adjustment name. Usually left at `"identity"`. |
| `inherit-aes` | `true` | Whether to merge the plot-level mapping into this layer’s mapping. |

## Returns

Layer dictionary consumed by [`plot`](../../reference/core/plot.llms.md).

## Examples

Default scatter, mapping `fill` to a categorical column.

``` typst
#let d = (
  (x: 1, y: 2, sp: "a"),
  (x: 2, y: 4, sp: "b"),
  (x: 3, y: 3, sp: "a"),
  (x: 4, y: 5, sp: "b"),
)
#plot(
  data: d,
  mapping: aes(x: "x", y: "y", fill: "sp"),
  layers: (geom-point(size: 3pt),),
  width: 10cm,
  height: 6cm,
)
```

[![Scatter of four (x, y) points across x = 1 to 4 with markers coloured by species (a, b) via the fill aesthetic.](../../assets/typst-render/references/geom-point-1-light.svg)](../../assets/typst-render/references/geom-point-1-light.svg "Scatter of four (x, y) points across x = 1 to 4 with markers coloured by species (a, b) via the fill aesthetic.")

[![Scatter of four (x, y) points across x = 1 to 4 with markers coloured by species (a, b) via the fill aesthetic.](../../assets/typst-render/references/geom-point-1-dark.svg)](../../assets/typst-render/references/geom-point-1-dark.svg "Scatter of four (x, y) points across x = 1 to 4 with markers coloured by species (a, b) via the fill aesthetic.")

Map `shape` and `size` alongside `fill` to encode three dimensions on the same scatter.

``` typst
#let d = (
  (x: 1, y: 2, sp: "a", w: 1),
  (x: 2, y: 4, sp: "b", w: 2),
  (x: 3, y: 3, sp: "a", w: 3),
  (x: 4, y: 5, sp: "b", w: 4),
)
#plot(
  data: d,
  mapping: aes(x: "x", y: "y", fill: "sp", shape: "sp", size: "w"),
  layers: (geom-point(),),
  width: 10cm,
  height: 6cm,
)
```

[![Scatter of (x, y) with marker fill and shape mapped to species and marker size encoding weight w from 1 to 4.](../../assets/typst-render/references/geom-point-2-light.svg)](../../assets/typst-render/references/geom-point-2-light.svg "Scatter of (x, y) with marker fill and shape mapped to species and marker size encoding weight w from 1 to 4.")

[![Scatter of (x, y) with marker fill and shape mapped to species and marker size encoding weight w from 1 to 4.](../../assets/typst-render/references/geom-point-2-dark.svg)](../../assets/typst-render/references/geom-point-2-dark.svg "Scatter of (x, y) with marker fill and shape mapped to species and marker size encoding weight w from 1 to 4.")

The classic penguins scatter: flipper length vs body mass, coloured and shaped by species.

``` typst
#plot(
  data: penguins,
  mapping: aes(
    x: "flipper-len",
    y: "body-mass",
    fill: "species",
    shape: "species",
  ),
  layers: (geom-point(size: 2pt, alpha: 0.85),),
  labels: labels(
    x: "Flipper Length (mm)",
    y: "Body Mass (g)",
    fill: "Species",
    shape: "Species",
  ),
  width: 11cm,
  height: 6cm,
)
```

[![Scatter of penguin flipper length (mm) against body mass (g) with markers coloured and shaped by species.](../../assets/typst-render/references/geom-point-3-light.svg)](../../assets/typst-render/references/geom-point-3-light.svg "Scatter of penguin flipper length (mm) against body mass (g) with markers coloured and shaped by species.")

[![Scatter of penguin flipper length (mm) against body mass (g) with markers coloured and shaped by species.](../../assets/typst-render/references/geom-point-3-dark.svg)](../../assets/typst-render/references/geom-point-3-dark.svg "Scatter of penguin flipper length (mm) against body mass (g) with markers coloured and shaped by species.")

A second layer passes a function as `data`; it receives the plot data and returns the subset to emphasise, here the heaviest penguins.

``` typst
#plot(
  data: penguins,
  mapping: aes(x: "flipper-len", y: "body-mass"),
  layers: (
    geom-point(alpha: 0.4),
    geom-point(
      data: rows => rows.filter(r => {
        let mass = r.at("body-mass", default: none)
        mass != none and mass >= 5500
      }),
      size: 3pt,
      colour: orange,
    ),
  ),
  labels: labels(x: "Flipper Length (mm)", y: "Body Mass (g)"),
  width: 11cm,
  height: 6cm,
)
```

[![Penguin scatter with the heaviest individuals re-drawn as larger highlighted markers.](../../assets/typst-render/references/geom-point-4-light.svg)](../../assets/typst-render/references/geom-point-4-light.svg "Penguin scatter with the heaviest individuals re-drawn as larger highlighted markers.")

[![Penguin scatter with the heaviest individuals re-drawn as larger highlighted markers.](../../assets/typst-render/references/geom-point-4-dark.svg)](../../assets/typst-render/references/geom-point-4-dark.svg "Penguin scatter with the heaviest individuals re-drawn as larger highlighted markers.")

## See also

[`geom-line`](../../reference/geoms/geom-line.llms.md), [`geom-text`](../../reference/geoms/geom-text.llms.md), [`scale-discrete`](../../reference/scales/scale-discrete.llms.md), [`aes`](../../reference/core/aes.llms.md).

Back to top