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=BMAGthe 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
marklayer type requires you to specify an input table (
inN) and point positions (
yN). Since the suffix we have used in the example for the
layerNparameter is "
_1", we have written
marklayer 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=5We 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=tealAlthough the
sizeparameter 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
icmdNparameter 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=redThe input tables and data values are the same for both datasets, so we can just supply the parameters
y, rather than
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
you can give the marker shape using any of the parameters
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
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
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
parameter, so for instance in the example above
leglabel_1=Slow leglabel_2=Fast would adjust the
Legend appearance and positioning can be adjusted by various
leg* global parameters.