32 Known Limitations
Gaps in the current Plotje release. None produce crashes on canonical inputs; each is documented and tracked for post-alpha work.
(ns plotje-book.known-limitations
(:require
;; Plotje -- the configuration whose defaults this chapter names
[scicloj.plotje.api :as pj]
;; Kindly -- notebook rendering protocol
[scicloj.kindly.v4.kind :as kind]))Layout and Visuals
Layers that draw the same columns are drawn in one color with no legend entry per layer. A pose with a
pj/lay-point, apj/lay-smoothwith{:stat :linear-model}and apj/lay-smoothwith{:stat :loess}on the same two columns draws two curves that cannot be told apart. Layers that draw different columns are each given a color and a legend entry. Workaround: color each layer explicitly.A scatter plot matrix of many variables at the default
:widthand:heighthas tight panels. Increase:width/:heightor pin:panel-width/:panel-height.Horizontal bars from
(pj/coord :flip)render the first row of data at the bottom of the chart, so a dataset sorted descending (natural “top N” order) produces the biggest bar at the bottom. ggplot2’scoord_flip()also runs bottom to top, in the order of the factor levels rather than of the data. Workaround: give the category axis a:domainin the order to draw, bottom to top. Under(pj/coord :flip)the categories are still the data’s:x, so the scale is written on:x, as in(pj/scale pose :x {:domain ["C" "B" "A"]}), which draws"A"at the top. Sorting the dataset ascending before plotting, as in(tc/order-by data [:value] [:asc]), puts the biggest bar at the top.:fit-text-domainwidens a numeric domain so that text and label marks near its edge are drawn in full. Nothing widens the domain for a mark whose size is in drawing units for another reason: apj/lay-pointgiven a large:sizeat the extreme of its domain is cut at the panel edge, as is a long rug tick. The domain padding (:domain-padding) absorbs this at ordinary radii, and a scale given a wide:range– say(pj/scale pose :size {:range [3 20]})– reaches past it. Workaround: widen the domain withpj/scale.Rotated tick labels are given room at the canvas edges, but not room from one another. Y-tick labels at 90 or -90 (
:y-tick-angle) run along the axis, and a label longer than the space between two ticks is drawn over its neighbours. The room a rotated label is given has a ceiling, a fixed share of the plot’s width or height, so a label longer than that is clipped at the edge. Workaround: shorten the labels, choose another angle, or thin the ticks with:n-ticks.A mark that occupies a band cannot be drawn at a place between two categories.
pj/lay-boxplotandpj/lay-violinrequire a category column and report an error without one;pj/lay-bargiven a written place draws the histogram bar instead, one place wide and centred there, rather than a bar in a band of its own. Workaround: none – a mark between two bands would need a band the axis does not have.Only a straight segment carries an arrow head.
pj/lay-segmenttakes:arrow, as the Cookbook shows;pj/lay-line, which runs through several points, draws a plain stroke and ends bluntly.Nothing moves a label out of the way of another label. Two text marks at nearby
:xand:yvalues are drawn on top of each other, and labelling every point of a dense scatter produces an unreadable pile. Workarounds: label a subset, or separate them by hand with:offset-x/:offset-y. Automatic placement, as in R’sggrepel, is designed but not implemented.A long label at the right edge of a panel costs axis range.
:fit-text-domainmakes room for the label by widening the domain, and nothing else can – there is no way to reserve drawing-space room for labels outside the drawing area. Several sentence-length labels at the line ends can push the axis well past the data. Workarounds: shorten the end labels and put the sentences in a callout, or turn the widening off with{:fit-text-domain false}and accept the clipping.:inplaces a layer in the data or on the panel (:in :drawing-area), and nothing places one on the canvas as a whole. A note outside every panel – beside the legend, or under the title – cannot be placed. Workaround::captionand:subtitlefor text below and above the panels.pj/marginaldraws on:topand:right.:bottomand:leftwould put the strip between the panel and the axis that describes it, so they report an error.pj/marginaladds one marginal to a leaf pose.pj/marginalreturns a composite, and a composite has no single panel to put a second strip beside. For a scatter with a histogram above it and another to its right, write(pj/matrix data [:a nil] [nil :b] {:col-weights [3 1] :row-weights [1 3]}): a panel where a column meetsnildraws that column alone, as a histogram, and the corner where twonils meet is left empty.(pj/marginal pose :top :histogram)draws its tallest bar close to the top of the marginal panel. The value axis is padded by the same fraction any axis is, and the strip is much shorter than the panel, so the gap comes to a few drawing units – which a density hides, since its tail approaches zero, and a histogram does not. Workaround:pj/marginalbuilds a composite whose marginal cell is the first sub-pose for:topand the second for:right, so(update-in m [:poses 0] pj/scale :y {:include n})withnabove the tallest count gives the strip more room over the bars.The pose’s
:colormapping does not reach its marginal. A marginal describes one whole column, so one undivided curve or set of bars is drawn beside however many colored groups the panel carries. Workaround: facet instead of coloring – faceting does reach the marginal, giving one distribution per panel.
The default size and the domain padding named above are configuration values:
(select-keys (pj/config) [:width :height :domain-padding]){:width 600, :height 400, :domain-padding 0.05}Marks
Aesthetic-gate versus mark-consumer asymmetry. Several aesthetics are accepted at the universal pose-mapping gate but consumed only by one or two mark extractors. Setting them on other marks does not vary the picture.
Aesthetic Consumed on Elsewhere :size(a column)lay-pointwarned, and no legend is drawn for it :alpha(a column)lay-pointwarned, and no legend is drawn for it (a written :alpha Nworks on most via:fixed-alpha)numeric (continuous) :colorevery mark drawn once per row a mark drawn once for many rows – a line, an area, a histogram bin, a box – draws one color and prints a warning that the column is not painted on it :tooltip, and the row index written beside itlay-point,lay-interval-hwarned, and no tooltip is drawn Only
lay-pointvaries a radius or an opacity from row to row, so{:size {:column :r :scale false}}– the column’s own values as radii – reports an error on any other layer type, rather than a warning: there is no reading for it at all. The warning and the error both name the:pointmark. The marks that vary a radius or an opacity per row are read from the registry, where each layer type declares what its mark varies under:varies, so an extension that draws a per-row size says so and is named alongsidelay-point.:shapeis not in this table: it is drawn only bylay-point. Passing it to any other layer type prints a warning naming the:pointlayer type, and the setting is ignored.:textis the same, and the warning names the:labeland:textlayer types.Workaround for
:sizeand:alpha: uselay-pointwhere the aesthetic must vary per row. For a numeric:coloron a mark drawn once for many rows, pre-bin the column into categories, or draw the quantity with a mark that stands for one row.A 2D density is computed from all the rows.
lay-density-2dandlay-contourdraw one density per panel, coloured by its own level. Given a:colorcolumn, they warn that the colour is not drawn and keep the density legend. Workaround: facet by the column, as in(pj/facet my-pose :species), so that each panel draws the density of one group.Interaction reaches a reader only through SVG. A tooltip and a brush are behaviours a browser runs over the figure, so a plot rendered to
:bufimg, or saved as a PNG, carries neither. Writing a tooltip or a brush for such a format prints a warning naming the format and the formats that draw interaction, and the figure still renders. Interactivity covers it. Workaround: render to SVG, and save the SVG rather than a PNG where the reader is meant to hover.pj/lay-rule-hrendered under(pj/coord :flip)becomes a vertical line;pj/lay-rule-vbecomes a horizontal line. The mark name still reflects the unflipped semantics. Add a one-line note in the surrounding prose if the chart’s flipped state is non-obvious.pj/lay-linejoins each group’s points in order of their:x, and no built-in layer type joins them in the order of the rows. A connected scatter plot – two measures drawn against each other and joined in time order – or any path that turns back on itself cannot be drawn.:position :dodgedraws no offset onlay-line, and is dropped between the pose and the plan onlay-summary.lay-pointhonours it on a categorical x, and ignores it on a numeric x, which has no bands to divide.lay-bardodges by default, so asking for it there changes nothing rather than failing. Workaround forlay-lineandlay-summary: pre-compute the offsets withtc/group-by, or use:dxto shift a layer by a fraction of its band.Stacked bars don’t split positive and negative values; all-positive data works, but mixed-sign data stacks incorrectly.
pj/lay-tilewith neither:fillnor:colorcounts rows in two-dimensional bins (the:bin2dstat), which needs numeric x and y columns; a categorical axis reports the error “Stat :bin2d requires a numeric column”. Given:fillor:color, a tile draws one cell per row and takes categorical axes – see Troubleshooting.Horizontal value bars (
pj/lay-barwith the category on:y) support plain and dodged layouts, but not:position :stackor:position :fill– stacking accumulates along the y-axis, which is the categorical band for a horizontal bar. Workaround: put the category on:xand add(pj/coord :flip), where stacking works.Bars on a numeric or temporal
:x(pj/lay-barwith both axes numeric or temporal) draw one bar per row at its:xvalue; grouped bars (via:color) overlap rather than dodge, and:position :stackis not applied. Pre-aggregate, or jitter the:xvalues, to separate groups.Value bars (
pj/lay-barwith a value column) cannot use a log scale on the value axis: a bar is measured from zero, so its axis always reaches zero, and a log scale has no reading for zero. Plotje reports an error that names the alternatives – a linear value axis, or a mark that is not measured from a baseline (pj/lay-point,pj/lay-line). Count bars and histograms do support a log axis, as do the other marks that are measured from a baseline:pj/lay-areaandpj/lay-lollipoprest on the panel’s smallest value there, as a count bar does.Rules and bands report an error under
(pj/coord :polar). A polar rule would need to draw as a circle (fixed radius) or a spoke (fixed angle); those shapes are not implemented, and the message names the marks polar does draw. Use Cartesian or flipped coordinates for annotated plots.Large scatters produce large SVGs, since each point is an element of its own. For many thousands of points, use
:format :bufimgfor raster output.LOESS with a confidence band fits the curve again on many resamples of the rows, so it is slow on large data. Subsample large data before smoothing it.
Scales
One pose reads an aesthetic through one scale. Two layers asking for different scales on
:size,:alpha,:coloror:fillreport an error rather than draw, since a plot has one legend per aesthetic. Two layers naming different scales for:xor:yreport an error as well, because a panel has one of each axis. Workaround in every case: put the layers in separate poses withpj/arrange, and write each cell’s scale on that cell. A cell that writes its own scale keeps it and draws its own legend; cells that map the same column and write no scale share one scale and one legend.Facet panels share their scale types.
{:share-scales #{}}gives each panel its own domain, but there is no equivalent for giving one panel a log axis and another a linear one. Workaround:pj/arrangeagain.
Options and Configuration
- The
:widthkey on apj/planresult preserves the user’s original request even when:panel-widthpins the real size – inspect:total-width/:total-heightfor the rendered canvas.
Mixing Keyword and String Column References
- Mapping the same column with a keyword in one place and a string in another (as in
(pj/pose ds {:color :group})then(pj/lay-point :x :y {:color "group"})) is not normalized: the scope hierarchy treats them as different keys. The mismatch reports an error rather than drawing – the spelling that does not match a column name is looked up, found missing, and named alongside the columns the data does carry. The exception is a string that happens to name something the aesthetic can draw:"red"on:coloris that color, so the mapping quietly stops grouping instead. Workaround: pick one form (keyword or string) and use it consistently within a pose.
Integer Column Names
A dataset built without column names gets integer column names, and Plotje reads integer column names wherever a mapping is written:
(pj/lay-point ds {:x 0 :y 1}),(pj/lay-point ds 0 1)and(pj/pose ds {:x 0 :y 1})all plot those two columns, and the derived axis titles read as the names.A number has two possible readings on
:xand:y, and the data decides between them: a number the data carries as a column name is that column, and any other number is a value to place a mark at. So the same code can change meaning on a dataset whose column names differ. Where that matters, write the mapping out in full –{:x {:column 0}}and{:x {:value 0}}are each unambiguous – or rename with(tc/rename-columns ds [:x :y])as shown in the Datasets chapter.The appearance aesthetics work the same way.
{:size 1}reads column 1 where the data has one, and is a radius where it does not;{:size {:value 1}}insists on the radius.
ggplot2 Features Not Yet Implemented
The
:fillaesthetic is currently consumed only bylay-tile(and the:density-2doutput beneathlay-density-2d). On filled marks likelay-bar,lay-area, andlay-violin,:colorpaints the interior; there is no separate stroke aesthetic.The
:linetypeaesthetic (ggplot2’saes(linetype=...)for solid versus dashed lines) is not implemented. Workaround: encode the same distinction via:colorinstead.A layer’s own
:datais not split bypj/facet. The pose’s data is divided among the panels, but a layer carrying its own dataset is drawn whole in every panel, whether or not that dataset has the facet column. ggplot2 divides a layer’s data the same way it divides the plot’s, sogeom_hline(data = means, aes(yintercept = m))puts one line in each panel where Plotje puts all of them in each. Nothing errors; every panel shows every group’s mark. Workaround: build the panels withpj/arrangerather thanpj/facet, so each cell is its own pose with its own layer data.No
after_stat()analog. ggplot2 idioms likegeom_bar(aes(label=after_stat(count)))andgeom_histogram(aes(y=after_stat(density)))reference computed stat values inside aesthetic mappings; Plotje requires a pre-computed column. Workaround: aggregate the data first viatc/group-by+tc/aggregate, then map the count or density column directly.Theme support is shallow versus ggplot2: today the theme map carries
:bg,:grid,:font-size, and a small handful of other keys. Named theme presets (theme_minimal,theme_bw,theme_classic), panel borders, strip text styling, andlegend.positionby coordinate are not yet exposed. Rotating tick labels is available, but as the:x-tick-angleand:y-tick-angleplot options rather than through the theme – see Customization.guides()for per-aesthetic legend control, and a square-root axis (scale_*_sqrt). Both are tracked in the backlog. The axis types are:linear,:logand:categorical. ggplot2’sscale_x_reverse()is a:domainwritten high to low, as in{:domain [100 0]}– see Scales – and a date column gives a date axis without a separate scale. (pj/scale :size {:by :sqrt}is a different setting – it says how a size spreads across the radii, not how an axis is transformed.)