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 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.