B.3.2 Examples

Here are some examples of coneskymatch:

stilts coneskymatch serviceurl=http://archive.stsci.edu/hst/search.php \
                    in=messier.xml sr=0.05 out=matches.xml

This queries the HST cone search service from Space Telescope for records within .05 degrees of each Messier object contained in a local VOTable messier.xml. The sky positions in the input catalogue are guessed from the available table metadata. The result is written to a new VOTable, matches.xml. Since the servicetype parameter is not given, the default (cone search) service type is assumed.

stilts coneskymatch
       servicetype=sia \
       serviceurl=http://irsa.ipac.caltech.edu/cgi-bin/2MASS/IM/nph-im_sia?type=ql&ds=asky \
       in=messier.xml ra=RA dec=DEC \
       dataformat=image/fits \
       out=fitsimages.xml

This is similar to the previous example, but instead of querying an HST cone search server for catalogue objects near the input table positions, it queries a 2MASS Simple Image Access (SIA) server for images. It also explicitly names the columns holding the J2000 positions of reach record in the input catalogue as RA and DEC. The search radius parameter (sr) is not set here; for SIA queries the default search radius is zero, which has the special meaning of including any image which covers the requested position. Setting dataformat=image/fits (which is the default) requests only records describing FITS-format images to be returned; setting it to an empty value might return other formats such as JPEG too.

stilts coneskymatch \
       serviceurl='http://www.nofs.navy.mil/cgi-bin/vo_cone.cgi?CAT=NOMAD' \
       in=vizier.xml#7 \
       icmd='addskycoords -inunit sex fk4 fk5 RAB1950 DEB1950 RAJ2000 DEJ2000' \
       icmd='progress'
       ra=RAJ2000 dec=DEJ2000 sr=0.01 \
       ocmd='replacecol -units deg RA hmsToDegrees(RA[0],RA[1],RA[2])' \
       ocmd='replacecol -units deg DEC dmsToDegrees(DEC[0],DEC[1],DEC[2])' \
       omode=topcat

In this example some pre-processing of the input catalogue and post-processing of the output catalogue is performed as well as the multiple cone search itself.

The input catalogue, which is the 8th TABLE element in a VOTable file, contains sky positions in sexagesimal FK4 (B1950) coordinates. The icmd=addskycoords... parameter specifies a filter which will add new columns in FK5 (J2000) degrees, which are what the coneskymatch command requires. The icmd=progress parameter specifies a filter which will write progress information to the terminal so you can see how the queries are progressing.

The NOMAD service specified by the serviceurl parameter used here happens to return results with the RA/DEC columns represented in a rather eccentric format, namely 3-element floating point arrays representing (hours,minutes,seconds)/(degrees,minutes,seconds). The two ocmd=replacecol... filters replace the values of these columns with the scalar equivalents in degrees. Finally, the omode=topcat parameter causes the result table to be loaded directly into TOPCAT (if it is available).

stilts coneskymatch serviceurl='http://archive.stsci.edu/iue/search.php?' \
                    in=queries.txt ifmt=ascii \
                    ra='$1' dec='$2' \
                    sr='$3' copycols='$4' \
                    out=found.fits

Here the input is a plain text table with four unnamed columns, giving in order the right ascension, declination, positional error and name of target objects. The command carries out a cone search to the named service for each one. Note in this case the search radius (sr parameter) is taken from the table and so varies for each query. The copycols parameter has the value '$4', which means that the value of the fourth column of the input table will be prepended to each row of the output table for which it is responsible. Output is to a FITS table.