STILTS-PLOT2TIME(1)

📦

version 3.5.4 · 5 versions

3.5.4 · ubuntu stonking (latest)
3.4.3 · ubuntu jammy
3.4.9 · ubuntu noble
3.4.7 · debian bookworm
3.5.2 · debian trixie, ubuntu questing, ubuntu resolute

💖 STILTS-PLOT2TIME(1) — Stilts commands 💖

ok bestie. sit down. hydrate. we are learning stilts-plot2time, which draws a time plot and honestly? it's giving main character energy. ✨

🌸 NAME 🌸

stilts-plot2time — draws a time plot 🕰️💅

🎀 SYNOPSIS 🎀

stilts plot2time [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>] [cellgap=<int-value>]
                 [yscale=linear|log|asinh(<a>)|symlog(<t>,<s>)]
                 [ylog=true|false] [yflip=true|false] [tlabel=<text>]
                 [ylabel=<text>] [t2func=<time-expr>] [y2func=<function-of-y>] [t2label=<text>] [y2label=<text>]
                 [grid=true|false] [tcrowd=<number>] [ycrowd=<number>]
                 [labelangle=horizontal|angled|adaptive]
                 [tformat=iso-8601|year|mjd|unix] [minor=true|false]
                 [shadow=true|false] [gridcolor=<rrggbb>|red|blue|...]
                 [gridtrans=0..1] [texttype=plain|antialias|latex]
                 [fontsize=<int-value>] [fontstyle=standard|serif|mono]
                 [fontweight=plain|bold|italic|bold_italic] [tmin=<year-or-iso8601>] [tmax=<year-or-iso8601>] [tsub=<lo>,<hi>]
                 [ymin=<number>] [ymax=<number>] [ysub=<lo>,<hi>]
                 [navaxes=t|y|ty] [zoomfactor=<number>]
                 [leglabelN=<text>] [layerN=<layer-type> <layerN-specific-params>] [zoneN=<text>]

✨ DESCRIPTION ✨

so plot2time draws plots where the horizontal axis is time. iconic concept, truly. and the time axis can be labelled in a bunch of different ways — MJD, decimal year, ISO-8601 form, the whole menu. pick your fighter. 💅

Positional coordinates come as t, y pairs, and there's an optional ttype specifier that tells everyone how the input value should be interpreted. like this:

plot2time in1=series.fits layer1=line t1=EPOCH ttype1=MJD y1=ENERGY

Time values can show up in input data in lots of different shapes, bestie. think Julian Day, Modified Julian Date, decimal years since 0AD, Unix seconds, ISO-8601, or variants of those with extra offsets sprinkled on top. and here's the tea 🍵: sometimes the input format carries enough metadata for us to figure out how the values should be mapped to a common timescale (so they can be plotted as MJD or Year/Month/Day, for instance) — and sometimes it absolutely does not.

for example: CDF files and VOTable 1.4 files with TIMESYS markup contain sufficient metadata, and text inputs using the ISO-8601 format can usually be identified and understood. but there's no way to tell automatically whether a numeric column in a CSV file represents MJD, seconds since a known epoch, decimal years, or literally anything else. 😭 so that's exactly why the ttypeN parameter exists for all the layer types that have a tN coordinate. here's how it goes:

ttypeN = DecYear|MJD|JD|Unix|Iso8601 (TimeMapper) — picks the form in which the Time value for parameter tN is supplied. your options:

DecYear: Years since 0 AD
MJD: Modified Julian Date
JD: Julian Day
Unix: Seconds since midnight 1 Jan 1970
Iso8601: ISO 8601 string

If you leave it blank, a guess will be taken depending on the data type of the value supplied for the tN value. 🎲

ok so this next bit is where plot2time gets to be the special one 👑

