Next Previous Up Contents
Next: Examples
Up: plot2plane: Draws a plane plot
Previous: plot2plane: Draws a plane plot

### B.14.1 Usage

The usage of `plot2plane` is

       stilts <stilts-flags> 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>

If you don't have the `stilts` script installed, write "`java -jar stilts.jar`" instead of "`stilts`" - see Section 3. The available `<stilts-flags>` are listed in Section 2.1. For programmatic invocation, the Task class for this command is `uk.ac.starlink.ttools.plot2.task.PlanePlot2Task`.

Parameter values are assigned on the command line as explained in Section 2.3. They are as follows:

`acmd = <cmds>` (ProcessingStep[])
  Specifies processing to be performed on the animation control table as specified by parameter `animate`, before any other processing has taken place. The value of this parameter is one or more of the filter commands described in Section 6.1. If more than one is given, they must be separated by semicolon characters (";"). This parameter can be repeated multiple times on the same command line to build up a list of processing steps. The sequence of commands given in this way defines the processing pipeline which is performed on the table.

  Commands may alternatively be supplied in an external file, by using the indirection character '`@`'. Thus a value of "`@filename`" causes the file `filename` to be read for a list of filter commands to execute. The commands in the file may be separated by newline characters and/or semicolons, and lines which are blank or which start with a '`#`' character are ignored. A backslash character '`\`' at the end of a line joins it with the following line.

`afmt = <in-format>` (String)
  Specifies the format of the animation control table as specified by parameter `animate`. The known formats are listed in Section 5.1.1. 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 cannot always be done correctly however, in which case the program will exit with an error explaining which formats were attempted. This parameter is ignored for scheme-specified tables.

  [Default: `(auto)`]

`animate = <table>` (StarTable)
  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.

  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.
`aspect = <number>` (Double)
  Ratio of the unit length on the X axis to the unit length on the Y axis. If set to 1, 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.
`astream = true|false` (Boolean)
  If set true, the animation control table specified by the `animate` parameter will be read as a stream. It is necessary 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 is necessary to read the table more than once). It is not normally necessary to set this flag; in most cases the data will be streamed automatically if that is the best thing to do. However it can sometimes result in less resource usage when processing large files in certain formats (such as VOTable). This parameter is ignored for scheme-specified tables.

  [Default: `false`]

`auxclip = <lo>,<hi>` (Subrange)
  Defines a subrange of the colour ramp to be used for Aux shading. The value is specified as a (low,high) comma-separated pair of two numbers between 0 and 1.

  If the full range `0,1` is used, the whole range of colours specified by the selected shader will be used. But if for instance a value of `0,0.5` is given, only those colours at the left hand end of the ramp will be seen.

  If the null (default) value is chosen, a default clip will be used. This generally covers most or all of the range 0-1 but for colour maps which fade to white, a small proportion of the lower end may be excluded, to ensure that all the colours are visually distinguishable from a white background. This default is usually a good idea if the colour map is being used with something like a scatter plot, where markers are plotted against a white background. However, for something like a density map when the whole plotting area is tiled with colours from the map, it may be better to supply the whole range `0,1` explicitly.

`auxcrowd = <factor>` (Double)
  Determines how closely the tick marks are spaced on the Aux axis, if visible. The default value is 1, meaning normal crowding. Larger values result in more ticks, and smaller values 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.

  [Default: `1.0`]

`auxflip = true|false` (Boolean)
  If true, the colour map on the Aux axis will be reversed.

  [Default: `false`]

`auxfunc = log|linear|histogram|...` (Scaling)
  Defines the way that values in the Aux range are 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 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 is being scaled) of each colour. The histogram options are somewhat more expensive, but can be a good choice if you are 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.

  [Default: `linear`]

`auxlabel = <text>` (String)
  Sets the label used to annotate the aux axis, if it is visible.
`auxmap = <map-name>|<color>-<color>[-<color>...]` (Shader)
  Color map used for Aux axis shading.

  A mixed bag of colour ramps are available as listed in Section 8.7: `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 rainbow-like ones, are frowned upon by the visualisation community.

  You can also construct your own custom colour map by giving a sequence of colour names separated by minus sign ("`-`") characters. In this case the ramp is a linear interpolation between each pair of colours named, using the same syntax as when specifying a colour value. So for instance "`yellow-hotpink-#0000ff`" would shade from yellow via hot pink to blue.

  [Default: `inferno`]

`auxmax = <number>` (Double)
  Maximum value of the data coordinate on the Aux axis. This sets the value before any subranging is applied. If not supplied, the value is determined from the plotted data.
`auxmin = <number>` (Double)
  Minimum value of the data coordinate on the Aux axis. This sets the value before any subranging is applied. If not supplied, the value is determined from the plotted data.
`auxquant = <number>` (Double)
  Allows the colour map used for the Aux axis to be quantised. If an integer value N is chosen then the colour map will be viewed as N discrete evenly-spaced levels, so that only N different colours will appear in the plot. This can be used to generate a contour-like effect, and may 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).

`auxvisible = true|false|null` (Boolean)
  Determines whether the aux axis colour ramp is displayed alongside the plot.

  If not supplied (the default), the aux axis will be visible when aux shading is used in any of the plotted layers.

