STILTS-PLOT2CORNER(1)

📦
version 3.5.4 · 3 versions
, in ubuntu stonking

💖 STILTS-PLOT2CORNER 💖

okay bestie, welcome to stilts-plot2corner — the Stilts command that draws a whole matrix of plane plots. yes, a matrix. it's giving graph-paper glamour. 🎀

✨ NAME ✨

stilts-plot2corner — draws a matrix of plane plots. that's the whole vibe. 💅

🌈 SYNOPSIS 🌈

stilts plot2corner [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>] [nvar=<int-value>]
                   [matrixformat=<value>] [cellgap=<int-value>]
                   [squares=true|false]
                   [xKscale=linear|log|asinh(<a>)|symlog(<t>,<s>)]
                   [xlog=true|false] [ylog=true|false]
                   [xKflip=true|false] [xKlabel=<text>]
                   [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]
                   [xKmin=<number>] [xKmax=<number>] [xKsub=<lo>,<hi>]
                   [navaxes=xy|x|y] [xKanchor=true|false]
                   [zoomfactor=<number>] [leglabelN=<text>]
                   [layerN=<layer-type> <layerN-specific-params>]

🌸 DESCRIPTION 🌸

okay so plot2corner takes a bunch of quantities and shows you how they all relate to each other. it draws a scatter-like plot of every pair of coordinates, and/or a histogram-like plot of every single coordinate, and then it lays all of those plots out on a square grid (half of one or all of one, your call). the horizontal coordinates of every plot in a column line up, and the vertical coordinates of every plot in a row line up too. so it's all neat and aligned and honestly kind of iconic. ✨

  • the single-coordinate (histogram-like) plots go on the diagonal.
  • the coordinate-pair (scatter-plot-like) plots go off the diagonal.

by default you only see the diagonal and the sub-diagonal part of the resulting plot matrix, because the plots above the diagonal are literally equivalent to the ones below it — like, why draw the same thing twice? but this is configurable if you're feeling extra.

this whole representation has many names: a corner plot, a scatter plot matrix, a splom, or a pairs plot. same girl, different outfits. 👑

in principle you can compare any number of quantities at once like this, but depending on the output format, if you try to use too many the individual plots can get too small to actually be useful. tragic, but true. 💀

the number D of quantities to compare (aka the dimensionality of the space you're plotting 2- and 1-dimensional projections from) is set by the nvar parameter. each specified layer then needs D positional coordinates, which you give via the parameters x1, x2, ... xD. the resulting grid of plots has a linear dimension of D if there are histogram-like layers in the mix, or D-1 if there are only scatter-plot-like layers. and it's not just the positional coordinate parameters xK themselves — some of the other parameters are indexed by the coordinate index K too, for instance xKlog, xKflip, xKmin and xKmax. iykyk. 🦋

you add content to the plot by specifying one or more plot layers with the layerN parameter. the N part is a suffix that gets applied to all the parameters affecting that given layer; any suffix may be used, including the empty string. the available layers for this plot type are: mark, line, linearfit, label, contour, grid, fill, quantile, histogram, kde, knn, densogram, gaussian, function. periodt. 💖

💅 OPTIONS 💅

  • xpix=<int-value> — the size of the output image in the X direction, in pixels. heads up, this includes the space for any axis labels, padding, and other decoration outside the plot area itself. see also insets. 📏
  • ypix=<int-value> — the size of the output image in the Y direction, in pixels. same deal: this includes space for axis labels, padding and other decoration outside the plot area itself. see also insets. 📐
  • insets=<top>,<left>,<bottom>,<right> — defines how much space in pixels sits around the actual plotting area. that space is where axis labels and other decorations live, and anything left over just becomes an empty border.

the size and position of the actual plotting area is determined by this parameter along with xpix and ypix.

the value is 4 comma separated integers: <top>,<left>,<bottom>,<right>. you can leave any or all of them blank, and in that case the corresponding margin gets calculated automatically based on how much space is actually needed. 🎀

  • omode=swing|out|cgi|discard|auto — decides how the drawn plot gets output. see SUN/256 for the lore.
    • swing: the plot is displayed in a window on the screen. this plot is "live" — it can be resized and (except for old-style plots) navigated around with mouse actions exactly like 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 suitable for CGI use directly from a web server. the output is in the graphics format given by ofmt, preceded by a suitable "Content-type" declaration.
    • discard: the plot is drawn, but then discarded. there is no output. it's giving ghosting. 💀
    • auto: behaves as swing or out mode depending on the presence of the out parameter.
  • storage=simple|memory|disk|policy|cache|basic-cache|persistent|parallel — decides the way data is accessed when constructing the plot. there are two main options here: cached or not cached.

if no caching is used, rows are read sequentially from the specified input table(s) every single time they're required. this generally needs a small resource footprint (although that can depend on how the table is specified), and it makes sense if the data only needs to be scanned once — or maybe if the table is very large.

if caching is used, the required data is read once from the specified input table(s), then prepared and cached before any plotting happens, and all the plots are done using this cached data. this can use a significant amount of storage for large tables, but it's usually more sensible (read: faster) if the data is going to need to be scanned multiple times. there are various options for cache storage.

the options are:

  • simple: no caching, data read directly from the 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 avoided on subsequent runs. but note it can leave potentially large files hanging out in your temporary directory. 🫣
  • cache: synonym for memory (backward compatibility)
  • basic-cache: the 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 performs plot navigation actions or resizes the window — or if animations are being produced. otherwise (say, output to a graphics file) the default is simple.
  • seq=<suffix>[,...] — holds a comma-separated list of layer suffixes that determines the order in which layers get drawn on the plot. this can affect which symbols get plotted on top of — and therefore potentially obscure — which other ones. stacking order is real. 🔥

when you specify a plot, multiple layers may be specified, each one introduced by a parameter layer<N>, 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 on the plot in the order in which the layer* parameters appear on the command line. but if this parameter is specified, each comma-separated element is interpreted as a layer suffix, giving the ordered list of layers to plot. every element of that list must be a suffix with a corresponding layer parameter, though missing or repeated elements are allowed. 🌈

  • legend=true|false|null — whether to draw a legend or not. if you supply no value, the decision is made automatically: a legend is only drawn if it would have more than one entry. so shy. 🙈
  • legborder=true|false — if true, a line border is drawn around the legend. frame it, bestie. 🖼️
  • legopaque=true|false — if true, the background of the legend is opaque, and the legend obscures any plot components behind it. otherwise it's transparent, and everything shows through. 👀
  • legseq=<suffix>[,...] — okay so this one picks which layers get to show up in the legend (if there even is a legend) and in what order they strut in. 💅 The legend gets one line per layer label (and those labels come from the leglabelN parameter, iykyk). If a bunch of layers share the same label, bestie they all collapse into the same legend entry, with their style icons stacked right on top of each other. The value here is a comma-separated lineup of layer suffixes, and that's literally the order the legend entries appear in, periodt. Any layer whose suffix isn't in this list? Not invited. Doesn't show up in the legend at all. 🙈

If you don't supply a value (that's the default), the sequence just copies the layer plotting sequence — peep seq for that.

  • legpos=<xfrac,yfrac> — sets where the legend sits inside the plot. Two comma-separated values: the X and the Y position of the legend within the plotting bounds. So like, "0.5,0.5" drops the legend dead center of the plot, main character behavior. 🌟 If you don't give a value, the legend shows up outside the plot boundary instead.
  • title=<value> — the text of a title up at the top of the plot. If it's null (which is the default), no title, and you get more room for the graphics. Simple as that. ✨
  • auxmap=<map-name>|<color>-<color>[-<color>...] — the color map used for Aux axis shading. 🎨

There's a whole mixed bag of colour ramps available, 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. 💀 Note: a lot of these — rainbow-like ones included — get side-eye from the visualisation community. Not my rules, bestie.

You can also build your own custom colour map by handing over a sequence of colour names separated by minus sign (-) characters. In that case the ramp is a linear interpolation between each pair of colours you named, using the same syntax as when you specify a colour value. So for example "yellow-hotpink-#0000ff" shades from yellow, through hot pink, all the way to blue. 🌈

  • auxclip=<lo>,<hi> — defines a subrange of the colour ramp that gets used for Aux shading. The value is a (low,high) comma-separated pair of two numbers sitting between 0 and 1. 🔢

Use the full range 0,1 and you get the whole range of colours the selected shader has to offer. But give it like 0,0.5 and only those colours at the left-hand end of the ramp show up.

