STILTS-PLOT2PLANE(1)

📦
version 3.5.4 · 5 versions
, in ubuntu stonking

STILTS-PLOT2PLANE(1) — okay bestie, buckle up, this is the plot2plane page and it's a whole ✨era✨ of its own. It's long so we're doing it in chunks. Let's go 💅

✨ NAME ✨

stilts-plot2plane — Draws a plane plot 🎀

🦋 SYNOPSIS 🦋

stilts plot2plane [xpix=<int-value>] [ypix=<int-value>]
                  [insets=<top>,<left>,<bottom>,<right>]
                  [omode=swing|out|cgi|discard|auto]
                  [storage=simple|memory|disk|policy|cache|basic-
                  cache|persistent|parallel] [seq=<suffix>[,...]]
                  [legend=true|false|null] [legborder=true|false]
                  [legopaque=true|false] [legseq=<suffix>[,...]]
                  [legpos=<xfrac,yfrac>] [title=<value>] [auxmap=<map-
                  name>|<color>-<color>[-<color>...]]
                  [auxclip=<lo>,<hi>] [auxflip=true|false]
                  [auxquant=<number>] [auxfunc=log|linear|histogram|...]
                  [auxmin=<number>] [auxmax=<number>] [auxlabel=<text>]
                  [auxcrowd=<factor>] [auxwidth=<pixels>]
                  [auxvisible=true|false|null] [forcebitmap=true|false]
                  [compositor=0..1] [animate=<table>] [afmt=<in-format>]
                  [astream=true|false] [acmd=<cmds>] [parallel=<int-
                  value>] [xscale=linear|log|asinh(<a>)|symlog(<t>,<s>)]
                  [yscale=linear|log|asinh(<a>)|symlog(<t>,<s>)]
                  [xlog=true|false] [ylog=true|false] [xflip=true|false]
                  [yflip=true|false] [xlabel=<text>] [ylabel=<text>]
                  [x2func=<function-of-x>] [y2func=<function-of-y>]
                  [x2label=<text>] [y2label=<text>] [aspect=<number>]
                  [grid=true|false] [xcrowd=<number>] [ycrowd=<number>]
                  [labelangle=horizontal|angled|adaptive]
                  [minor=true|false] [shadow=true|false]
                  [gridcolor=<rrggbb>|red|blue|...] [gridtrans=0..1]
                  [labelcolor=<rrggbb>|red|blue|...]
                  [texttype=plain|antialias|latex] [fontsize=<int-
                  value>] [fontstyle=standard|serif|mono]
                  [fontweight=plain|bold|italic|bold_italic]
                  [xmin=<number>] [xmax=<number>] [xsub=<lo>,<hi>]
                  [ymin=<number>] [ymax=<number>] [ysub=<lo>,<hi>]
                  [navaxes=xy|x|y] [xanchor=true|false]
                  [yanchor=true|false] [zoomfactor=<number>]
                  [leglabelN=<text>] [layerN=<layer-type> <layerN-
                  specific-params>]

Like, yeah, that's a lot of brackets. It's giving "I have options and I'm not afraid to use them" 💅

💖 DESCRIPTION 💖

So plot2plane draws plots on a Cartesian 2-dimensional surface. That's the whole vibe. Flat. Two axes. Iconic. ✨

Positional coordinates come in as x, y pairs, like:

plot2plane layer1=mark in1=cat.fits x1=RMAG y1=RMAG-BMAG

You build up the actual content by naming one or more plot layers with the layer<N> parameter. The N part is a suffix that gets applied to all the parameters affecting that given layer — and bestie, any suffix works here, including the empty string. Live your truth 🫶

The layers available for this plot type are:

  • mark
  • size
  • sizexy
  • xyvector
  • xyerror
  • xyellipse
  • xycorr
  • link2
  • mark2
  • poly4
  • mark4
  • polygon
  • area
  • central
  • lines
  • marks
  • handles
  • yerrors
  • xyerrors
  • statline
  • statmark
  • arrayquantile
  • line
  • linearfit
  • label
  • arealabel
  • contour
  • grid
  • fill
  • quantile
  • histogram
  • kde
  • knn
  • densogram
  • gaussian
  • function

💅 OPTIONS 💅

  • xpix=<int-value> — How big the output image is in the X direction, in pixels. Heads up: this count includes the space for axis labels, padding and all the other decoration hanging around outside the plot area itself. See also insets 💖
  • ypix=<int-value> — Same deal but for the Y direction, in pixels. Also includes space for axis labels, padding and other decoration outside the plot area itself. See also insets 🦋
  • insets=<top>,<left>,<bottom>,<right> — Sets how much space, in pixels, sits around the actual plotting area. That space is where axis labels and other decorations go, and whatever's left over becomes an empty border.

The size and position of the actual plotting area is decided by this parameter together with xpix and ypix.

The value is 4 comma separated integers: <top>,<left>,<bottom>,<right>. Any or all of these can be left blank, and if you do that, the matching margin gets calculated automatically based on how much room is actually needed. 🧚

  • omode=swing|out|cgi|discard|auto — Picks how the drawn plot gets output, see SUN/256.
    • swing: the plot shows up in a window on the screen. This one is "live" — you can resize it and (except for old-style plots) navigate around it with mouse actions exactly like you would for plots in TOPCAT. main character energy, fr.
    • out: the plot gets written to a file given by out, using the graphics format given by ofmt.
    • cgi: the plot gets written in a way that's suitable for CGI use direct from a web server. The output is in the graphics format given by ofmt, with a suitable "Content-type" declaration in front of it.
    • discard: the plot gets drawn, then thrown away. No output at all. it's giving ghosting 💀
    • auto: behaves as swing or out mode depending on whether the out parameter is present.
  • storage=simple|memory|disk|policy|cache|basic-cache|persistent|parallel — Decides how data gets accessed while the plot is being constructed. Two big flavours here: cached or not cached. 😌

If there's no caching, rows are read sequentially from the input table(s) you specified every single time they're needed. That usually means a small resource footprint (though honestly that can depend on how the table is specified), and it makes sense if the data only needs scanning once, or maybe if the table is enormous.

If you do use caching, the data you need is read once from the specified input table(s), then prepared and cached before any plotting happens, and the plotting all runs off that cached data. For big tables this can eat a serious amount of storage, but it's usually the more sensible (read: faster) move if the data is going to get scanned multiple times. There are various options for where the cache lives.

The options are:

  • simple: no caching, data read directly from input table
  • memory: cached to memory; OutOfMemoryError possible for very large plots 😭
  • disk: cached to disk
  • policy: cached using the application-wide default storage policy, which is usually adaptive (memory/disk hybrid)
  • persistent: cached to persistent files on disk, in the system temporary directory (defined by system property java.io.tmpdir). If you use this, plot data gets stored on disk in a way that means it can be re-used between STILTS invocations, so data preparation can be skipped on subsequent runs. Note however it can leave potentially large files sitting in your temporary directory. 🙈
  • cache: synonym for memory (backward compatibility)
  • basic-cache: a dumber version of memory (no optimisation for constant-valued columns)
  • parallel: experimental version of the memory-based cache that reads into the cache in parallel for large files. This makes the plot faster to prepare, but interaction is a bit slower and sequence-dependent attributes of the plot may not come out right. This experimental option may be withdrawn or modified in future releases. ⚠️

The default value is memory if a live plot is being generated (omode=swing), since in that case the plot needs to be redrawn every time the user does a plot navigation action or resizes the window, or if animations are being produced. Otherwise (e.g. output to a graphics file) the default is simple.

  • seq=<suffix>[,...] — A comma-separated list of layer suffixes that sets the order layers get drawn on the plot. This matters because it decides which symbols get plotted on top of — and therefore potentially obscure — which other ones. 👑

When you specify a plot, you can have multiple layers, each introduced by a layer<N> parameter, where <N> is a different (arbitrary) suffix labelling that layer, and it gets appended to all the parameters specific to defining that layer.

By default the layers are drawn in the order the layer* parameters appear on the command line. But if you set this parameter, each comma-separated element is read as a layer suffix, giving the ordered list of layers to plot. Every element of the list must be a suffix with a corresponding layer parameter — though missing or repeated elements are allowed. no cap.

  • legend=true|false|null — Whether to draw a legend or not. If you don't supply a value, the decision gets made automatically: a legend is drawn only if it would have more than one entry. ✨
  • legborder=true|false — If true, a line border gets drawn around the legend.
  • legopaque=true|false — If true, the legend's background is opaque, so the legend obscures any plot components behind it. Otherwise it's transparent. 🫧
  • legseq=<suffix>[,...] — Decides which layers are represented in the legend (if there is one) and in what order they show up. The legend has a line for each layer label (that's whatever the leglabelN parameter says). If multiple layers share the same label, they all contribute to the same entry in the legend, with the style icons plotted over each other. The value of this parameter is a comma-separated sequence of layer suffixes, and that's what determines the order the legend entries appear in. Layers whose suffixes are missing from this list don't show up in the legend at all. 👻

If you don't supply a value (that's the default), the sequence is the same as the layer plotting sequence (see seq).

  • legpos=<xfrac,yfrac> — Sets the internal position of the legend on the plot. The value is a comma-separated pair giving the X and Y positions of the legend within the plotting bounds, so for instance "0.5,0.5" puts the legend right in the middle of the plot. If you don't supply a value, the legend appears outside the plot boundary. 💖
  • title=<value> — The text of a title to be displayed at the top of the plot. If it's null (the default), no title is shown and there's more space for the graphics. 🎀
  • auxmap=<map-name>|<color>-<color>[-<color>...] — Color map used for Aux axis shading. 🌈

A mixed bag of colour ramps are available, and they're all listed in SUN/256: inferno, magma, plasma, viridis, cividis, cubehelix, sron, rainbow, rainbow2, rainbow3, pastel, cosmic, ember, gothic, rainforest, voltage, bubblegum, gem, chroma, sunset, neon, tropical, accent, gnuplot, gnuplot2, specxby, set1, paired, hotcold, guppy, iceburn, redshift, pride, rdbu, piyg, brbg, cyan-magenta, red-blue, brg, heat, cold, light, greyscale, colour, standard, bugn, bupu, orrd, pubu, purd, painbow, huecl, infinity, hue, intensity, rgb_red, rgb_green, rgb_blue, hsv_h, hsv_s, hsv_v, yuv_y, yuv_u, yuv_v, scale_hsv_s, scale_hsv_v, scale_yuv_y, mask, blacker, whiter, transparency. okay but heads up bestie — a lot of these, rainbow-likes included, are like... deeply frowned upon by the visualisation community. 💀 They just are. Don't shoot the messenger.

You can ALSO cook up your own custom colour map all by yourself ✨ — just give a sequence of colour names separated by minus sign (-) characters. When you do that, the ramp is a linear interpolation between each pair of colours you named, using the same syntax as when you're specifying a colour value. So for example yellow-hotpink-#0000ff would shade from yellow, through hot pink, all the way to blue. iconic

  • auxclip=<lo>,<hi> — sets a subrange of the colour ramp to use for Aux shading. You give it a low/high comma-separated pair of two numbers between 0 and 1. If you use the full range 0,1, the whole range of colours from your chosen shader gets used. But if you say 0,0.5, only the colours at the left hand end of the ramp show up. If you leave it at the null (default) value, a default clip is used — and that generally covers most or all of the range 0-1, except for colour maps that fade to white, where a small chunk of the lower end may get cut so that every colour stays visually distinguishable from a white background. ngl that default is usually the vibe if your colour map is hanging out with something like a scatter plot, where markers sit against a white background. But for something like a density map where the whole plotting area is tiled with colours from the map? You probably wanna supply the whole range 0,1 explicitly.
  • auxflip=true|false — if true, the colour map on the Aux axis gets reversed. 🔄
  • auxquant=<number> — lets you quantise the colour map used for the Aux axis. Give it an integer value N and the colour map gets viewed as N discrete evenly-spaced levels, so only N different colours show up in the plot. This is how you get a contour-like effect, and it may make it easier to trace the boundaries of regions of interest by eye. 👀 If you leave it blank, the colour map is nominally continuous — though in practice it may be quantised to a medium-sized number like 256.
  • auxfunc=log|linear|histogram|... — defines the way values in the Aux range get mapped to the selected colour ramp. The available options are:
    • log: Logarithmic scaling, positive values only
    • linear: Linear scaling
    • histogram: Scaling follows data distribution, with linear axis
    • histolog: Scaling follows data distribution, with logarithmic axis, positive values only
    • asinh: Asinh scaling, wide dynamic range for both positive and negative values
    • sqrt: Square root scaling
    • square: Square scaling
    • acos: Inverse cosine Scaling
    • cos: Cosine Scaling