`auxwidth = <pixels>` (Integer)
  Determines the lateral size of the aux colour ramp, if visible, in pixels.

  [Default: `15`]

`compositor = 0..1` (Compositor)
  Defines how multiple overplotted partially transparent pixels are 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 is 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.

  [Default: `0.05`]

`fontsize = <int-value>` (Integer)
  Size of the text font in points.

  [Default: `12`]

`fontstyle = standard|serif|mono` (FontType)
  Font style for text.

  The available options are:

  - `standard`
  - `serif`
  - `mono`

  [Default: `standard`]

`fontweight = plain|bold|italic|bold_italic` (FontWeight)
  Font weight for text.

  The available options are:

  - `plain`
  - `bold`
  - `italic`
  - `bold_italic`

  [Default: `plain`]

`forcebitmap = true|false` (Boolean)
  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. 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 plotting time. For some types of plot (e.g. `shadingN=auto` or `shadingN=density`) it will 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.

  [Default: `false`]

`grid = true|false` (Boolean)
  If true, grid lines are drawn on the plot at positions determined by the major tick marks. If false, they are absent.

  [Default: `false`]

`gridcolor = <rrggbb>|red|blue|...` (Color)
  The color of the plot grid, 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`. However, 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.

  [Default: `grey`]

`gridtrans = 0..1` (Double)
  Transparency of grid lines that may be drawn over the plot. The range is 0 (opaque) to 1 (invisible). This value is 1-alpha.

  [Default: `0.5`]

`insets = <top>,<left>,<bottom>,<right>` (Padding)
  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.

`labelangle = horizontal|angled|adaptive` (OrientationPolicy)
  Controls the orientation of numeric labels on the axes. In most cases labels are written horizontally on both horizontal and vertical axes, but this option provides the possibility to write them at an angle which may be able to accommodate more labels on the horizontal axis, especially if the labels are long or a high crowding factor is requested.

  Note that 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

  [Default: `horizontal`]

`labelcolor = <rrggbb>|red|blue|...` (Color)
  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`. However, 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.

  [Default: `black`]

`layerN = <layer-type> <layerN-specific-params>` (LayerType)
  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, and zero or more plot layers. Each layer is introduced by a parameter with the name `layer<N>` where the suffix "`<N>`" is a label identifying the layer and is appended to all the parameter names which configure that layer. Suffixes may be any string, including the empty string.

  This parameter may take one of the following values, described in more detail in Section 8.3:

  - `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`
  - `vecfield`
  - `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 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 input table), you can supply it using one unsuffixed parameter to save having to supply several parameters with the same value but different suffixes.

`legborder = true|false` (Boolean)
  If true, a line border is drawn around the legend.

  [Default: `true`]

`legend = true|false|null` (Boolean)
  Whether to draw a legend or not. If no value is supplied, the decision is made automatically: a legend is drawn only if it would have more than one entry.
`leglabelN = <text>` (String)
  Sets the presentation label for the layer with a given suffix. This is the text which is displayed in the legend, if present. Multiple layers may use the same label, in which case they will be combined to form a single legend entry.

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

`legopaque = true|false` (Boolean)
  If true, the background of the legend is opaque, and the legend obscures any plot components behind it. Otherwise, it's transparent.

  [Default: `true`]

`legpos = <xfrac,yfrac>` (double[])
  Determines the internal position of the legend on the plot. The value is a comma-separated pair of values giving the X and Y positions of the legend within the plotting bounds, so for instance "`0.5,0.5`" will put the legend right in the middle of the plot. If no value is supplied, the legend will appear outside the plot boundary.
`legseq = <suffix>[,...]` (String[])
  Determines which layers are represented in the legend (if present) and in which order they appear. The legend has a line for each layer label (as determined by the `leglabelN` parameter). If multiple layers have the same label, they will contribute to the same entry in the legend, with style icons plotted over each other. The value of this parameter is a comma-separated sequence of layer suffixes, which determines the order in which the legend entries appear. Layers with suffixes missing from this list do not show up in the legend at all.

  If no value is supplied (the default), the sequence is the same as the layer plotting sequence (see `seq`).

`minor = true|false` (Boolean)
  If true, minor tick marks are painted along the axes as well as the major tick marks. Minor tick marks do not have associated grid lines.

  [Default: `true`]

`navaxes = xy|x|y` (boolean[])
  Determines the axes which are affected by the interactive navigation actions (pan and zoom). The default is `xy`, which means that the various mouse gestures will provide panning and zooming in both X and Y directions. However, if it is set to (for instance) `x` then the mouse will only allow panning and zooming in the horizontal direction, with the vertical extent fixed.

  [Default: `xy`]

`omode = swing|out|cgi|discard|auto` (PaintMode)
  Determines how the drawn plot will be output, see Section 8.5.
  - `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.
  - `auto`: Behaves as `swing` or `out` mode depending on presence of `out` parameter

  [Default: `auto`]

`parallel = <int-value>` (Integer)
  Determines how many threads will 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.

  [Default: `20`]

