Next Previous Up Contents
Next: Animation
Up: Plot Parameters
Previous: Global Parameters

8.1.2 Layer Parameters

The layer parameters come in groups, each specifying the details of one plot layer. Each layer type has its own list of parameters. A plot layer is introduced on the command line with a parameter of the form

and any other parameters with the same <suffix> are considered to apply to the same layer. In the basic example we considered:
   stilts plot2plane layer_1=mark in_1=cat.fits x_1=BMAG-RMAG y_1=BMAG
the suffix is "_1" and the layer type associated with it is mark (plotting markers to make a scatter plot). The different layer types are documented in Section 8.3, and each has its own set of parameters, some of which are mandatory and some which are optional with sensible defaults. In the documentation, the suffix is represented as "N". For instance the mark layer type requires you to specify an input table (inN) and point positions (xN and yN). Since the suffix we have used in the example for the layerN parameter is "_1", we have written in_1, x_1 and y_1. The mark layer has some optional style parameters as well, so we could adjust the plot's appearance by adding shape_1=cross size_1=4 color_1=blue.

You can have as many layers as you like (even none), so we could overplot two datasets from different input files like this:

   stilts plot2plane
       layer_1=mark in_1=cat1.fits x_1=BMAG-RMAG   y_1=BMAG  color_1=magenta size_1=5
       layer_2=mark in_2=cat2.fits x_2=mag_b-mag_r y_2=mag_b color_2=cyan    size_2=5
We have assigned different colours to the different layers and boosted the marker size to 5 pixels.

As a convenience, if the same value is used for all the layers, you can omit the suffix. So to avoid having to specify the same markers size for both layers, you can write instead:

   stilts plot2plane
       layer_1=mark in_1=cat1.fits x_1=BMAG-RMAG   y_1=BMAG  color_1=magenta
       layer_2=mark in_2=cat2.fits x_2=mag_b-mag_r y_2=mag_b color_2=teal
Although the size parameter no longer has an explicit suffix, it's still a layer parameter, it just applies to multiple layers. This shorthand works for all layer parameters. Here is another example which also shows how you can use the icmdN parameter to pre-process input data prior to performing the plot. Here, we make two different selections of the input rows to plot two different data sets.
   stilts plot2plane
          in=cat.fits x=BMAG-RMAG y=BMAG
          layer_1=mark icmd_1='select vel<1000'  color_1=blue
          layer_2=mark icmd_2='select vel>=1000' color_2=red
The input tables and data values are the same for both datasets, so we can just supply the parameters in, x and y, rather than in_1, in_2 etc.

Any string can be used as a suffix, including the empty string (though an empty string can cause confusion if there are multiple layers). The suffixing is also slightly more sophisticated than described above; to find parameters relating to a layer with a given suffix, the parameter looks first using the whole suffix, and strips single characters off it until it has none left. So if a layer is introduced with the parameter layer_ab, you can give the marker shape using any of the parameters shape_ab, shape_a, shape_ or shape. If more than one of these is present, the first one in that list will be used (the order in which they appear on the command line is not significant). This can be used to group sets of layers.

By default, if multiple layers are specified, they are plotted in the order in which the introducing layerN parameters appear on the command line. This may be relevant, since layers plotted later sometimes obscure ones plotted earlier. You can alter the order of plotting with the seq (global) parameter, which is a comma-separated list of layer suffixes giving the sequence in which layers should be plotted. So adding "seq=_2,_1" would cause layer _2 to be plotted before layer _1, instead of the other way round.

By default, if more than one layer is plotted, a legend will appear labelling the datasets. The dataset labels appearing in the legend are by default the layer suffixes specified on the command line. However, the labels can be given explicitly with the legendN parameter, so for instance in the example above leglabel_1=Slow leglabel_2=Fast would adjust the legend accordingly. Legend appearance and positioning can be adjusted by various leg* global parameters.

Next Previous Up Contents
Next: Animation
Up: Plot Parameters
Previous: Global Parameters

STILTS - Starlink Tables Infrastructure Library Tool Set
Starlink User Note256
STILTS web page:
Author email:
Mailing list: