/usr/share/doc/stilts/sun256/plotSuffixes.html is in stilts-doc 3.1.2-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 | <html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" type="text/css" href="sun-style.css">
<title>Parameter Suffixes</title>
</head>
<body>
<hr>
<a href="jel.html">Next</a> <a href="plot.html">Previous</a> <a href="plot.html">Up</a> <a href="index.html">Contents</a> <br> <b>Next: </b><a href="jel.html">Algebraic Expression Syntax</a><br>
<b>Up: </b><a href="plot.html">Old-Style Plotting</a><br>
<b>Previous: </b><a href="plot.html">Old-Style Plotting</a><br>
<hr>
<h3><a name="plotSuffixes">9.1 Parameter Suffixes</a></h3>
<p><em>This section describes deprecated commands.
For recommended plotting commands, see <a href="plot2.html">Section 8</a>.
</em></p>
<p>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 <a href="plot2d-usage.html">Appendix B.12.1</a>,
you will see that a number of the parameters have the
suffixes "<code>N</code>" or "<code>NS</code>".
These suffixes can be substituted with any convenient string to identify
parameters which relate to the same input datasets or subsets.
Specifically:
<dl>
<dt><strong>Suffix "<code>N</code>":</strong></dt>
<dd>Denotes an input dataset. At least the <code>inN</code> parameter
must be given to identify the source of the data; any other parameters
with the same value of the <code>N</code> suffix relate to that dataset.
A <em>dataset</em> 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.
</dd>
<dt><strong>Suffix "<code>NS</code>":</strong></dt>
<dd>Denotes a particular subset of the rows in dataset <code>N</code>.
At least the <code>subsetNS</code> parameter must be given to
identify the expression by which the subset is defined;
any other parameters with the same value of the <code>NS</code> suffix
relate to that subset.
</dd>
</dl>
</p>
<p>Some examples will help to illustrate.
The following will generate a Cartesian plot of catalogue position
from a single dataset:
<pre>
stilts plot2d in=gals.fits xdata=RA ydata=DEC
</pre>
In this case the <code>N</code> suffix is present on each of the parameters
<code>in</code>, <code>xdata</code> and <code>ydata</code>, 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:
<pre>
stilts plot2d in1=gals.fits xdata1=RA ydata1=DEC
in2=stars.fits xdata2=RAJ2000 ydata2=DEJ2000
</pre>
The suffix values "<code>1</code>" and "<code>2</code>" are quite arbitrary
and can be chosen as convenient, so the following would do exactly the
same as the previous example:
<pre>
stilts plot2d in_GAL=gals.fits xdata_GAL=RA ydata_GAL=DEC
in_STAR=stars.fits xdata_STAR=RAJ2000 ydata_STAR=DEJ2000
</pre>
The other parameters which have the <code>N</code> suffix apply only
to the matching dataset, so for instance the following:
<pre>
stilts plot2d in1=gals.fits xdata1=RA ydata1=DEC txtlabel1=NGC_ID
in2=stars.fits xdata2=RAJ2000 ydata2=DEJ2000
</pre>
would draw text labels adjacent to the points from only the gals.fits file
giving the contents of its NGC_ID column.
</p>
<p>The <code>NS</code> suffix identifies distinct <em>row subsets</em>
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
<code>subsetNS</code> parameter.
If, as in all the examples we have seen so far,
no <code>subsetNS</code> 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 (<code>S=""</code>)
containing all rows has been specified.
So our earlier simple example:
<pre>
stilts plot2d in=gals.fits xdata=RA ydata=DEC
</pre>
is equivalent to
<pre>
stilts plot2d in=gals.fits xdata=RA ydata=DEC subset=true
</pre>
If we wish to split the plotted points into two sets based on their
R-B colours, we can write something like:
<pre>
stilts plot2d in=gals.fits xdata=RA ydata=DEC
subsetX='RMAG-BMAG>0' subsetY='RMAG-BMAG<=0'
</pre>
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
<code>NS</code> suffixes, for instance
<pre>
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
</pre>
Again, the suffix strings can be chosen to have any value as convenient.
</p>
<p>The dataset- and subset-specific parameters must be put
together if there are multiple datasets with multiple subsets to plot
simultaneously, for instance:
<pre>
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
</pre>
</p>
<p>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 <code>sequence</code> parameter.
For instance, to ensure that star data appears on top of galaxy data
in the plot, do the following:
<pre>
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
</pre>
</p>
<p>More examples can be found in the <b>Examples</b>
subsections of the individual plotting command descriptions in
<a href="cmdUsage.html">Appendix B</a>.
</p>
<hr><a href="jel.html">Next</a> <a href="plot.html">Previous</a> <a href="plot.html">Up</a> <a href="index.html">Contents</a> <br> <b>Next: </b><a href="jel.html">Algebraic Expression Syntax</a><br>
<b>Up: </b><a href="plot.html">Old-Style Plotting</a><br>
<b>Previous: </b><a href="plot.html">Old-Style Plotting</a><br>
<hr><i>STILTS - Starlink Tables Infrastructure Library Tool Set<br>Starlink User Note256<br>STILTS web page:
<a href="http://www.starlink.ac.uk/stilts/">http://www.starlink.ac.uk/stilts/</a><br>Author email:
<a href="mailto:m.b.taylor@bristol.ac.uk">m.b.taylor@bristol.ac.uk</a><br>Mailing list:
<a href="mailto:topcat-user@jiscmail.ac.uk">topcat-user@jiscmail.ac.uk</a><br></i></body>
</html>
|