Next Previous Up Contents
Next: Algebraic Expression Syntax
Up: Old-Style Plotting
Previous: Old-Style Plotting

9.1 Parameter Suffixes

This section describes deprecated commands. For recommended plotting commands, see Section 8.

Some of the parameters for the plotting tasks behave a little bit differently to other parameters in STILTS, in order to accommodate related sets of values. If you look at the usage of one of the plotting commands, for instance in Appendix B.14.1, you will see that a number of the parameters have the suffixes "N" or "NS". These suffixes can be substituted with any convenient string to identify parameters which relate to the same input datasets or subsets. Specifically:

Suffix "N":
Denotes an input dataset. At least the inN parameter must be given to identify the source of the data; any other parameters with the same value of the N suffix relate to that dataset. A dataset here refers to a particular set of plot data from a table; in most cases each input table corresponds to a different dataset, though two datasets may correspond to different sets of columns from the same table.
Suffix "NS":
Denotes a particular subset of the rows in dataset N. At least the subsetNS parameter must be given to identify the expression by which the subset is defined; any other parameters with the same value of the NS suffix relate to that subset.

Some examples will help to illustrate. The following will generate a Cartesian plot of catalogue position from a single dataset:

   stilts plot2d in=gals.fits xdata=RA ydata=DEC
In this case the N suffix is present on each of the parameters in, xdata and ydata, but is equal to the empty string, hence invisible. This is perfectly legal, and convenient when only a single table is in use. If we wish to overplot two datasets however, the dataset suffixes (or one of them at least) have to be made explicit so that different ones can be used, for instance:
   stilts plot2d in1=gals.fits  xdata1=RA      ydata1=DEC
                 in2=stars.fits xdata2=RAJ2000 ydata2=DEJ2000
The suffix values "1" and "2" are quite arbitrary and can be chosen as convenient, so the following would do exactly the same as the previous example:
   stilts plot2d in_GAL=gals.fits   xdata_GAL=RA       ydata_GAL=DEC
                 in_STAR=stars.fits xdata_STAR=RAJ2000 ydata_STAR=DEJ2000
The other parameters which have the N suffix apply only to the matching dataset, so for instance the following:
   stilts plot2d in1=gals.fits  xdata1=RA      ydata1=DEC     txtlabel1=NGC_ID
                 in2=stars.fits xdata2=RAJ2000 ydata2=DEJ2000
would draw text labels adjacent to the points from only the gals.fits file giving the contents of its NGC_ID column.

The NS suffix identifies distinct row subsets within the same or different datasets. A subset is defined by supplying a boolean inclusion expression (each row is included only if the expression evaluates true for that row) as the value of a subsetNS parameter. If, as in all the examples we have seen so far, no subsetNS parameter is supplied for a given dataset, then it is treated as a special case, as if a single subset with a name equal to the empty string (S="") containing all rows has been specified. So our earlier simple example:

   stilts plot2d in=gals.fits xdata=RA ydata=DEC
is equivalent to
   stilts plot2d in=gals.fits xdata=RA ydata=DEC subset=true
If we wish to split the plotted points into two sets based on their R-B colours, we can write something like:
   stilts plot2d in=gals.fits xdata=RA ydata=DEC
                 subsetX='RMAG-BMAG>0' subsetY='RMAG-BMAG<=0'
This will generate a plot with two subsets shown using different colours and/or plotting symbols. These colours and symbols are selected automatically. More control over the appearance can be exercised by setting values for some of the other parameters with NS suffixes, for instance
   stilts plot2d in=gals.fits xdata=RA ydata=DEC
                              subset_A='RMAG-BMAG>0'  colour_A=blue
                              subset_B='RMAG-BMAG<=0' colour_B=red
Again, the suffix strings can be chosen to have any value as convenient.

The dataset- and subset-specific parameters must be put together if there are multiple datasets with multiple subsets to plot simultaneously, for instance:

   stilts plot2d in_1=gals.fits  xdata_1=RA ydata_1=DEC
                                 subset_1_A='RMAG-BMAG>0'  colour_1_A=blue
                                 subset_1_B='RMAG-BMAG<=0' colour_1_B=red
                 in_2=stars.fits xdata_2=RAJ2000 ydata_2=DEJ2000
                                 colour_2=green

Finally, it's not quite true that the suffixes chosen have no effect on the plot; they may influence the order in which sets are plotted. Markers drawn for sets plotted earlier may be obscured by the markers drawn for sets plotted later, so this can affect the appearance of the plot. If you want to control this, use the sequence parameter. For instance, to ensure that star data appears on top of galaxy data in the plot, do the following:

   stilts plot2d in_GAL=gals.fits   xdata_GAL=RA       ydata_GAL=DEC
                 in_STAR=stars.fits xdata_STAR=RAJ2000 ydata_STAR=DEJ2000
                 sequence=_GAL,_STAR

More examples can be found in the Examples subsections of the individual plotting command descriptions in Appendix B.


Next Previous Up Contents
Next: Algebraic Expression Syntax
Up: Old-Style Plotting
Previous: Old-Style Plotting

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