`seq = <suffix>[,...]` (String[])
  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.

  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.

  By default the layers are drawn on the plot in the order in which the `layer*` parameters appear on the command line. However 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 the list must be a suffix with a corresponding `layer` parameter, but missing or repeated elements are allowed.

`shadow = true|false` (Boolean)
  If true and no secondary axis is in use, then tick marks without numeric labels are painted along the axis opposite to the primary axis, so that tick marks are visible along all edges not just the ones with numeric labels. If a secondary axis is in use, this setting is ignored.

  [Default: `true`]

`storage = simple|memory|disk|policy|cache|basic-cache|persistent|parallel` (DataStoreFactory)
  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`.

  [Default: `simple`]

`texttype = plain|antialias|latex` (TextSyntax)
  Determines how to turn label text 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 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).

  [Default: `plain`]

`title = <value>` (String)
  Text of a title to be displayed at the top of the plot. If null, the default, no title is shown and there's more space for the graphics.
`x2func = <function-of-x>` (JELFunction)
  Defines a secondary X axis in terms of the primary one. If a secondary axis is defined in 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.

  The function supplied 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>` (String)
  Provides a string that will label the secondary X axis. This appears on the opposite side of the plot to the X axis itself.
`xanchor = true|false` (Boolean)
  If true, then zoom actions will work in such a way that the zero point on the X axis stays in the same position on the plot.

  [Default: `false`]

`xcrowd = <number>` (Double)
  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 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.

  [Default: `1`]

`xflip = true|false` (Boolean)
  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).

  [Default: `false`]

`xlabel = <text>` (String)
  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.

  [Default: `X`]

`xlog = true|false` (Boolean)
  If false (the default), the scale on the X axis is linear, if true it is logarithmic.

  Note this option is deprecated in favour of the `xscale` option, which offers more flexible axis scaling options.

  [Default: `false`]

`xmax = <number>` (Double)
  Maximum value of the data coordinate on the X axis. This sets the value before any subranging is applied. If not supplied, the value is determined from the plotted data.
`xmin = <number>` (Double)
  Minimum value of the data coordinate on the X axis. This sets the value before any subranging is applied. If not supplied, the value is determined from the plotted data.
`xpix = <int-value>` (Integer)
  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`.

  [Default: `500`]

`xscale = linear|log|asinh(<a>)|symlog(<t>,<s>)` (Scale)
  Defines the mapping of data to graphical coordinates on the X axis. Options are:
  - `linear`: Linear scale
  - `log`: Logarithmic scale
  - `asinh`: Scaling based on 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.

  [Default: `linear`]

`xsub = <lo>,<hi>` (Subrange)
  Defines a normalised adjustment to the data range of the X axis. The value may be specified as a comma-separated pair of two numbers, giving the 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`.

  [Default: `0,1`]

`y2func = <function-of-y>` (JELFunction)
  Defines a secondary Y axis in terms of the primary one. If a secondary axis is defined in 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 supplied 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.

`y2label = <text>` (String)
  Provides a string that will label the secondary Y axis. This appears on the opposite side of the plot to the Y axis itself.
`yanchor = true|false` (Boolean)
  If true, then zoom actions will work in such a way that the zero point on the Y axis stays in the same position on the plot.

  [Default: `false`]

`ycrowd = <number>` (Double)
  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 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.

  [Default: `1`]

`yflip = true|false` (Boolean)
  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).

  [Default: `false`]

`ylabel = <text>` (String)
  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.

  [Default: `Y`]

`ylog = true|false` (Boolean)
  If false (the default), the scale on the Y axis is linear, if true it is logarithmic.

  Note this option is deprecated in favour of the `yscale` option, which offers more flexible axis scaling options.

  [Default: `false`]

`ymax = <number>` (Double)
  Maximum 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.
`ymin = <number>` (Double)
  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.
`ypix = <int-value>` (Integer)
  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`.

  [Default: `400`]

`yscale = linear|log|asinh(<a>)|symlog(<t>,<s>)` (Scale)
  Defines the mapping of data to graphical coordinates on the Y axis. Options are:
  - `linear`: Linear scale
  - `log`: Logarithmic scale
  - `asinh`: Scaling based on 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.

  [Default: `linear`]

`ysub = <lo>,<hi>` (Subrange)
  Defines a normalised adjustment to the data range of the Y axis. The value may be specified as a comma-separated pair of two numbers, giving the 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`.

  [Default: `0,1`]

`zoomfactor = <number>` (Double)
  Sets the amount by which the plot view zooms in or out for each unit of mouse wheel movement. A value of 1 means that mouse wheel zooming has no effect. A higher value means that the mouse wheel zooms faster and a value nearer 1 means it zooms slower. Values below 1 are not permitted.

  [Default: `1.2`]

Next Previous Up Contents
Next: Examples
Up: plot2plane: Draws a plane plot
Previous: plot2plane: Draws a plane plot

STILTS - Starlink Tables Infrastructure Library Tool Set
Starlink User Note256
STILTS web page: http://www.starlink.ac.uk/stilts/
Author email: m.b.taylor@bristol.ac.uk
Mailing list: topcat-user@jiscmail.ac.uk