The Python cdsclient package gather scripts to query large tables : wise, 2mass, sdss, Gaia, ... the package includes:
The vizquery program is a facility to query remotely VizieR. This program is part of the cdsclient package, and can run on any linux/unix platform. It reads the query parameters on its standard input, and writes the results of the query on the standard output in various formats including VOTable or FITSNote: it may happen that all specifications are not fully implemented; if some features are missing or not working, please contact us (click on the enveloppe at the bottom of this page)
Please refer to the cdsclient pages which includes all the details for the installation of vizquery.
Without any argument, vizquery displays a short help:
Usage: vizquery [-mime={html|ascii|votable|fits|binfits|tsv|csv|xml|acl|text}]
[-site=site] [{asu_constraints...|input_file_with_contraints}]
Constraints are given in ASU form (-list can be used for a list of targets)
vizquery -mime=text -source=I/239/hip_main HIP=1..10
by default constraints are asked on standard input.
(details at: http://vizier.cds.unistra.fr/doc/vizquery.htx
Sites are:
vizier.cds.unistra.fr (cds) (fr)
vizier.cfa.harvard.edu (cfa) (us)
vizier.hia.nrc.ca (cadc) (ca)
vizier.nao.ac.jp (adac) (jp)
data.bao.ac.cn (bejing) (cn)
vizier.ast.cam.ac.uk (cambridge) (uk)
www.ukirt.jach.hawaii.edu (ukirt) (hawaii)
vizier.inasan.ru (moscow) (ru)
|
| html | is the format used by the various browsers like Firefox, Mozilla or Internet Explorer, and presents the results in nicely formatted tables; however such a presentation requires a large amount of bytes, and is not quite easy to interpret by a program. |
| ascii | is also meant to be used by browsers, but here tables are presented as column-aligned bytes separated by blanks. It generates less bytes than the html output, but still includes HTML tags like links. |
| votable | is the format defined for the Virtual Observatory; its structure is defined in the VOTable Documentation (the corresponding cgi is /viz-bin/votable) |
| fits | is the ascii tabular format defined in the context of the Flexible Image Transport System (the corresponding cgi is /viz-bin/asu-fits). |
| binfits | is the binary tabular format defined in the context of the Flexible Image Transport System (BINTABLE extension) (the corresponding cgi is /viz-bin/asu-binfits). |
| tsv | is an ascii format where each column is separated from the next one by a tab character (with hexadecimal representation 09, and sometimes named Control-I) (the corresponding cgi is /viz-bin/asu-tsv). |
| csv | is a format similar to tsv, but the character used to separated the columns is the semicolon ; Other punctuation characters may be used to separate the columns – by just specifying the punctuation as the mime type: for instance -mime=';' has the same effect as -mime=csv. To separate the columns by a vertical bar, just use -mime='|'. |
| astrores | is a mixture of XML and TSV format also known as Astrores; it is the original format developped for the communication to the Aladin integrator (the corresponding cgi is /viz-bin/asu-xml). |
| acl | is the format required by SkyCat and used e.g. by Gemini tools (the corresponding cgi is /viz-bin/asu-acl). |
| text | is a simple aligned asci text output (text/plain mime type) (the corresponding cgi is /viz-bin/asu-txt). |
When no constraint is given as arguments or via a file, the query specifications are assumed to be in the standard input (i.e. typed at the terminal or included in the script with the Unix <<sentinel convention).
Each line of the input to vizquery may contain the following:
Specifying a Choice of Catalogues: there are several ways of designating catalogues; the fastest is to use the catalog identification assigned in VizieR like -source=I/239/hip_main for the main Hipparcos catalog.
| -source= | catalog(s) to query
(Several catalogs may be specified if separated by
a comma or a blank). Well-known catalog abbreviations may be used – the full list of abbreviations known in VizieR can be listed. | ||||||||
| -words= | names or words of title of catalog. The words are and'ed, i.e. only the catalogues characterized by all the words are selected. | ||||||||
| -kw= | keyword in any of the 3 lists by Wavelength,
Mission, or Astronomy. If several keywords are given on the line, they are or'ed; but if several lines with -kw=value exist, their content is and'ed. | ||||||||
| -ucd= | designation of UCD The catalogues having one or more columns matching the specified UCD(s) are selected; the * may be used as a wild character, e.g. PHOT_*_B represents a blue photometry which can be in a lot of different photometric systems. Several -ucd=value can be used to select catalogues having simulteously the properties specified by the UCDs; in other terms, similalry to -kw, UCDs specified on the same line are or'ed, while the different lines are and'ed. | ||||||||
| -pos | restricts to tables containing celestial positions | ||||||||
| -phot | restricts to tables containing well-defined photometry | ||||||||
| -nosurvey | restricts the choice to catalogues outside the ``survey'' list of catalogues. | ||||||||
| -obsolete | asks to include the obsoleted versions of catalogues in the set. | ||||||||
| -corr= | correlation for a fine-grain selection of tables:
|
Target Center: the specification of a target requires a center – a position in the sky – and a geometry around the center. Only a circle/annulus, and a rectangular box, are available.
| -c= | defines the center of the target There are many possibilities of specifying the center – by object name, position in sexagesimal or decimal degrees. For equatorial positions, remember that a sign must exist before the declination, and that no decimal point in the RA part implies a sexagesimal position (i.e. 15 +12 means 15h+12°, but 15.+12 means 15°+12°, or 1h+12°. |
| -c.eq= | defines the equinox of the position given in
the -c argument. Note that this parameter
is not useful when the target is specified by a name. Typical examples are -c.eq=B1950 or -c.eq=Gal The default is -c.eq=J2000 |
| -c.rm= | defines the radius of the target in arcminutes. Two numbers may be specified: in the case, the target is an annulus. |
| -c.rd= | defines the radius of the target in degrees. |
| -c.rs= | defines the radius of the target in arcsec. |
| -c.bm= | defines a rectangular box of horizontal/vertical dimensions in arcmin, as e.g. -c.bm=8x6 |
| -c.bd= | defines a rectangular box in degrees |
| -c.bs= | defines a rectangular box in arcsec. |
| -box= | defines a rectangular box using IAU-conventions, e.g.
J0000-00 for a box
in J2000 coordinates containing the positions
having their RA between 0h0m and 0h1m
and their declination between 0° and –1°
This convention is valid also with other coordinate systems:
Bhhmm...±dd... (B1950 position),
Glon...±lat... (galactic position),
S... (supergalactic)
and E (ecliptic). Finally a box may also be represented by a qbox value, the systems of cells used to access by positions (described briefly in the qbox man page) |
Output Contents: the contents and order of the result can be specified by the following arguments:
| -meta | No actual query is performed, only the tables involved in the query are described. This is useful to get an idea of which catalogues exist which share e.g. a keyword. | ||||||||||||||||||||||||||||||||||||||
| -meta.all | similar to -meta, but all metadata (details of columns) are listed. | ||||||||||||||||||||||||||||||||||||||
| -meta.max= | specifies the maximal number of catalogs to be listed (the default is 500) | ||||||||||||||||||||||||||||||||||||||
| -out= | specifies the result columns to list in the output;
-out= is normally followed by a list of column names
(separated by blanks)
to be displayed. The list may contain, in addition to standard column names:
| ||||||||||||||||||||||||||||||||||||||
| -out.all | Display all columns (i.e. -out.all is equivalent to -out=**) | ||||||||||||||||||||||||||||||||||||||
| -out.add= | List of columns to add to the standard set, e.g. -out.add=_r lists the distance to the target | ||||||||||||||||||||||||||||||||||||||
| -out.max= | Maximal number of rows to retrieve (default is 50) | ||||||||||||||||||||||||||||||||||||||
| -out.meta= | Some options on the descriptions of the columns,
as a set of characters referring to the possible additional details;
the list may be preceded by + or - for addition or
removal of the following elements:
The default is huD; to get for instance the 2 UCDs, add -out.meta=+2 | ||||||||||||||||||||||||||||||||||||||
| -out.form= | Some options on the output:
| ||||||||||||||||||||||||||||||||||||||
| -sort= | Sort order, e.g. -sort=_r to sort by increasing distance to the target. A minus sign before the column name (e.g. -sort=-_r) indicates a decreasing order. | ||||||||||||||||||||||||||||||||||||||
| -oc.form | form of the computed position, as -oc.form=d for decimal degrees, or-oc.form=s for sexagesimal representations. An optional M (Main) can be added to specify that the UCD qualification main main is added to the computed position (by default this main qualification is attached to the original position) |
Joining tables: Two or more tables can be combined or joined into a single table; some details and examples can be found in the join documentation. The following argments are specific to joins:
| -joincol | specifies the column used in the join (the name must be shared among the tables involved). |
| -outjoin | specifies the table.column of the referent column in the case of outer joins. |
Issuing several queries: Independant queries can be issued in a single request, using a -go separator. More control can be specified in the case of votable output:
The full syntax of the way to specify constraints (what is at the right of the leftmost equal sign) is detailed in the Qualification Syntax.
Long lists of contraints on one parameter – typically a list of targets (positions on the sky) or values asked in one column of a table – can be stored in a plain ascii file and referred in the -list argument.
Assuming that the file myTargets.txt contains the list of targets (set of positions or object names, 1 per line; the semi-colon (;) can be used for in-line comments) the command
vizquery -source=PPMXL -out.add=_r -list=-c=myTargets.txt
will deliver the sources found in the PPMXL catalog around each of the positions specified, with their distance from the sources specified in the myTargets.txt file.
If a constraint other than the position is supplied in a file, the name of the column of the table corresponding to the parameter is specified after the list, as in the example below
Note that lists are more generic than just lists of targets: the -c= expresses that the constraints given in the list concern the position. But other possibilities exist: an example below queries a list of Hipparcos stars.
The examples are shown in 2 dialects: either a single command line possibly referencing a file, or with the use of a delimiter ====End to indicate to the shell where the standard input starts and ends. This delimiter can be changed to any other valid delimiter (word excluding the characters meaningful to the shell like spaces, asterisks, brackets, questions marks, ampersand, ...); alternatively if the query arguments are saved in a file named e.g. myQueryArguments , the standard shell redirection can be used and the first example could be written
vizquery -mime=tsv < myQueryArguments
vizquery -mime=csv -source=2MASS,USNO-A2 -out.add=_r -sort=_r -c="HD 226868" -c.rm=2
Alternatively, with the ASU commands in the standard input:
vizquery -mime=csv <<====End # Query All Columns of 2MASS and Tycho-2 Catalogues around HD 226868 -source=2MASS,USNO-A2 -out.all -out.add=_r -sort=_r -c=HD 226868 -c.rm=2 ====End
vizquery -mime=csv -source=HIP/hip_main -out.max=9999 -oc.form=D -out="Plx _RAJ2000 _DEJ2000 HIP Vmag B-V" -sort="-Plx" Plx=">50"
Alternatively, with the ASU commands in the standard input:
vizquery -mime=csv <<====End # Retrieve Hiparcos stars closer than 20pc (Plx > 50mas) # and order the results by decreasing parallax # (i.e. increasing distance from the Sun) -source=HIP/hip_main -out.max=9999 -oc.form=D -out=Plx, _RAJ2000, _DEJ2000, HIP, Vmag, B-V -sort=-Plx Plx=>50 ====End
The traditional way is:
vizquery -mime=votable <<====End ### Example of a list of Targets for vizquery usage ####################### -source=USNO-B1 # VizieR uses catalog numbers -- would work also with #-source=I/284 -out.max=9999 #-out.add=_1 asks to insert my target as the first output column -out.add=_1 # I need the distance of the found objects, too. -out.add=_r # Be as concise as possible -- don't create a new table for each target -out.form=mini # My output looks better sorted by increasing distance to each target. -sort=_r # Max distance to the target: 1arcmin -c.rm=1 # Now comes the list of my targets: -c=<<====MyList # Some random position in (RA,Dec) 123.5-12.68 ; random position # The First Quasar 3C 273 # The only supernova brighter than 6mag SN 1987A # 2 bright stars used for checking alpha Cen alpha UMi ====MyList ====End
A probably simpler way, assuming that the file MyList.txt contains what is between the markers ====MyList, would be
vizquery -mime=votable -source=USNO-B1 -out.max=9999 -out.add=_1 -out.add=_r -out.form=mini -sort=_r -list=MyList.txt
vizquery -mime=votable <<====End ### Example of a list of Targets for vizquery usage ####################### -source=HIP/hip_main #-out.add=_1 asks to insert my Hipparcos number as leftmost column. -out.add=_1 # Be as concise as possible -- don't create a new table for each star -out.form=mini # Get all parameters of the Hipparcos main table -out.all # Now comes the list of my Hipparcos numbers: HIP=<<====myHIPsample # In fact, I want just Hipparcos stars 1 to 10, # 101 to 110, 1001 to 1010, 10001 to 10010, and 100001 to 100010 1..10 101..110 1001..1010 10001..10010 100001..100010 ====myHIPsample ====End
The simpler way would be, if myHIPsample.txt contains the text between the myHIPsample markers:
vizquery -mime=votable -source=HIP/hip_main -out.add=_1 -out.form=mini -out.all -list=HIP=myHIPsample.txt