If you pick the null value (the default), a default clip kicks in. This generally covers most or all of the 0-1 range, but for colour maps that fade to white, a small slice of the lower end may get excluded — ensuring every colour is actually visually distinguishable from a white background. That default is usually a good idea when the colour map is being used with something like a scatter plot, where markers are plotted against a white background. But for something like a density map, where the whole plotting area is tiled with colours from the map, supplying the whole range 0,1 explicitly might be better. 💡

  • auxflip=true|false — if true, the colour map on the Aux axis gets reversed. That's it, that's the whole thing. 🔄
  • auxquant=<number> — lets the colour map used for the Aux axis be quantised. Pick an integer value N and the colour map gets viewed as N discrete evenly-spaced levels — meaning only N different colours will appear in the plot. This can generate a contour-like effect, and might make it easier to trace region boundaries by eye. 👀

Leave it blank and 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 how values in the Aux range get mapped onto 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 gets 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 you end up with roughly the same number of points (or pixels, or whatever's being scaled) of each colour. The histogram options are a little more expensive, but they can be a great choice if you're exploring data whose distribution is unknown or just 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 — and HistoLog also ignores non-positive values.

  • auxmin=<number> — the 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> — the 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> — controls how closely the tick marks are spaced on the Aux axis, if it's visible. Default is 1, meaning normal crowding. Bigger values = more ticks, smaller values = fewer ticks. That said, tick marks won't get spaced so tightly that the labels overlap each other — so if you want truly tightly-spaced marks, you might need to shrink the font size too. 🔬
  • auxwidth=<pixels> — sets the lateral size of the aux colour ramp, if it's visible, in pixels. 📏
  • auxvisible=true|false|null — decides whether the aux axis colour ramp gets displayed alongside the plot. 👁️

If you don't supply it (that's the default), the aux axis will be visible whenever aux shading is used in any of the plotted layers.

  • forcebitmap=true|false — affects whether rendering of the data contents of a plot (not axis labels and such, just the data) is always done to an intermediate bitmap, rather than being painted with graphics primitives where possible. This is a pretty arcane setting, but ngl it can still have noticeable effects on the appearance and size of an output graphics file, plus on plotting time. For some types of plot (like shadingN=auto or shadingN=density) it has no effect at all, since that kind of rendering happens in any case. 🤷♀️

When writing to vector graphics formats (PDF and PostScript), setting it true forces the data contents to be bitmapped. That can make the output less beautiful (round markers will no longer be perfectly round 😭), but it may result in a much smaller file if you've got a huge number of 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 being rendered at the mercy of the graphics system, which sometimes throws in small distortions. 🖼️

  • compositor=0..1 — defines how multiple overplotted partially transparent pixels get combined into a resulting colour. How 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 get 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 upshot: 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 makes the command 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. 🔥

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 runs the pipeline you just gave it and reads from its standard output. Ngl bestie, 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) gets decompressed transparently, like magic, zero effort from you. 💅

afmt=<in-format> — tells everyone what format the animation control table is in, as specified by the animate parameter. 🌸 The known formats are all listed in SUN/256. Use this flag when you already know what format your table is in. If it has the special value (auto) — which is the default — then it'll try to detect the format automatically for you. It cannot always get that right, though, and when it can't, the program bails out with an error explaining which formats it attempted. 😭 This parameter is ignored for scheme-specified tables.

astream=true|false — if you set it true, the animation control table from the animate parameter gets read as a stream. 🦋 You must give the afmt parameter in that case, no skipping. Depending on the required operations and the processing mode, this may make the read fail (sometimes the table has to be read more than once, rip). You don't normally need to set this flag — in most cases the data streams automatically when that's the best thing to do. But it can sometimes mean less resource usage when you're processing large files in certain formats (such as VOTable). 🫶 Ignored for scheme-specified tables.

acmd=<cmds> — processing to be performed on the animation control table (the one from animate) before anything else has happened. The value is one or more of the filter commands described in SUN/256. If you're giving more than one, separate them with semicolon characters (;). ✨ Repeat this parameter multiple times on the same command line to build up a whole list of processing steps — the sequence you give defines the processing pipeline that gets performed on the table.

Commands can alternatively be supplied in an external file, using the indirection character @. So a value of @filename makes the file filename be read for a list of filter commands to execute. Commands in that file can be separated by newline characters and/or semicolons, and lines that are blank or that start with a # character get ignored. A backslash character \ at the end of a line joins it with the following line. 💜

parallel=<int-value> — decides how many threads run in parallel if animation output is being produced. Only used if the animate parameter is supplied. The default value is the number of processors apparently available to the JVM. 👑

nvar=<int-value> — gives the number of quantities to be plotted against each other, which will be the number of cells along each side of the scatter plot matrix. 🎀

matrixformat=<value> — configures which cells of the matrix grid get filled in. Below-diagonal, above-diagonal, or the full matrix — your call. Given grid cells will only appear if there are appropriate plot layers specified, i.e. 2-coordinate (scatter-plot-like) plots for the off-diagonal cells and 1-coordinate (histogram-like) plots for the diagonal cells. 🌈

The available options are:

  • lower: only the lower diagonal part of the matrix is populated, as well as the diagonal if diagonal elements are present
  • upper: only the upper diagonal part of the matrix is populated, as well as the diagonal if diagonal elements are present
  • full: all cells of the matrix are populated where present

cellgap=<int-value> — gives the number of pixels between cells in the displayed matrix of plots. ✨

squares=true|false — if true, each of the plotted panels in the matrix gets the same vertical and horizontal dimension. If false, the shape of each panel is determined by the shape of the overall plotting area. 🦋

xKscale=linear|log|asinh(<a>)|symlog(<t>,<s>) — defines the mapping of data to graphical coordinates on the xK axis. 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 from it. It has one parameter, the "linear width" a, which controls the extent of the linear-like region, and 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 which have parameters, the values are specified 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 allow plots 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.

The xK axis refers to any axes in the matrix on which input coordinate #K is plotted. Hence x2scale affects the axes on which the x2 coordinates are plotted. No cap. 👑

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. 🫶

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. 🫶

xKflip=true|false — if true, the scale on the xK axis will increase in the opposite sense from usual (e.g. right to left rather than left to right). 🙈

The xK axis refers to any axes in the matrix on which input coordinate #K is plotted. Hence x2flip affects the axes on which the x2 coordinates are plotted.

xKlabel=<text> — gives a label to be used for annotating axis xK. A default value based on the plotted data will be used if no value is supplied. 🌸

The xK axis refers to any axes in the matrix on which input coordinate #K is plotted. Hence x2label affects the axes on which the x2 coordinates are plotted.

grid=true|false — if true, grid lines get drawn on the plot at positions determined by the major tick marks. If false, they're absent. Simple as. ✨

xcrowd=<number> — determines how closely the tick marks are spaced on the X axis. The default value is 1, meaning normal crowding. Larger values give you more ticks, smaller values give you fewer. Tick marks won't be spaced so closely that the labels overlap each other, though, so to get very closely spaced marks you may need to reduce the font size as well. 💅

ycrowd=<number> — determines how closely the tick marks are spaced on the Y axis. The default value is 1, meaning normal crowding. Larger values give you more ticks, smaller values give you fewer. Tick marks won't be spaced so closely that the labels overlap each other, though, so to get very closely spaced marks you may need to reduce the font size as well. 💅

labelangle=horizontal|angled|adaptive — controls the orientation of numeric labels on the axes. 🌈 In most cases labels are written horizontally on both the horizontal and vertical axes, but this option lets you write them at an angle, which may fit more labels on the horizontal axis — especially if the labels are long or you've asked for a high crowding factor.

Heads up: the adaptive option is currently not perfect, and can sometimes lead to suboptimal border placement. 😭