This command, unlike the other plot2* commands at time of writing, can be used to draw multi-zone plots. These are plots with different panels stacked vertically so that different datasets can share the same horizontal (time) axis, but have separate vertical axes, colour maps, legends etc. The horizontal axes are always synchronized between zones. no cap. 🦋

This is currently controlled with the zoneN parameter. For any layer with a layer suffix N, you can specify a zone identifier as an arbitrary string, Z, by supplying the parameter zoneN=Z. Layers with the same value of zoneN are plotted in the same zone, and layers with different values are plotted in different zones. If no zoneN is given, the layer is assigned to a single (unnamed) zone — so with no zone parameters specified, all plots appear in a single zone. Parameters specific to a given zone can then be suffixed with the same Z zone identifier. The examples section illustrates what this looks like in practice. 💖

⚠️ Note: The multi-zone feature is experimental. As currently implemented it lacks some features. The interface may be changed in a future version. bestie we are on the bleeding edge, act accordingly 💀

Content is added to the plot by specifying one or more plot layers using the layerN parameter. The N part is a suffix applied to all the parameters affecting a given layer; any suffix (including the empty string) may be used. Available layers for this plot type are:

line, linearfit, mark, fill, quantile, grid, histogram, kde, knn, densogram, gaussian, yerror, spectrogram, label, function.

that's fifteen (15) whole layers. we ate. 🔥

👑 OPTIONS 👑

💅 `xpix=<int-value>`

Size of the output image in the X direction in pixels. This includes space for any axis labels, padding and other decoration outside the plot area itself. See also insets.

💅 `ypix=<int-value>`

Size of the output image in the Y direction in pixels. This includes space for any axis labels, padding and other decoration outside the plot area itself. See also insets.

💅 `insets=<top>,<left>,<bottom>,<right>`

Defines the amount of space in pixels around the actual plotting area. This space is used for axis labels, and other decorations — and any left over forms an empty border.

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

The value of this parameter is 4 comma separated integers: <top>,<left>,<bottom>,<right>. Any or all of these values may be left blank, in which case the corresponding margin will be calculated automatically according to how much space is required. so it just ✨knows✨. 🧚

💅 `omode=swing|out|cgi|discard|auto`

Determines how the drawn plot will be output, see SUN/256. your choices, babes:

swing: Plot will be 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 in the same way as plots in TOPCAT. 🖱️✨
out: Plot will be written to a file given by out using the graphics format given by ofmt.
cgi: Plot will be written in a way suitable for CGI use direct from a web server. The output is in the graphics format given by ofmt, preceded by a suitable "Content-type" declaration. 🌐
discard: Plot is drawn, but discarded. There is no output. (all that work for nothing, we love a dramatic exit 💀)
auto: Behaves as swing or out mode depending on presence of out parameter

💅 `storage=simple|memory|disk|policy|cache|basic-cache|persistent|parallel`

Determines the way that data is accessed when constructing the plot. There are two main options: cached or not. 👛

If no caching is used then rows are read sequentially from the specified input table(s) every time they are required. This generally requires a small resource footprint (though that can depend on how the table is specified) and makes sense if the data only needs to be scanned once or perhaps if the table is very large.

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

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 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 this is used, plot data will be stored on disk in a way that means they can be re-used between STILTS invocations, so data preparation can be avoided on subsequent runs. Note however it can leave potentially large files in your temporary directory. 🫣
cache: synonym for memory (backward compatibility)
basic-cache: dumber version of memory (no optimisation for constant-valued columns)
parallel: experimental version of memory-based cache that reads into the cache in parallel for large files. This will make 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 (e.g. output to a graphics file) the default is simple.

💅 `seq=<suffix>[,...]`

Contains a comma-separated list of layer suffixes to determine the order in which layers are drawn on the plot. This can affect which symbol are plotted on top of, and so potentially obscure, which other ones. 🤭 stacking order is a whole personality trait, honestly

When specifying a plot, multiple layers may be specified, each introduced by a parameter layer<N>, where <N> is a different (arbitrary) suffix labelling the layer, and is appended to all the parameters specific to defining that layer.

