Here are some examples of
tpipe in use with explanations
of what's going on. For simplicity these examples assume that you have the
stilts script installed and are using a Unix-like shell;
see Section 3 for an explanation of how to invoke the command
if you just have the Java classes.
stilts tpipe cat.fits
omode=outis assumed, and output is to standard output in
stilts tpipe cmd='head 5' cat.fits.gz
stilts tpipe ifmt=csv xxx.csv \ cmd='keepcols "index ra dec"' \ omode=out ofmt=fits xxx.fits
cmdargument: the outer quotes are so that the argument of the
cmdparameter itself (
keepcols "index ra dec") is not split up by spaces (to protect it from the shell), and the inner quotes are to keep the
colid-listargument of the
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
outparameters have been specified, the input and output are actually byte streams on standard input and standard output of the
tpipecommand 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.
stilts tpipe cmd='addskycoords -inunit sex fk5 gal \ RA2000 DEC2000 GAL_LONG GAL_LAT' \ 6dfgs.fits 6dfgs+gal.fits
stilts -disk tpipe 2dfgrs_ngp.fits \ cmd='keepcols "SEQNUM AREA ECCENT"' \ cmd='sort -down AREA' \ cmd='head 20'
-diskflag is supplied, which means that temporary disk files rather than memory will be used for caching table data.
stilts tpipe 2dfgrs_ngp.fits \ cmd='keepcols "SEQNUM AREA ECCENT"' \ cmd='sorthead -down 20 AREA'
sortheadfilter 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
stilts tpipe omode=meta email@example.com http://archive.org/data/survey.vot.Z
stilts tpipe in=survey.fits cmd='select "skyDistanceDegrees(hmsToDegrees(RA),dmsToDegrees(DEC), \ hmsToDegrees(2,28,11),dmsToDegrees(-6,49,45) \ < 5./60."' \ omode=count
skyDistanceDegreesfunction 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
skyDistanceDegrees'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
dmsToDegreesfunctions 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,
skyDistanceRadianswhich works in radians, is also available. These functions and constants used here are described in detail in Section 9.5.15 and Section 9.5.7.
stilts tpipe ifmt=ascii survey.txt \ cmd='select "OBJTYPE == 3 && Z > 0.15"' \ cmd='keepcols "IMAG JMAG KMAG"' \ omode=stats
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
jdbc.driverssystem 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
explodeallcommand, which takes any columns which have fixed-size array values and replaces them in the output with multiple scalar columns.
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"
stiltsscript to do it. Note that you cannot use java's
-jarflag 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
omode=tosql. For this we need to supply an
outvalue 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
omode=tosqlmode can be a help.
stilts tpipe USNOB.FITS cmd='every 1000000' omode=stats