CapstractHelpChart specification

Chart specification

Charts are drawn by Capstract in the default matplotlib style (DejaVu Sans, tab10 colours), so they look like figures produced by the field's usual tooling. Set "style": "pgfplots" for serif type and a boxed axis. A chart is a JSON object, inside a chart block or as a figures entry of kind chart. It must be strict JSON: no comments, no trailing commas.

{
  "type": "line",
  "xlabel": "Dose $d$ (mg)",
  "ylabel": "Accuracy (%)",
  "x": [0, 10, 20, 30, 40, 50],
  "series": [
    { "label": "Placebo", "y": [61.2, 61.0, 61.4, 61.1, 61.3, 61.2], "style": "dashed", "marker": "none" },
    { "label": "Lisdexamfetamine", "y": [61.2, 63.8, 66.1, 67.9, 67.2, 64.0],
      "err": [0.8, 0.7, 0.9, 0.7, 1.1, 1.6], "marker": "o" }
  ],
  "legend": "lower right",
  "grid": false,
  "xscale": "linear", "yscale": "linear",
  "xlim": [0, 50], "ylim": [55, 70],
  "size": [3.3, 2.4],
  "hlines": [{ "y": 61.2, "label": "baseline", "style": "dotted" }],
  "annotations": [{ "x": 30, "y": 67.9, "text": "peak" }],
  "band": false
}
  • type: line (default), scatter, bar or heatmap.
  • x: shared x values for every series, or the categories of a bar chart. Each series may carry its own x instead. A null in y leaves a gap.
  • err: error bars, or a shaded band on line series when "band": true.
  • size: [width, height] in inches; about 3.3 for a column, 6.8 for the full width. Width 1–8.5, height 0.8–10.
  • xlim, ylim: [min, max]. xscale, yscale: linear or log; log axes label powers of ten and draw unlabelled minor ticks, as matplotlib does by default.
  • hlines (y) and vlines (x): reference lines; those with a label appear in the legend.
  • annotations: { "x", "y", "text" } placed just above and to the right of the point.
  • text on the x axis: line and scatter charts accept category labels in x; points sit at evenly spaced positions. xtick_rotation (degrees) rotates long tick labels; bar charts rotate them when neighbouring labels would collide.

Lines and markers

Every line or scatter series can have a line, markers, or both:

Series Line Markers
on a line chart "style": solid (default), dashed, dotted, dashdot, or none "marker", default none
on a scatter chart "style", default none "marker", default o

So { "style": "none", "marker": "o" } puts observed points on a line chart, and { "style": "solid", "marker": "none" } draws a fitted curve on a scatter chart. Markers: `o s ^ v D x

  • none`. A series with no line and no marker is an error.

Legend

"legend": best (the default), upper right, upper left, lower left, lower right, right, center left, center right, lower center, upper center, center, outside or none. With best the legend goes inside the axes where it covers no data, as matplotlib's best does, and above the axes when no place inside is clear. A position you set yourself is kept, and the preview warns when the legend covers data there; a legend too big for the axes goes above them.

Math in labels

Axis labels, titles, legend labels, reference-line labels, annotations, bar categories and heatmap row, column and colour-bar labels accept $...$ math, set as matplotlib's mathtext sets it: Latin letters and lowercase Greek in italic, digits and operators upright.

  • Greek letters, x_i, x^2, x_{ij}^{(k)}, ^\circ (a degree sign: $^\circ$C), primes.
  • \mathrm{…}, \text{…}, \mathit{…}, \mathbf{…}, \operatorname{…}, \mathcal{…}, \mathbb{…}.
  • Operators and relations: \times \cdot \pm \mp \leq \geq \neq \approx \sim \simeq \propto \equiv \ll \gg \to \infty \partial \nabla \sum \int, and more; function names such as \log \exp \sin \max.
  • \frac{a}{b} is set inline as a/b, with parentheses where needed; \sqrt{x} as √x.
  • Accents \hat \bar \tilde \vec \dot; spacing \, \; \quad; \left and \right are ignored.

Anything else is reported in the preview and printed without its backslash. Outside $...$, \% and \$ give % and $; other TeX commands, _ and ^ print literally and are reported.

Heatmaps

{
  "type": "heatmap",
  "rows": ["Morning", "Afternoon", "Evening"],
  "cols": [1, 2, 3, 4],
  "values": [[0.12, 0.40, 0.33, -0.05], [0.25, 0.61, 0.48, 0.10], [-0.30, 0.05, 0.21, 0.44]],
  "colormap": "RdBu",
  "annotate": true,
  "fmt": ".2f",
  "colorbar": "Correlation $r$",
  "vmin": -1, "vmax": 1,
  "xlabel": "Week", "ylabel": "Session"
}

values holds one array per row, each with one value per column (null leaves a cell blank). rows and cols are optional labels, text or numbers, and must match those counts. Heatmaps take no x or series. colormap: viridis (default), magma, Blues, Greys or RdBu. fmt is .Nf, .Ne or .N%. colorbar is a label, or false for none. Set a symmetric vmin/vmax to centre a diverging map on zero.

Panels

{
  "size": [6.8, 2.4],
  "panels": [
    { "type": "line", "xlabel": "Dose (mg)", "ylabel": "Accuracy (%)", "x": [0, 25, 50], "series": [{ "y": [61, 66, 64] }] },
    { "type": "bar", "xlabel": "Arm", "ylabel": "Dropouts", "x": ["Placebo", "Treated"], "series": [{ "y": [3, 5] }] }
  ]
}

Subplots side by side, labelled (a), (b), …; size and style apply to the whole figure. "ncols" sets the number of panels per row: "ncols": 1 stacks them, which suits a figure one column wide (for example "size": [3.4, 4.2]) in a two-column template.

Other notes

  • Series colours default to C0, C1, ... Set "color": "C3" or a hex value to override.
  • Errors in a spec name the field, for example series[1] ("Placebo"): y has 5 values but the shared "x" has 6; fields Capstract does not use are reported and ignored.
  • When a BibTeX database is written inside a JavaScript template literal, avoid LaTeX backtick quotes; write straight double quotes inside a braced field instead.