Every element of the list has to be a suffix that actually has a matching layer parameter, okay? But bestie, missing ones and repeated ones are totally allowed, we're not gatekeeping.

legend=true|false|null — do we draw a legend or not? 🙈 If you don't give a value, it decides for itself: a legend shows up only if it would have more than one entry.
legborder=true|false — if true, a line border gets drawn around the legend. Cute lil frame. 🎀
legopaque=true|false — if true, the legend's background is opaque and it obscures any plot components behind it. Otherwise it's transparent and everything shows through. ✨
legseq=<suffix>[,...] — this one picks which layers show up in the legend (if there is one) and in what order. The legend has one line per layer label (labels come from the leglabelN parameter). If multiple layers share the same label, they all feed into the same legend entry, with style icons plotted right over each other. The value is a comma-separated sequence of layer suffixes that sets the order of the legend entries. Any layers whose suffixes aren't in this list don't show up in the legend at all. Periodt.

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

legpos=<xfrac,yfrac> — where the legend sits inside the plot. It's a comma-separated pair giving the X and Y position of the legend within the plotting bounds, so like "0.5,0.5" drops that legend dead center in the plot. 👑 If you don't give a value, the legend appears outside the plot boundary.

If a zone suffix is tacked onto the parameter name, only that zone is affected, e.g. legposZ affects only zone Z.

title=<value> — the text of a title 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. ✨

If a zone suffix is tacked onto the parameter name, only that zone is affected, e.g. titleZ affects only zone Z.

auxmap=<map-name>|<color>-<color>[-<color>...] — the colour map used for Aux axis shading. 🌈

There's a whole mixed bag of colour ramps you can pick from, 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: many of these — including the rainbow-like ones — are frowned upon by the visualisation community. 😭 (iykyk)

You can also build your own custom colour map by giving 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 instance yellow-hotpink-#0000ff shades from yellow via hot pink to blue. Obsessed actually.

If a zone suffix is tacked onto the parameter name, only that zone is affected, e.g. auxmapZ affects only zone Z.

auxclip=<lo>,<hi> — defines a subrange of the colour ramp used for Aux shading. The value is 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 the selected shader is used. But if you give something like 0,0.5, you'll only see the colours at the left hand end of the ramp.

If you pick null (the default), a default clip gets used. That generally covers most or all of the range 0-1, but for colour maps that fade to white, a small proportion of the lower end may be excluded — to make sure all the colours stay visually distinguishable from a white background. This default is usually a good idea when the colour map is 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, it may be better to explicitly supply the whole range 0,1.

If a zone suffix is tacked onto the parameter name, only that zone is affected, e.g. auxclipZ affects only zone Z.

auxflip=true|false — if true, the colour map on the Aux axis gets reversed. 🔄

If a zone suffix is tacked onto the parameter name, only that zone is affected, e.g. auxflipZ affects only zone Z.

auxquant=<number> — lets the colour map used for the Aux axis be quantised. If you choose an integer value N, the colour map is viewed as N discrete evenly-spaced levels, so only N different colours show up in the plot. This can generate a contour-like effect, and can make it easier to trace the boundaries of regions of interest by eye. 😌

If left blank, the colour map is nominally continuous (though in practice it may be quantised to a medium-sized number like 256).

If a zone suffix is tacked onto the parameter name, only that zone is affected, e.g. auxquantZ affects only zone Z.

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 is used, and displayed on the colour bar if applicable. Heads up: the logarithmic-based options Log and HistoLog 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 there are about the same number of points (or pixels, or whatever is being scaled) of each colour. The histogram options are somewhat more expensive, but they can be a great choice if you're exploring data whose distribution is unknown or not well-behaved over its min-max range. Histogram and HistoLog both assign the colours the same way, but they display the colour ramp with linear or logarithmic annotation respectively; HistoLog also ignores non-positive values.

