typstDotchart: Enhanced Dot Chart Rendered as Typst Markup

Description

typstDotchart is a Typst-markup translation of latexDotchart, itself a translation of dotchart3. It produces a character string of Typst markup (a single #box(...) containing a sequence of #place() calls) that visually mimics dotchart3's output, for use in Typst/Quarto documents in place of a raster image. As with latexDotchart, the add and horizontal=FALSE options available in dotchart3 are not supported here.

Usage

typstDotchart(
  data,
  labels,
  groups = NULL,
  gdata = NA,
  xlab = "",
  auxdata,
  auxgdata = NULL,
  auxtitle,
  w = 4,
  h = 4,
  margin,
  lines = TRUE,
  dotsize = 0.075,
  size = "small",
  size.labels = "small",
  size.group.labels = "normalsize",
  ttlabels = FALSE,
  sort. = TRUE,
  xaxis = TRUE,
  lcolor = "gray",
  ...
)

Value

A single character string of Typst markup -- one

#box(...) containing the full sequence of placed drawing commands -- suitable for passing to typstAsis (if it is the sole/final content being emitted) or for concatenating into a larger character vector alongside other Typst content.

Arguments

data: A numeric vector whose values are shown on the x-axis.
labels: A vector of labels for each point, corresponding to data. If omitted, names(data) are used, and if there are no names, integers prefixed by "#" are used.
groups: An optional categorical variable indicating how data values are grouped.
gdata: Data values for groups, typically summaries such as group medians.
xlab: X-axis title.
auxdata: A vector of auxiliary data, the same length as data. If present, printed outside the right margin of the chart -- usually cell sizes.
auxgdata: Similar to auxdata but corresponding to gdata.
auxtitle: If auxdata is given, a column heading for it (e.g. "N").
w: Width of the chart, in inches.
h: Height of the chart, in inches.
margin: A 4-vector, in inches: margin to the left of the x-axis, below the y-axis, to the right of the x-axis, and above the y-axis. By default computed automatically based on label/auxdata widths.
lines: Set to FALSE to suppress the horizontal reference lines.
dotsize: Diameter of the filled dots, in inches.
size: Text size for the main chart text, as a LaTeX font-size command name (see Details).
size.labels: Text size for row labels.
size.group.labels: Text size for group labels.
ttlabels: Set to TRUE to render row labels in a monospace font.
sort.: Set to FALSE to keep the input order rather than sorting by data value.
xaxis: Set to FALSE to suppress the x-axis.
lcolor: Color for the horizontal reference lines. Default "gray".
...: Ignored.

Details

typstDotchart reuses latexDotchart's coordinate computation, sorting, and margin logic essentially unchanged -- none of that is LaTeX-specific. Only the drawing primitives differ:

Text (\put(x,y){\makebox(...)[just]{s}}) becomes a call to a small shared Typst helper, justified-text (expected to already be defined in the document via typstFunctions$justifiedText), which uses Typst's measure() function to compute the rendered width/height of s and offset the placement accordingly -- the Typst equivalent of \makebox's own text-width-aware justification.
Lines (\put(x,y){\line(dx,dy){len}}) become #place(dx:, dy:, line(length:, angle:)) calls, with color passed directly as line()'s stroke: argument rather than LaTeX's stateful \color{...} ... \color{black} wrapping -- Typst needs no such state to be opened and closed.
Dots (\put(x,y){\circle*{d}}) become #place(dx:, dy:, circle(radius:, fill: black)) calls. Since #place() anchors the top-left of a shape's bounding box rather than its center, both dx and dy are offset by -radius so the dot is actually centered on its target point.

Because Typst's #place() measures dy from the top of its container downward, while LaTeX's picture environment measures y from the bottom upward, the internal y-coordinate function is wrapped in a single top/bottom flip (yt <- function(y) h - yt0(y)) so every other line of coordinate logic below it can be used completely unchanged from latexDotchart.

The gap between x-axis tick marks and their labels was originally a fixed 0.15 inch offset from the axis line, with tick marks 0.05 inches long -- an effective gap of 0.10 inches between the tick's far edge and the label. That gap has been reduced by 40% here (to 0.06 inches), giving a total label offset of 0.05 + 0.06 = 0.11 inches, confirmed by direct visual comparison against the original spacing.

size, size.labels, and size.group.labels keep latexDotchart's original LaTeX font-size-command-name interface (e.g. 'small', 'normalsize', 'large') for familiarity, translated internally to approximate point sizes via a fixed lookup table based on standard LaTeX class default point sizes. This is an approximation -- actual LaTeX point sizes depend on the base document font size -- not a byte-exact equivalence.

This is a first-draft port. The individual drawing primitives (text justification via measure(), dot centering, horizontal/vertical lines, direct color arguments, the tick-label gap) have each been confirmed by standalone compile tests. The full function, exercised end to end on real grouped/aux-data input the way latexDotchart's own examples do, has not yet been compile-tested at that scale.

Examples

Run this code

if (FALSE) {
z <- typstDotchart(c(.1, .2), c('a', 'bbAAb'), xlab = 'This Label',
                   auxdata = c(.1, .2), auxtitle = 'Zcriteria')
typstAsis(z)
}