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

       layer<suffix>=<layer-type>

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
           size=5
           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: http://www.starlink.ac.uk/stilts/
Author email: m.b.taylor@bristol.ac.uk
Mailing list: topcat-user@jiscmail.ac.uk