If a zone suffix is tacked onto the parameter name, only that zone is affected, e.g. auxfuncZ affects only zone Z.

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 comes from the plotted data.

If a zone suffix is tacked onto the parameter name, only that zone is affected, e.g. auxminZ affects only zone Z.

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 comes from the plotted data.

If a zone suffix is tacked onto the parameter name, only that zone is affected, e.g. auxmaxZ affects only zone Z.

auxlabel=<text> — sets the label used to annotate the aux axis, if it's visible. 🏷️

If a zone suffix is tacked onto the parameter name, only that zone is affected, e.g. auxlabelZ affects only zone Z.

auxcrowd=<factor> — determines how closely the tick marks are spaced on the Aux axis, if visible. The default value is 1, meaning normal crowding. Bigger values = more ticks, smaller values = fewer ticks. Tick marks won't get so closely spaced that the labels overlap each other, though — so if you want very closely spaced marks you may need to reduce the font size too.

If a zone suffix is tacked onto the parameter name, only that zone is affected, e.g. auxcrowdZ affects only zone Z.

auxwidth=<pixels> — determines the lateral size of the aux colour ramp, if visible, in pixels. 📏

If a zone suffix is tacked onto the parameter name, only that zone is affected, e.g. auxwidthZ affects only zone Z.

auxvisible=true|false|null — determines whether the aux axis colour ramp is displayed alongside the plot.

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

If a zone suffix is tacked onto the parameter name, only that zone is affected, e.g. auxvisibleZ affects only zone Z.

forcebitmap=true|false — controls 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. This is a rather arcane setting that may nevertheless have noticeable effects on the appearance and size of an output graphics file, as well as on plotting time. For some types of plot (e.g. shadingN=auto or shadingN=density) it will have no effect, since that kind of rendering happens in any case. 💀

Okay bestie, plot-twist (literally), we're still deep in OPTIONS here — so let's keep scrolling, the lore continues 💅

If you're writing out to vector graphics formats (PDF and PostScript), setting it true forces the data contents to get bitmapped. Yeah, lowkey that means the output can be less pretty — perfectly round markers stop being perfectly round 😭 — but it can also give you a way smaller file if you've got, like, an absurd number of data points.

And if you're writing to bitmapped output formats (PNG, GIF, JPEG, ...), it locks the shapes down so they look exactly like they did on screen, instead of being rendered at the mercy of the graphics system — which sometimes sneaks in lil distortions. Rude of it, honestly. 🙈

compositor=0..1 — This one decides how multiple overplotted, partially transparent pixels get smooshed together into one resulting colour 🎨. Exactly how it's used depends on the fine details of the plot you specified.

Right now this parameter takes a "boost" value in the range 0..1. If it's zero, you get saturation semantics: RGB colours get added in proportion to their associated alpha value until the total alpha saturates (hits 1), and after that, extra pixels do absolutely nothing more. For larger boost values the vibe is similar, except any non-zero alpha in the output gets boosted up to that given minimum value. What that gets you: even the tiniest, most barely-populated pixels can be visually told apart from completely unpopulated ones — which ngl just isn't always the case with saturation composition.

animate=<table> — If this isn't null, it makes the command produce a whole sequence of plots instead of just one 🌈. The value is a table with one row per frame you want produced. Table columns get interpreted as parameters that can take different values per frame — column name = parameter name, and the value for a given frame is whatever's in that row. Animating this way is considerably more efficient than just invoking the STILTS command in a loop. Efficiency queen 👑

The location of the animation control table. It can take one of these 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. Heads up: not all formats can be streamed 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 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. Magic ✨

afmt=<in-format> — Tells it the format of the animation control table given by the animate parameter. The known formats are listed in SUN/256. Use this flag when you already know what format your table is in. If it has the special value (auto) (the default), it'll try to detect the format automatically. It can't always get that right though — in which case the program exits with an error explaining which formats it attempted. 🫠 This parameter is ignored for scheme-specified tables.
astream=true|false — If set true, the animation control table given by animate gets read as a stream. You have to give the afmt parameter in this case. Depending on the required operations and processing mode, this may cause the read to fail (sometimes it's necessary to read the table more than once 😭). 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. But it can sometimes mean less resource usage when processing large files in certain formats (like VOTable). This parameter is ignored for scheme-specified tables.
acmd=<cmds> — Specifies processing to be done on the animation control table (the one from animate) before any other processing happens. The value is one or more of the filter commands described in SUN/256. If you give more than one, separate them with semicolon characters (;). You can repeat this parameter multiple times on the same command line to build up a list of processing steps — and the sequence of commands you give this way defines the processing pipeline performed on the table. 🧚

You can also supply commands from 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 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 however many processors the JVM apparently has available. Multi-core moment fr fr 🔥
cellgap=<int-value> — The number of pixels between individual members in the stack of plots. Gotta have your personal space 💅
yscale=linear|log|asinh(<a>)|symlog(<t>,<s>) — Defines the mapping of data to graphical coordinates on the Y axis. Your options:
- 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 takes 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. Linear near the origin, and positive/negative logarithmic for larger values. It takes two parameters, t (a.k.a. linthresh) and s (a.k.a. linscale). Both parameters must be strictly positive. The linear region sits 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 the options that have parameters, you give the values after the name in brackets, e.g. "symlog(10,0.5)". If the parameters are missing (like just "symlog"), some default values get used. ✨

The linear and log options should be self-explanatory bestie. symlog and asinh let you plot over a wide dynamic range just like log, but unlike log they can handle negative and 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. Iconic crossover 🫶

If a zone suffix is appended to the parameter name, only that zone is affected — e.g. yscaleZ affects only zone Z.

ylog=true|false — If false (the default), the scale on the Y axis is linear; if true, it's logarithmic.

Heads up: this option is deprecated in favour of the yscale option, which offers more flexible axis scaling options. Retire her 💀

If a zone suffix is appended to the parameter name, only that zone is affected — e.g. ylogZ affects only zone Z.

yflip=true|false — If true, the scale on the Y axis increases in the opposite sense from usual (e.g. right to left rather than left to right). Flip the vibe 🦋

If a zone suffix is appended to the parameter name, only that zone is affected — e.g. yflipZ affects only zone Z.

tlabel=<text> — Gives a label used for annotating the Time axis. If you don't supply one, no label gets drawn. Silent treatment, periodt.

If a zone suffix is appended to the parameter name, only that zone is affected — e.g. tlabelZ affects only zone Z.

ylabel=<text> — Gives a label used for annotating axis Y. A default value based on the plotted data gets used if you don't supply one.

If a zone suffix is appended to the parameter name, only that zone is affected — e.g. ylabelZ affects only zone Z.

t2func=<time-expr> — Defines a secondary time axis in terms of the primary one. If a secondary axis is defined this way, then the axis opposite the primary one — i.e. the one on the top edge of the plot — gets annotated with the appropriate tickmarks. 📈

The value of this parameter is an algebraic expression giving the numeric value to display on the secondary axis for a given time value on the primary axis. The expression may be given in terms of one of these variables:

mjd: Modified Julian Date
jd: Julian Day
decYear: decimal year CE
unixSec: seconds since 1970-01-01T00:00:00

In most cases the value of this parameter is just one of those variable names — for instance "mjd" to annotate the secondary axis in Modified Julian Date. But you can apply operations to those values the usual way if you need to, for instance to provide a differently offset date scale. 💖

The function you supply should be monotonic and reasonably well-behaved, otherwise the secondary axis annotation may not work well. Tick marks will always be applied on a linear scale. Currently there's no way to annotate the secondary axis with ISO-8601 dates or other non-numeric labels. 😭

If a zone suffix is appended to the parameter name, only that zone is affected — e.g. t2funcZ affects only zone Z.

and we're STILL going, don't you dare close the tab, there's so much plot left to plot 🎀

y2func=<function-of-y> — bestie this one is CUTE. It builds you a whole secondary Y axis out of the primary one. Like, if you set this up, then the axis sitting opposite your primary one (that's the right side of the plot, yes) gets annotated with the appropriate tickmarks. Coordination? Iconic. 💅

So what you actually put here is an algebraic expression in terms of the variable y, and it gives you the value on the secondary Y axis that corresponds to a given value on the primary Y axis. Math but make it fashion.

Say your primary Y axis is flux in Jansky. Then you'd hand over the expression 2.5*(23-log10(y))-48.6 (or janskyToAb(y)) and boom — the secondary Y axis gets annotated as AB magnitudes. Slay.

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

If a zone suffix is appended to the parameter name, only that zone is affected, e.g. y2funcZ affects only zone Z.

t2label=<text> — drops a string that labels the secondary Time axis. It shows up on the opposite side of the plot from the Time axis itself. 🎀

If a zone suffix is appended to the parameter name, only that zone is affected, e.g. t2labelZ affects only zone Z.

y2label=<text> — same energy, different axis: this one labels the secondary Y axis, and it appears on the opposite side of the plot from the Y axis itself.

If a zone suffix is appended to the parameter name, only that zone is affected, e.g. y2labelZ affects only zone Z.

grid=true|false — if it's true, grid lines get drawn on the plot at positions determined by the major tick marks. If it's false, they're just… absent. Not invited. 💀

If a zone suffix is appended to the parameter name, only that zone is affected, e.g. gridZ affects only zone Z.

tcrowd=<number> — controls how closely the tick marks are spaced on the Time axis. Default is 1, which means normal crowding. Bigger values → more ticks, smaller values → fewer ticks. But heads up, the tick marks won't get 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. Teamwork, fr fr.

If a zone suffix is appended to the parameter name, only that zone is affected, e.g. tcrowdZ affects only zone Z.

ycrowd=<number> — same deal but for the Y axis. Default 1, normal crowding. Bigger values → more ticks, smaller values → fewer. And again, the marks won't be spaced so closely that the labels overlap, so very closely spaced marks may need a font size reduction too.

If a zone suffix is appended to the parameter name, only that zone is affected, e.g. ycrowdZ affects only zone Z.

labelangle=horizontal|angled|adaptive — controls the orientation of the numeric labels on your axes. Most of the time the labels go horizontally on both horizontal and vertical axes, but this option opens up the possibility of writing them at an angle — which may fit more labels on the horizontal axis, especially when your labels are long or you're asking for a high crowding factor.

Heads up bestie: the adaptive option is currently not perfect, and can sometimes lead to suboptimal border placement. Not me warning you about a known quirk. 😭

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

If a zone suffix is appended to the parameter name, only that zone is affected, e.g. labelangleZ affects only zone Z.

tformat=iso-8601|year|mjd|unix — picks how time values get represented when you use them to label the time axis. Pick your fighter. 🦋

The available options are:

iso-8601: ISO 8601 date, of the form yyyy-mm-ddThh:mm:ss.s (e.g. "2012-03-13T04")
year: Decimal year (e.g. "2012.197")
mjd: Modified Julian Date (e.g. "55999.2")
unix: Seconds since midnight of 1 Jan 1970 (e.g. "1331613420")

If a zone suffix is appended to the parameter name, only that zone is affected, e.g. tformatZ affects only zone Z.

minor=true|false — if true, minor tick marks get painted along the axes in addition to the major tick marks. Important: minor tick marks do not have associated grid lines. They're just little guys, no grid. 🥺

If a zone suffix is appended to the parameter name, only that zone is affected, e.g. minorZ affects only zone Z.

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

If a zone suffix is appended to the parameter name, only that zone is affected, e.g. shadowZ affects only zone Z.

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, many other common colour names (way 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. 💜

If a zone suffix is appended to the parameter name, only that zone is affected, e.g. gridcolorZ affects only zone Z.

gridtrans=0..1 — the transparency of grid lines that may be drawn over the plot. The range is 0 (opaque) to 1 (invisible). This value is 1-alpha. Ghost-y grid lines, we love a subtle moment.

If a zone suffix is appended to the parameter name, only that zone is affected, e.g. gridtransZ affects only zone Z.

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. It's giving glow-up.

When you're not using LaTeX, antialiased text usually looks nicer, but can be perceptibly slower to plot. 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). Not me calling out a java bug on main. 💀

If a zone suffix is appended to the parameter name, only that zone is affected, e.g. texttypeZ affects only zone Z.

fontsize=<int-value> — size of the text font, in points. Small text, big text, whatever your heart says.

If a zone suffix is appended to the parameter name, only that zone is affected, e.g. fontsizeZ affects only zone Z.

fontstyle=standard|serif|mono — font style for text.

The available options are:

standard
serif
mono

If a zone suffix is appended to the parameter name, only that zone is affected, e.g. fontstyleZ affects only zone Z.

fontweight=plain|bold|italic|bold_italic — font weight for text. Yes you can be bold and italic, the iconique bold_italic.

The available options are:

plain
bold
italic
bold_italic

If a zone suffix is appended to the parameter name, only that zone is affected, e.g. fontweightZ affects only zone Z.

tmin=<year-or-iso8601> — minimum value of the time coordinate plotted. This sets the value before any subranging is applied. If you don't supply it, the value is determined from the plotted data.

The value may be set with a string that can be interpreted as a decimal year (e.g. "2007.521") or an ISO-8601 string (e.g. "2007-07-10T03:57:36", "2007-07-10T03" or "2007-07-10"). Note however that the numeric value of this configuration item, if accessed programmatically, is seconds since 1 Jan 1970. Sneaky units, iykyk. 🧚

If a zone suffix is appended to the parameter name, only that zone is affected, e.g. tminZ affects only zone Z.

tmax=<year-or-iso8601> — maximum value of the time coordinate plotted. This sets the value before any subranging is applied. If not supplied, the value is determined from the plotted data.

The value may be set with a string that can be interpreted as a decimal year (e.g. "2007.521") or an ISO-8601 string (e.g. "2007-07-10T03:57:36", "2007-07-10T03" or "2007-07-10"). And again — the numeric value of this configuration item if accessed programmatically is seconds since 1 Jan 1970.

If a zone suffix is appended to the parameter name, only that zone is affected, e.g. tmaxZ affects only zone Z.

tsub=<lo>,<hi> — defines a normalised adjustment to the data range of the Time axis. You give it a comma-separated pair of two numbers: the lower and upper bounds of the range of interest respectively. This sub-range gets 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 (it's the full range, like, obviously). The range could be restricted to its lower half with the value 0,0.5. Cropping but make it math. ✂️

If a zone suffix is appended to the parameter name, only that zone is affected, e.g. tsubZ affects only zone Z.

ymin=<number> — minimum value of the data coordinate on the Y axis. This sets the value before any subranging is applied. If not supplied, the value is determined from the plotted data.

If a zone suffix is appended to the parameter name, only that zone is affected, e.g. yminZ affects only zone Z.

ymax=<number> — the biggest value on the Y axis, periodt. This sets it before any subranging gets applied, so it's the raw ceiling, not the after-party version. If you don't give it, it just gets figured out from the data you're plotting, no biggie.

And bestie, hear me out: if you slap a zone suffix on the parameter name, only that zone gets touched — like ymaxZ only affects zone Z. 💅

ysub=<lo>,<hi> — ok so this is a normalised little adjustment to your Y axis data range. You give it a comma-separated pair of two numbers: the lower and upper bounds of the range of interest. That sub-range gets applied to the data range that would otherwise be used — whether that was auto-calculated or something you explicitly handed over. Zero = the lower bound, one = the upper bound. ✨

So the default value 0,1 does literally nothing, iconic behaviour, no notes. But if you wanted to zoom into just the bottom half, you'd go 0,0.5. Slay.

Zone suffix rules apply here too: ysubZ affects only zone Z. 🎀

navaxes=t|y|ty — picks which axes the interactive navigation vibe (pan and zoom) actually hits. Default is t, meaning all those cute mouse gestures only pan and zoom in the Time direction. But set it to ty and the mouse actions go for both the horizontal and vertical axes. Main character energy on both axes, fr fr.
zoomfactor=<number> — how much the plot view zooms in or out per unit of mouse wheel movement. 1 means the mouse wheel does nothing at all (💀). Bigger value = faster zoom. Value nearer 1 = slower zoom. And values below 1? Not permitted. Nope. Not allowed. Don't even try it. 🚫
leglabelN=<text> — sets the presentation label for the layer with suffix N. This is the text that shows up in the legend, if there is one. Multiple layers can totally share the same label, and when they do, they get combined into a single legend entry. Besties matching outfits. 🫶

If you supply no value (which is the default), the suffix itself becomes the label. Simple as.

layerN=<layer-type> <layerN-specific-params> — ok this is the big one, the iconic one. This selects one of the available plot types for layerN. Here's the lore: a plot is made of a plotting surface — set up with the various unsuffixed parameters of the plotting command — plus zero or more plot layers. Each layer gets introduced by a parameter named layer<N>, where the suffix <N> is a label identifying that layer, and it gets appended to all the parameter names that configure it. Suffixes can be any string, including the empty string. Yes, even that. 💖

This parameter can take one of these values, all described in more detail in SUN/256:

line
linearfit
mark
fill
quantile
grid
histogram
kde
knn
densogram
gaussian
yerror
spectrogram
label
function

Each one of these layer types comes with its own list of type-specific parameters that define the details of that layer, and that includes some or all of these lil 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. BUT — if the suffix isn't there, the application will try looking for a parameter with the same name and no suffix instead. So if several layers all want the same value for a parameter (input table, say), you can just supply it once with an unsuffixed parameter instead of typing out the same value over and over with different suffixes. Efficiency queen behaviour. 👑

zoneN=<text> — defines which plot zone the layer with suffix N will show up in. This only makes sense for multi-zone plots, so don't stress if that's not your situation. The actual value of the parameter isn't significant — it's just a label, a lil name tag 🎀 — but different layers will end up in the same plot zone if they give the same values for this parameter. Matching bracelets, essentially.

🌈 SEE ALSO 🌈

stilts(1)

And if the package stilts-doc is installed, the full documentation SUN/256 is available in HTML format, right here:

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

⭐ VERSION ⭐

STILTS version 3.5.4-debian

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

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

👑 AUTHOR 👑

Mark Taylor (Bristol University)

ok bestie that's the whole page, we ate and left no crumbs ✨ this was STILTS version 3.5.4-debian, dated Mar 2017, and honestly? iconic of it. go forth and plot, my love 💜🦋

📦 where this page comes from

ubuntu stonking: stilts 3.5.4-1 · LGPL-2.1-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-02: a language model's rewrite of the original, under its terms

STILTS-PLOT2TIME(1)

💖 STILTS-PLOT2TIME(1) — Stilts commands 💖

🌸 NAME 🌸

🎀 SYNOPSIS 🎀

✨ DESCRIPTION ✨

👑 OPTIONS 👑

💅 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>[,...]

🌈 SEE ALSO 🌈

⭐ VERSION ⭐

👑 AUTHOR 👑

💅 `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>[,...]`