For all these options, the full range of valid data values is used, and displayed on the colour bar if applicable. Note that the logarithmic-based options Log and HistoLog will ignore non-positive values. The Linear, Log, Square and Sqrt options just apply the named function to the full data range. The histogram options, on the other hand, use a scaling function that corresponds to the actual distribution of the data, so that there are about the same number of points (or pixels, or whatever's being scaled) of each colour. ✨ The histogram options are somewhat more expensive, but they can be a good choice if you're exploring data whose distribution is unknown or not well-behaved over its min-max range. The Histogram and HistoLog options both assign the colours in the same way, but they display the colour ramp with linear or logarithmic annotation respectively; the HistoLog option also ignores non-positive values.

  • auxmin=<number> — minimum value of the data coordinate on the Aux axis. This sets the value before any subranging is applied. If you don't supply it, the value gets determined from the plotted data.
  • auxmax=<number> — maximum value of the data coordinate on the Aux axis. This sets the value before any subranging is applied. If you don't supply it, the value gets determined from the plotted data.
  • auxlabel=<text> — sets the label used to annotate the aux axis, if it's visible.
  • auxcrowd=<factor> — determines how closely the tick marks are spaced on the Aux axis, if visible. Default value is 1, meaning normal crowding. Bigger values = more ticks, smaller values = fewer ticks. But tick marks won't be spaced so closely that the labels overlap each other, so if you want very closely spaced marks you may need to reduce the font size as well.
  • auxwidth=<pixels> — determines the lateral size of the aux colour ramp, if visible, in pixels.
  • auxvisible=true|false|null — determines whether the aux axis colour ramp is displayed alongside the plot. If you don't supply it (the default), the aux axis will be visible when aux shading is used in any of the plotted layers. 🫶
  • forcebitmap=true|false — affects whether rendering of the data contents of a plot (though not axis labels etc) is always done to an intermediate bitmap rather than, where possible, being painted using graphics primitives. It's a rather arcane setting, but lowkey it may still have noticeable effects on the appearance and size of an output graphics file, as well as plotting time. For some types of plot (e.g. shadingN=auto or shadingN=density) it'll have no effect, since this kind of rendering happens in any case.

When writing to vector graphics formats (PDF and PostScript), setting it true will force the data contents to be bitmapped. This may make the output less beautiful (round markers will no longer be perfectly round 💀), but it may result in a much smaller file if there are very many data points.

When writing to bitmapped output formats (PNG, GIF, JPEG, ...), it fixes shapes to be the same as seen on the screen rather than be rendered at the mercy of the graphics system, which sometimes introduces small distortions.

  • compositor=0..1 — defines how multiple overplotted partially transparent pixels get combined to form a resulting colour. The way this is used depends on the details of the specified plot.

Currently, this parameter takes a "boost" value in the range 0..1. If the value is zero, saturation semantics are used: RGB colours are added in proporition to their associated alpha value until the total alpha is saturated (reaches 1), after which additional pixels have no further effect. For larger boost values, the effect is similar, but any non-zero alpha in the output gets boosted to the given minimum value. The effect of this is that even very slightly populated pixels can be visually distinguished from unpopulated ones — which may not be the case for saturation composition.

  • animate=<table> — if not null, this parameter causes the command to create a sequence of plots instead of just one. The parameter value is a table with one row for each frame to be produced. Columns in the table are interpreted as parameters which may take different values for each frame; the column name is the parameter name, and the value for a given frame is its value from that row. Animating like this is considerably more efficient than invoking the STILTS command in a loop. periodt

The location of the animation control table. This may take one of the following forms:

  • A filename.
  • A URL.
  • The special value -, meaning standard input. In this case the input format must be given explicitly using the afmt parameter. Note that not all formats can be streamed in this way.
  • A scheme specification of the form :<scheme-name>:<scheme-args>.
  • A system command line with either a < character at the start, or a | character at the end (<syscmd or syscmd|). This executes the given pipeline and reads from its standard output. This will probably only work on unix-like systems.

In any case, compressed data in one of the supported compression formats (gzip, Unix compress or bzip2) will be decompressed transparently. 🦋

  • afmt=<in-format> — specifies the format of the animation control table as specified by parameter animate. The known formats are listed in SUN/256. This flag can be used if you know what format your table is in. If it has the special value (auto) (the default), then an attempt will be made to detect the format of the table automatically. 🤖 This can't always be done correctly though — in which case the program will exit with an error explaining which formats were attempted. This parameter is ignored for scheme-specified tables.
  • astream=true|false — set this to true and the animation control table you picked with animate gets read as a stream 🌊. You must hand over the afmt parameter when you do this, no exceptions bestie. Depending on which operations you're running and your processing mode, this may genuinely make the read fail 😭 (sometimes it's just necessary to read the table more than once, it's giving needy). You don't normally need to set this flag — in most cases the data will be streamed automatically if that's the best thing to do, she's self-aware like that. But it can sometimes mean less resource usage when you're processing large files in certain formats (such as VOTable). Heads up: this parameter is ignored for scheme-specified tables. 💅
  • acmd=<cmds> — tells stilts what processing to do on the animation control table named by the animate parameter, and it happens before any other processing takes place. The value is one or more of the filter commands described in SUN/256. Give more than one and you separate them with semicolon characters (";"). You can repeat this parameter multiple times on the same command line to build up a whole list of processing steps — the sequence of commands you give in this way defines the processing pipeline that gets performed on the table. ✨

You can also supply the commands from an external file using the indirection character '@'. So a value of "@filename" causes the file filename to be read for a list of filter commands to execute. Commands in that file may be separated by newline characters and/or semicolons, and lines that are blank or that start with a '#' character are ignored. A backslash character '\fR' at the end of a line joins it with the following line. 🫶

  • parallel=<int-value> — decides how many threads run in parallel when animation output is being produced. Only used if you supplied the animate parameter. The default value is the number of processors apparently available to the JVM. Multitasking queen 👑
  • xscale=linear|log|asinh(<a>)|symlog(<t>,<s>) — defines how data maps to graphical coordinates on the X axis. Your options are:
    • linear: Linear scale
    • log: Logarithmic scale
    • asinh: Scaling based on the inverse hyperbolic sin function. This is approximately linear near the origin, and approximately logarithmic far away from it. It has one parameter, the "linear width" a, which controls how far the linear-like region extends, and it must be strictly positive. The function is x->asinh(x/a).
    • symlog: Symmetric logarithmic scale. This is linear near the origin, and positive/negative logarithmic for larger values. It has two parameters, t (a.k.a. linthresh) and s (a.k.a. linscale). Both parameters must be strictly positive. The linear region is in the range -t<x<+t, and the graphical extent of the region from the origin to t is the same as s decades in the logarithmic region.

For those options that have parameters, the values go after the name in brackets, e.g. "symlog(10,0.5)". If the parameters are missing (e.g. "symlog") some default values are used. no cap.

The linear and log options should be self-explanatory, bestie. symlog and asinh let you plot over a wide dynamic range like log, but unlike log they can accommodate negative as well as positive values 🔥. In both cases scaling near the origin is more or less linear (like x), and scaling far from the origin is more or less logarithmic (like log(x) or -log(-x)). The symlog option simply switches between the two regimes at a given threshold, while asinh transitions smoothly. These options were copied from the equivalent functionality in matplotlib — we love a collab. 💜

  • yscale=linear|log|asinh(<a>)|symlog(<t>,<s>) — defines how data maps to graphical coordinates on the Y axis. Your options are:
    • linear: Linear scale
    • log: Logarithmic scale
    • asinh: Scaling based on the inverse hyperbolic sin function. This is approximately linear near the origin, and approximately logarithmic far away from it. It has one parameter, the "linear width" a, which controls how far the linear-like region extends, and it must be strictly positive. The function is x->asinh(x/a).
    • symlog: Symmetric logarithmic scale. This is linear near the origin, and positive/negative logarithmic for larger values. It has two parameters, t (a.k.a. linthresh) and s (a.k.a. linscale). Both parameters must be strictly positive. The linear region is in the range -t<x<+t, and the graphical extent of the region from the origin to t is the same as s decades in the logarithmic region.

For those options that have parameters, the values go after the name in brackets, e.g. "symlog(10,0.5)". If the parameters are missing (e.g. "symlog") some default values are used.

The linear and log options should be self-explanatory. symlog and asinh let you plot over a wide dynamic range like log, but unlike log they can accommodate negative as well as positive values. In both cases scaling near the origin is more or less linear (like x), and scaling far from the origin is more or less logarithmic (like log(x) or -log(-x)). The symlog option simply switches between the two regimes at a given threshold, while asinh transitions smoothly. These options were copied from the equivalent functionality in matplotlib. 🌈

ngl, xscale and yscale are basically twins — same brain, different axis. 💅
  • xlog=true|false — if false (the default) the scale on the X axis is linear; if true it's logarithmic.
⚠️ Note this option is deprecated in favour of the xscale option, which offers more flexible axis scaling options. She's retired bestie, use the new one.
  • ylog=true|false — if false (the default) the scale on the Y axis is linear; if true it's logarithmic.
⚠️ Note this option is deprecated in favour of the yscale option, which offers more flexible axis scaling options. Same energy, also retired.
  • xflip=true|false — if true, the scale on the X axis will increase in the opposite sense from usual (e.g. right to left rather than left to right). Chaos mode on the X axis 🔄
  • yflip=true|false — if true, the scale on the Y axis will increase in the opposite sense from usual (e.g. right to left rather than left to right).
  • xlabel=<text> — gives a label to be used for annotating axis X. A default value based on the plotted data will be used if no value is supplied. label your axes bestie, it's the bare minimum 🎀
  • ylabel=<text> — gives a label to be used for annotating axis Y. A default value based on the plotted data will be used if no value is supplied.
  • x2func=<function-of-x> — defines a secondary X axis in terms of the primary one. If a secondary axis is defined this way, then the axis opposite the primary one (i.e. on the top side of the plot) will be annotated with the appropriate tickmarks. ✨

The value of this parameter is an algebraic expression in terms of the variable x giving the value on the secondary X axis corresponding to a given value on the primary X axis.

For instance, if the primary X axis represents flux in Jansky, then supplying the expression "2.5*(23-log10(x))-48.6" (or "janskyToAb(x)") would annotate the secondary X axis as AB magnitudes. iconic behaviour tbh.

The function you supply should be monotonic and reasonably well-behaved, otherwise the secondary axis annotation may not work well. The application will attempt to make a sensible decision about whether to use linear or logarithmic tick marks.

  • y2func=<function-of-y> — defines a secondary Y axis in terms of the primary one. If a secondary axis is defined this way, then the axis opposite the primary one (i.e. on the right side of the plot) will be annotated with the appropriate tickmarks.

The value of this parameter is an algebraic expression in terms of the variable y giving the value on the secondary Y axis corresponding to a given value on the primary Y axis.

For instance, if the primary Y axis represents flux in Jansky, then supplying the expression "2.5*(23-log10(y))-48.6" (or "janskyToAb(y)") would annotate the secondary Y axis as AB magnitudes.

The function you supply should be monotonic and reasonably well-behaved, otherwise the secondary axis annotation may not work well. The application will attempt to make a sensible decision about whether to use linear or logarithmic tick marks. 🧚

  • x2label=<text> — provides a string that will label the secondary X axis. This appears on the opposite side of the plot to the X axis itself. a little annotation moment 💖
  • y2label=<text> — provides a string that will label the secondary Y axis. This appears on the opposite side of the plot to the Y axis itself.
  • aspect=<number> — ratio of the unit length on the X axis to the unit length on the Y axis. Set it to 1 and the space will be isotropic. If not set (the default) the ratio will be determined by the given or calculated data bounds on both axes and the shape of the plotting region. geometry served 💅
  • grid=true|false — if true, grid lines are drawn on the plot at positions determined by the major tick marks. If false, they are absent. grid lines are a vibe, lowkey essential ✨
  • xcrowd=<number> — determines how closely the tick marks are spaced on the X axis. The default value is 1, meaning normal crowding. Larger values result in more ticks, and smaller values result in fewer ticks. Tick marks will not however be spaced so closely that the labels overlap each other, so to get very closely spaced marks you may need to reduce the font size as well. she has boundaries, respect them 🙈
  • ycrowd=<number> — determines how closely the tick marks are spaced on the Y axis. The default value is 1, meaning normal crowding. Larger values result in more ticks, and smaller values result in fewer ticks. Tick marks will not however be spaced so closely that the labels overlap each other, so to get very closely spaced marks you may need to reduce the font size as well.
  • labelangle=horizontal|angled|adaptive — this one controls which way your numeric axis labels are facing bestie. Normally labels just sit horizontal on both the horizontal and the vertical axis, but this lets you angle them, which can fit way more labels onto the horizontal axis — especially when the labels are long or you asked for a high crowding factor. 💅

Heads up though: the adaptive option is currently not perfect, and sometimes it lowkey messes up the border placement. Not a vibe, just the truth. 🙈

The options are:

  • horizontal: axis labels are horizontal
  • angled: axis labels are angled
  • adaptive: axis labels are horizontal if possible, but angled if necessary to fit more in
  • minor=true|false — if true, minor tick marks get painted along the axes right alongside the major ones ✨. Slight catch: minor tick marks do not have grid lines attached to them. No grid lines for the little guys.
  • shadow=true|false — if true and no secondary axis is in use, then tick marks without numeric labels get painted along the axis opposite the primary one, so the whole plot has tick marks on every edge, not just the labeled ones 🎀. But if a secondary axis is in use, this setting just gets ignored. Sorry babe.
  • gridcolor=<rrggbb>|red|blue|... — the color of the plot grid, given either by name or as a hexadecimal RGB value 🌈.

The standard plotting colour names are red, blue, green, grey, magenta, cyan, orange, pink, yellow, black, light_grey, white. But lowkey there are sooo many other common colour names it understands — too many to list here fr. The list currently contains the colour names understood by most web browsers, everything from AliceBlue to YellowGreen, listed e.g. in the Extended color keywords section of the CSS3 standard.

Or you can drop a six-digit hexadecimal number RRGGBB, optionally prefixed with # or 0x, giving the red, green and blue intensities — e.g. ff00ff, #ff00ff or 0xff00ff for magenta. ✨

  • gridtrans=0..1 — transparency of grid lines that may be drawn over the plot. The range is 0 (opaque) to 1 (invisible). This value is 1-alpha. iykyk.
  • labelcolor=<rrggbb>|red|blue|... — the color of axis labels and other plot annotations, given by name or as a hexadecimal RGB value 💜.

The standard plotting colour names are red, blue, green, grey, magenta, cyan, orange, pink, yellow, black, light_grey, white. And again, many other common colour names (too many to list here) are also understood. The list currently contains those colour names understood by most web browsers, from AliceBlue to YellowGreen, listed e.g. in the Extended color keywords section of the CSS3 standard.

Alternatively, a six-digit hexadecimal number RRGGBB may be supplied, optionally prefixed by # or 0x, giving red, green and blue intensities, e.g. ff00ff, #ff00ff or 0xff00ff for magenta. 💖

  • texttype=plain|antialias|latex — determines how label text gets turned into characters on the plot 👑. plain and antialias both take the text at face value, but antialias smooths the characters. LaTeX interprets the text as LaTeX source code and typesets it accordingly.

When you're not using LaTeX, antialiased text usually looks nicer, but it can be perceptibly slower to plot. And at time of writing, on MacOS antialiased text seems to be required to stop the writing coming out upside-down for non-horizontal text (MacOS java bug) 😭💀.

  • fontsize=<int-value> — size of the text font in points.
  • fontstyle=standard|serif|mono — font style for text 🎀.

The available options are:

  • standard
  • serif
  • mono
  • fontweight=plain|bold|italic|bold_italic — font weight for text ✨.

The available options are:

  • plain
  • bold
  • italic
  • bold_italic
  • xmin=<number> — minimum value of the data coordinate on the X axis. This sets the value before any subranging is applied. If you don't supply it, the value gets determined from the plotted data.
  • xmax=<number> — maximum value of the data coordinate on the X axis. Also sets the value before any subranging is applied, and again, if not supplied it comes from the plotted data.
  • xsub=<lo>,<hi> — defines a normalised adjustment to the data range of the X axis. You give it a comma-separated pair of two numbers: the lower and upper bounds of the range of of interest respectively (yes, "of of", we said what we said). This sub-range is applied to the data range that would otherwise be used, either automatically calculated or explicitly supplied; zero corresponds to the lower bound and one to the upper.

The default value 0,1 therefore has no effect. But you could restrict the range to its lower half with the value 0,0.5. Slay.

  • ymin=<number> — minimum value of the data coordinate on the Y axis. Sets the value before any subranging is applied, and if not supplied, it's determined from the plotted data.
  • ymax=<number> — maximum value of the data coordinate on the Y axis. Same deal — before any subranging, and from the data if you don't supply it.
  • ysub=<lo>,<hi> — defines a normalised adjustment to the data range of the Y axis. Comma-separated pair of two numbers, lower and upper bounds of the range of of interest respectively. This sub-range is applied to the data range that would otherwise be used, either automatically calculated or explicitly supplied; zero corresponds to the lower bound and one to the upper.

The default value 0,1 therefore has no effect. The range could be restricted to its lower half with the value 0,0.5. 🦋

  • navaxes=xy|x|y — determines which axes are affected by the interactive navigation actions (pan and zoom) 🫶. The default is xy, meaning the various mouse gestures give you panning and zooming in both the X and Y directions. But set it to (for instance) x and the mouse will only let you pan and zoom horizontally, with the vertical extent fixed. Main character behavior honestly.
  • xanchor=true|false — if true, zoom actions work such that the zero point on the X axis stays in the same position on the plot. Pinned. 📌
  • yanchor=true|false — if true, zoom actions work such that the zero point on the Y axis stays in the same position on the plot.
  • zoomfactor=<number> — sets how much the plot view zooms in or out for each unit of mouse wheel movement. A value of 1 means mouse wheel zooming has no effect. A higher value means the mouse wheel zooms faster, and a value nearer 1 means it zooms slower. Values below 1 are not permitted 🚫.
  • leglabelN=<text> — sets the presentation label for the layer with a given suffix. This is the text displayed in the legend, if there is one. Multiple layers may use the same label, in which case they get combined into a single legend entry 👑.

If no value is supplied (the default), the suffix itself is used as the label.

  • layerN=<layer-type> <layerN-specific-params> — selects one of the available plot types for layerN ✨. A plot consists of a plotting surface, set up using the various unsuffixed parameters of the plotting command, plus zero or more plot layers. Each layer is introduced by a parameter named layer<N> where the suffix <N> is a label identifying the layer, and it gets appended to all the parameter names that configure that layer. Suffixes may be any string, including the empty string. (Yes, the empty string counts, iconic.)

This parameter may take one of the following values, described in more detail in SUN/256:

  • mark
  • size
  • sizexy
  • xyvector
  • xyerror
  • xyellipse
  • xycorr
  • link2
  • mark2
  • poly4
  • mark4
  • polygon
  • area
  • central
  • lines
  • marks
  • handles
  • yerrors
  • xyerrors
  • statline
  • statmark
  • arrayquantile
  • line
  • linearfit
  • label
  • arealabel
  • contour
  • grid
  • fill
  • quantile
  • histogram
  • kde
  • knn
  • densogram
  • gaussian
  • function

Each of these layer types comes with a list of type-specific parameters to define the details of that layer, including some or all of the following groups:

  • input table parameters (e.g. inN, icmdN)
  • coordinate params referring to input table columns (e.g. xN, yN)
  • layer style parameters (e.g. shadingN, colorN)

Every parameter notionally carries the same suffix N. However, if the suffix isn't present, the application will try looking for a parameter with the same name with no suffix instead. So basically: if several layers share the same value for a given parameter (like input table), you can supply it using one unsuffixed parameter and save yourself from writing a whole pile of identical suffixed ones. Bestie efficiency 💖.

👀 SEE ALSO ✨

If the package stilts-doc is installed, the full documentation SUN/256 is available in HTML format:

file:///usr/share/doc/stilts/sun256/index.html

📌 VERSION 💅

STILTS version 3.5.4-debian

This is the Debian version of Stilts, which lack the support of some file formats and network protocols. For differences see:

file:///usr/share/doc/stilts/README.Debian

👑 AUTHOR 🌸

Mark Taylor (Bristol University)

okay that's the whole thing bestie, we ate and left no crumbs 🫶 this was STILTS version 3.5.4-debian, dated Mar 2017, and the man page is STILTS-PLOT2PLANE(1) — go make some gorgeous plots fr fr ✨💖

📦 where this page comes from