Skip to main content

nanoplot

Draw a Gribouille plot in each cell of a keisen nanoplot column, with a shared axis.

NoteExperimental

This function is experimental; its interface may change without notice.

nanoplot returns a keisen nanoplot renderer. Give it to the plot argument of keisen’s format-nanoplot. Each cell holds an array of records, and the cell draws them as the data of plot, with the given mapping, layers, scales and theme.

keisen reads the domain-field of every record in the column and computes one domain. Each cell then uses that domain as the limits of its x scale, so all cells share one x scale. The other arguments of the x scale in scales stay as given. The x scale keeps the default expansion of Gribouille unless the x scale in scales sets expand. Cells draw no axes, no axis titles and no legends.

When axis is true, keisen draws the x axis of the column below the column labels and again after the last row. The axis uses the same x scale and theme as the cells, so each break lines up with the cells. The cells and the axis set the column domain as the x-limits of coord-cartesian, so a geom that draws whole marks, such as geom-col, geom-tile or geom-histogram, does not widen the scale of a cell. A mark at the end of the domain is centred on the end, and the part of it past the end is drawn into the cell margin. To draw whole marks, give keisen’s format-nanoplot a domain that holds them, for example half a bar width past each end, as in domain: (-0.5, 10.5) for bars at 0 to 10. A tick label at the end of the domain is centred on the end, so half of it can go past the column content into the cell inset. It draws the tick labels even when the theme hides them, as theme-void does. The axis draws no axis line and no plot background, even when the theme sets them. Gribouille does not import keisen: the renderer is a plain dictionary.

Usage

nanoplot(
  mapping: none,
  layers: (),
  scales: (:),
  theme: none,
  domain-field: none,
  axis: true,
  axis-height: auto,
)

Parameters

Parameter Default Description
mapping none Aesthetic mapping from aes, applied to the records of each cell.
layers () Array of geom layers drawn in each cell.
scales (:) Scales from scales. The x scale gets the column domain as its limits. It must be continuous, because the column domain is numeric.
theme none Theme for the cells and the axis; none (default) uses theme-void.
domain-field none Name of the record field that holds the x values, as a string. keisen reads it to compute the column domain. It has no default: none fails.
axis true true (default) gives the column an x axis; false gives it none.
axis-height auto Height of the axis, as a length; default auto. auto gives the height of the axis ticks plus 1.4 times the size of the axis text of the theme. The axis text takes its size from the theme, not from the table, so give a length only to set the height yourself.

Returns

A keisen nanoplot renderer, (kind: "nanoplot-renderer", draw, readings, axis).

Examples

Call the drawers of the renderer as keisen does, for one cell and the axis below it.

#let renderer = nanoplot(
  mapping: aes(x: "salary", y: "y"),
  layers: (geom-point(size: 2pt),),
  domain-field: "salary",
)
#let cell = (25000, 32000, 41000, 50000, 58000).map(v => (salary: v, y: 0))
#let domain = (20000, 60000)
// The end labels reach past the cell, as they reach into the cell inset in a table.
#pad(x: 2em, stack(
  spacing: 2pt,
  (renderer.draw)(cell, domain: domain, width: 9cm, height: 0.6cm),
  (renderer.axis)(domain: domain, width: 9cm, side: "bottom"),
))

A strip of five points along a salary scale from 20000 to 60000, drawn without axes, above an axis with tick labels at 20000, 30000, 40000, 50000 and 60000 that line up with the points.

A strip of five points along a salary scale from 20000 to 60000, drawn without axes, above an axis with tick labels at 20000, 30000, 40000, 50000 and 60000 that line up with the points.

Draw a strip of salaries in each row of a keisen table, with the axis above the first row and below the last. The document imports keisen as keisen.

#let rows = (
  (field: "Engineering", majors: ((salary: 61000, y: 0), (salary: 72000, y: 0))),
  (field: "Education", majors: ((salary: 38000, y: 0), (salary: 41000, y: 0))),
)
#keisen.display-table(
  rows,
  keisen.format-nanoplot(
    "majors",
    plot: nanoplot(
      mapping: aes(x: "salary", y: "y"),
      layers: (geom-point(size: 2pt),),
      scales: scales(x: scale-continuous(labels: format-currency())),
      domain-field: "salary",
    ),
    width: 6cm,
    height: 0.6cm,
    domain: (0, 115000),
  ),
)

See also

plot, scales, theme-void.

Back to top