/usr/share/doc/stilts/sun256/tpipeExamples.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 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 | <html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" type="text/css" href="sun-style.css">
<title>Examples</title>
</head>
<body>
<hr>
<a href="tskymap.html">Next</a> <a href="tpipe-usage.html">Previous</a> <a href="tpipe.html">Up</a> <a href="index.html">Contents</a> <br> <b>Next: </b><a href="tskymap.html">tskymap: Calculates sky density maps</a><br>
<b>Up: </b><a href="tpipe.html">tpipe: Performs pipeline processing on a table</a><br>
<b>Previous: </b><a href="tpipe-usage.html">Usage</a><br>
<hr>
<h3><a name="tpipeExamples">B.35.2 Examples</a></h3>
<p>Here are some examples of <code>tpipe</code> in use with explanations
of what's going on. For simplicity these examples assume that you have the
<code>stilts</code> script installed and are using a Unix-like shell;
see <a href="invoke.html">Section 3</a> for an explanation of how to invoke the command
if you just have the Java classes.
</p>
<p>
<dl>
<dt><strong><pre>
stilts tpipe cat.fits
</pre></strong></dt>
<dd>Writes a FITS table to standard output in human-readable form.
Since no mode specifier is given, <code>omode=out</code> is assumed,
and output is to standard output in <code>text</code> format.
</dd>
<dt><strong><pre>
stilts tpipe cmd='head 5' cat.fits.gz
</pre></strong></dt>
<dd>Does the same as the last example, but with one processing step:
only the first five rows of the table are output. In this case,
the input file is compressed using gzip - this is automatically
detected.
</dd>
<dt><strong><pre>
stilts tpipe ifmt=csv xxx.csv \
cmd='keepcols "index ra dec"' \
omode=out ofmt=fits xxx.fits
</pre></strong></dt>
<dd>Reads from a comma-separated values file, writes to a FITS file,
and discards all columns in the input table apart from INDEX, RA and DEC.
Note the quoting in the <code>cmd</code> argument: the outer quotes
are so that the argument of the <code>cmd</code> parameter itself
(<code>keepcols "index ra dec"</code>)
is not split up by spaces (to protect it from the shell),
and the inner quotes are to keep the
<code>colid-list</code> argument of the
<code>keepcols</code> command together.
</dd>
<dt><strong><pre>
stilts tpipe ifmt=votable \
cmd='addcol IV_SUM "(IMAG+VMAG)"' \
cmd='addcol IV_DIFF "(IMAG-VMAG)"' \
cmd='delcols "IMAG VMAG"' \
omode=out ofmt=votable \
< tab1.vot \
> tab2.vot
</pre></strong></dt>
<dd>Replaces two columns by their sum and difference in a VOTable.
Since neither the <code>in</code> nor <code>out</code> parameters
have been specified, the input and output are actually byte
streams on standard input and standard output of the
<code>tpipe</code> command in this case.
The processing steps first add a column representing the sum,
then add a column representing the difference, then delete the
original columns.
</dd>
<dt><strong><pre>
stilts tpipe cmd='addskycoords -inunit sex fk5 gal \
RA2000 DEC2000 GAL_LONG GAL_LAT' \
6dfgs.fits 6dfgs+gal.fits
</pre></strong></dt>
<dd>Adds columns giving galactic coordinates to a table.
Both input and output tables are FITS files.
The galactic coordinates, stored in new columns named GAL_LONG and
GAL_LAT, are calculated from FK5 J2000.0 coordinates
given in the existing columns named RA2000 and DEC2000.
The input (FK5) coordinates are represented as sexagesimal strings
(hh:mm:ss, dd:mm:ss), and the output ones are numeric degrees.
</dd>
<dt><strong><pre>
stilts -disk tpipe 2dfgrs_ngp.fits \
cmd='keepcols "SEQNUM AREA ECCENT"' \
cmd='sort -down AREA' \
cmd='head 20'
</pre></strong></dt>
<dd>Displays selected columns for the 20 rows with largest values in
the AREA column of a FITS table. First the columns of interest
are selected, then the rows are sorted into descending order by
the value of the AREA column, then the first 20 rows of the resulting
table are selected, and the result is written to standard output.
Since a sort is being performed here, it's not possible to do all
the processing a row at a time, since all the AREA values
must be available for comparison during the sort.
Two things are done here to accommodate this fact: first the
column selection is done before the sort, so that it's only a 3-column
table which needs to be available for random access,
reducing the temporary storage required.
Secondly the <code>-disk</code> flag is supplied, which means that
temporary disk files rather than memory
will be used for caching table data.
</dd>
<dt><strong><pre>
stilts tpipe 2dfgrs_ngp.fits \
cmd='keepcols "SEQNUM AREA ECCENT"' \
cmd='sorthead -down 20 AREA'
</pre></strong></dt>
<dd>Has exactly the same effect as the previous example.
However, the algorithm used by the <code>sorthead</code> filter is
in most cases faster and cheaper on memory (only 20 rows ever have
to be stored in this case), so this is generally a better approach
than combining the <code>sort</code> and <code>head</code> filters.
</dd>
<dt><strong><pre>
stilts tpipe omode=meta cmd=@commands.lis http://archive.org/data/survey.vot.Z
</pre></strong></dt>
<dd>Outputs column and table metadata about a table.
In this case the table is a compressed VOTable at the end of a URL.
Processing is performed according to the commands contained in a
file named "commands.lis" in the current directory.
</dd>
<dt><strong><pre>
stilts tpipe in=survey.fits
cmd='select "skyDistanceDegrees(hmsToDegrees(RA),dmsToDegrees(DEC), \
hmsToDegrees(2,28,11),dmsToDegrees(-6,49,45)) \
< 5./60."' \
omode=count
</pre></strong></dt>
<dd>Counts the number of rows within a given 5 arcmin
cone of sky in a FITS table.
The <code>skyDistanceDegrees</code> function is an expression which
calculates the distance between the position specified in a row
(as given by its RA and DEC columns) and a given point on the sky
(here, 02:28:11,-06:49:45).
Since <code>skyDistanceDegrees</code>'s arguments and return value are in
decimal degrees, some conversions are required: the RA and DEC columns
are sexagesimal strings which are converted using the
<code>hmsToDegrees</code> and <code>dmsToDegrees</code> functions
respectively. Different versions of these functions (ones which take
numeric arguments) are used to convert the coordinates of the fixed
point to degrees.
The result is compared to a constant expression representing 5 arcminutes
in degrees.
Any rows of the input table for which this comparison
is true are included in the output.
An alternative function, <code>skyDistanceRadians</code> which works
in radians, is also available.
These functions and constants used here are described in detail in
<a href="uk.ac.starlink.ttools.func.CoordsDegrees.html">Section 10.5.14</a> and
<a href="uk.ac.starlink.ttools.func.CoordsRadians.html">Section 10.5.12</a>.
</dd>
<dt><strong><pre>
stilts tpipe ifmt=ascii survey.txt \
cmd='select "OBJTYPE == 3 && Z > 0.15"' \
cmd='keepcols "IMAG JMAG KMAG"' \
omode=stats
</pre></strong></dt>
<dd>Calculate statistics on the I, J and K magnitudes of selected
objects from a catalogue. Only those rows with the given OBJTYPE
and in the given Z range are included. The minimum, maximum,
mean, standard deviation etc of the IMAG, JMAG and KMAG columns
will be written to standard output.
</dd>
<dt><strong><pre>
stilts -classpath lib/drivers/mysql-connector-java.jar \
-Djdbc.drivers=com.mysql.jdbc.Driver \
tpipe in=x.fits cmd="explodeall" omode=tosql \
protocol=mysql host=localhost db=ASTRO1 dbtable=TABLEX \
write=dropcreate user=mbt
</pre></strong></dt>
<dd>Writes a FITS table to an SQL table, converting array-valued columns
to scalar ones.
To make the SQL connection work properly, the classpath is augmented
to include the path of the MySQL JDBC driver and the
<code>jdbc.drivers</code> system property is set to the JDBC driver
class name. The output will be written as a new table named TABLEX
in the MySQL database named ASTRO1 on a MySQL server on the
local host. The password, if required, will be prompted for,
as would any of the other required parameters if they had not been
given on the command line.
Any existing table in ASTRO1 with the name TABLEX is overwritten.
The only processing done here is by the <code>explodeall</code> command,
which takes any columns which have fixed-size array values and
replaces them in the output with multiple scalar columns.
</dd>
<dt><strong><pre>
java -classpath stilts.jar:lib/drivers/mysql-connector-java.jar
-Djdbc.drivers=com.mysql.jdbc.Driver \
uk.ac.starlink.ttools.Stilts \
tpipe in=x.fits \
cmd=explodeall \
omode=out \
out="jdbc:mysql://localhost/ASTRO1?user=mbt#TABLEX"
</pre></strong></dt>
<dd>This does exactly the same as the previous example, but achieves it
in a slightly different way. In the first place, java is invoked
directly with the necessary flags rather than getting the
<code>stilts</code> script to do it. Note that you cannot use java's
<code>-jar</code> flag in this case, because doing it like that
would not permit access to the additional classes that contain
the JDBC driver.
In the second place we use <code>omode=out</code> rather than
<code>omode=tosql</code>. For this we need to supply an <code>out</code>
value which encodes the information about the SQL connection and
table in a special URL-like format. As you can see, this is a bit
arcane, which is why the <code>omode=tosql</code> mode can be a help.
</dd>
<dt><strong><pre>
stilts tpipe USNOB.FITS cmd='every 1000000' omode=stats
</pre></strong></dt>
<dd>Calculates statistics on a selection of the rows in a catalogue,
and writes the result to the terminal.
In this example, every millionth row is sampled.
</dd>
</dl>
</p>
<hr><a href="tskymap.html">Next</a> <a href="tpipe-usage.html">Previous</a> <a href="tpipe.html">Up</a> <a href="index.html">Contents</a> <br> <b>Next: </b><a href="tskymap.html">tskymap: Calculates sky density maps</a><br>
<b>Up: </b><a href="tpipe.html">tpipe: Performs pipeline processing on a table</a><br>
<b>Previous: </b><a href="tpipe-usage.html">Usage</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>
|