The available 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 as well as the major tick marks. Minor tick marks do not have associated grid lines. 🎀

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 axis, so tick marks are visible along all edges — not just the ones with numeric labels. Iconic. 👑 If a secondary axis is in use, this setting is ignored.

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. However, many other common colour names (too many to list here, fr fr) 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. 🌈

  • RRGGBB — or as a six-digit hexadecimal number, optionally with a # or 0x in front, no big deal either way. That gives you red, green and blue intensities, like ff00ff, #ff00ff or 0xff00ff bestie, and all three of those are literally just magenta 💜.
  • gridtrans=0..1 — how see-through the grid lines are, the ones that might get drawn over your plot. Range goes from 0 (fully opaque, can't see through it at all) to 1 (invisible, ghosted, gone). Heads up: this value is 1-alpha, so yeah, it's the inverse of what you'd expect 🙈.
  • labelcolor=<rrggbb>|red|blue|... — the color of your axis labels and any other plot annotations. Give it a name, or give it a hex RGB value, your call 💅.

The standard plotting colour names are red, blue, green, grey, magenta, cyan, orange, pink, yellow, black, light_grey, white. But also — and this is the fun part — many other common colour names are understood too, way too many to list here. The list currently contains every colour name understood by most web browsers, from AliceBlue all the way to YellowGreen, and you can find them listed e.g. in the Extended color keywords section of the CSS3 standard. So go off, name your colour whatever cursed CSS name you like 🎀.

Alternatively? A six-digit hexadecimal number RRGGBB, optionally prefixed by # or 0x, giving red, green and blue intensities, e.g. ff00ff, #ff00ff or 0xff00ff for magenta. Same energy, just with numbers.

  • texttype=plain|antialias|latex — decides how your label text gets turned into actual characters on the plot. plain and antialias both take the text at face value, except antialias smooths the characters so they look all ✨crisp✨. latex interprets the text as LaTeX source code and typesets it accordingly, which is giving academic 🎓.

When you're not using LaTeX, antialiased text usually looks nicer, but ngl 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 — yep, that's a MacOS java bug 💀 not us, not our fault.

  • fontsize=<int-value> — size of the text font, in points. Make it big, make it tiny, live your truth 👑.
  • fontstyle=standard|serif|mono — the font style for text, bestie.

The available options are:

  • standard
  • serif
  • mono
  • fontweight=plain|bold|italic|bold_italic — the font weight for text. Bold italic? Iconic, honestly.

The available options are:

  • plain
  • bold
  • italic
  • bold_italic
  • xKmin=<number> — the minimum value of the data coordinate on the xK axis. This sets the value before any subranging gets applied. If you don't supply it, the value is determined from the plotted data 🦋.

Real talk: the xK axis refers to any axes in the matrix on which input coordinate #K is plotted. Hence x2min affects the axes on which the x2 coordinates are plotted. iykyk.

  • xKmax=<number> — the maximum value of the data coordinate on the xK axis. Same deal as above: it sets the value before any subranging is applied, and if you don't supply it, it's determined from the plotted data ✨.

And yeah, same note: the xK axis refers to any axes in the matrix on which input coordinate #K is plotted. Hence x2max affects the axes on which the x2 coordinates are plotted.

  • xKsub=<lo>,<hi> — defines a normalised adjustment to the data range of the XK axis. You specify it as a comma-separated pair of two numbers giving the lower and upper bounds of the range 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. So it's all relative, cutie 🌸.

The default value 0,1 therefore has no effect (obviously, it's the whole thing). You could restrict the range to its lower half with the value 0,0.5. Lowkey handy.

And the classic: the xK axis refers to any axes in the matrix on which input coordinate #K is plotted. Hence x2sub affects the axes on which the x2 coordinates are plotted.

  • navaxes=xy|x|y — determines which axes get affected by the interactive navigation actions (pan and zoom). Default is xy, meaning your various mouse gestures will pan and zoom in both the X and Y directions. But if you set it to, for instance, x, then the mouse will only allow panning and zooming in the horizontal direction, with the vertical extent staying fixed. Locked in 🔒.
  • xKanchor=true|false — if true, then zoom actions work in such a way that the zero point on the xK axis stays in the same position on the plot. Anchored, grounded, unbothered 💅.

You know the drill: the xK axis refers to any axes in the matrix on which input coordinate #K is plotted. Hence x2anchor affects the axes on which the x2 coordinates are plotted.

  • 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 (just vibes, no zoom). A higher value means the mouse wheel zooms faster, and a value nearer 1 means it zooms slower.
⚠️ Values below 1 are not permitted. Don't try it, she will not allow it.
  • leglabelN=<text> — sets the presentation label for the layer with a given suffix. This is the text that shows up in the legend, if there is one. Multiple layers may use the same label, and if they do they'll be combined to form a single legend entry. Cute, efficient 💖.

If no value is supplied (which is 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. So here's the lore: 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 that suffix gets appended to all the parameter names which configure that layer. Suffixes may be any string, including the empty string. Yeah, the empty string counts. She contains multitudes 🧚.

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

  • mark
  • line
  • linearfit
  • label
  • 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 — and this is the genius bit — if the suffix is not present, the application will try looking for a parameter with the same name with no suffix instead. In this way, if several layers have the same value for a given parameter (for instance the input table), you can supply it using one unsuffixed parameter and save yourself from having to supply several parameters with the same value but different suffixes. Obsessed with the efficiency, honestly 🔥.

✨ 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

(no, that grammar is theirs not mine, I'm just the messenger 💀)

👑 AUTHOR 👑

Mark Taylor (Bristol University)

And that's a wrap, bestie 🫶 this page is from Mar 2017, straight out of the STILTS docs, and we ate literally every last line of it. Go plot something gorgeous. Periodt. 💅✨

📦 where this page comes from