The ``vizquery'' program

5.1  The Python-cdsclient package

The Python cdsclient package gather scripts to query large tables : wise, 2mass, sdss, Gaia, ... the package includes:

Download Python-cdsclient

5.2  The old vizquery program

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 FITS

Note: 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)

5.2.1  Package Installation

Please refer to the cdsclient pages which includes all the details for the installation of vizquery.

5.2.2  Calling the program

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)

5.2.3  Input to vizquery

The input_file_with_contraints (standard input by default if no contraint is given to the vizquery ) specifies what to query in VizieR: which catalog(s), which position to look at, what to display, how many records, etc... written as 1 query argument per line. The query definitions follow the ASU protocol, using the name=value paradigm; submitting list of targets is detailed below.

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:
-corr=pos restricts to tables having a position;
-corr=name=col_name restricts to tables having the specified col_name among its columns;
-corr=PK=col_name restricts to tables having the specified col_name and this column is a primary key of the table;
-corr=FK=col_name restricts to tables having the specified col_name and this column is a foreign key of the table;

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 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:
  • computed columns: names starting by an underscore (_)
    _r Distance from the target center
    _x Horizontal distance from the target center (East)
    _y Vertical distance from the target center (North)
    _pa Position angle (North through East) of vector from the target center (degrees)
    _key The column representing a key (identifier) of a row (typically the recno counter when that one exists)
    _ID a string which identifies a row, in the form name=value (typically recno=record_counter)
    _RA(Equinox, Epoch) Computed right ascension for a specified frame / equinox / epoch with the standard conventions: ICRS represents the ICRS frame, J2000 represents the FK5(J2000)/ICRS frame, and B1950 the FK4(B1950) frame.
    _RA _RAJ or _RAJ2000 are a shorthand for _RA(J2000,J2000)
    _RAJ() is a shorthand for _RA(J2000) (keeping the epoch)
    _RAB or _RAB1950 are a shorthand for _RA(B1950,B1950).
    _DE(Equinox, Epoch) Computed declination, using the same conventions as _RA
    _GLON Computed galactic longitude
    _GLAT Computed galactic latitude
    _SGLAT Computed supergalactic latitude
    _SGLON Computed supergalactic longitude
    _1 Name of target or input constraint (applies to lists)
    _q Counter (from 1) of target number (applies to lists)
    _V A http link to the row being edited. _V may be followed by a text which will be used in the link.
    _sed0 Minimal details to build an SED (Spectral Energy Distribution): edit the columns containing magnitudes or fluxes in well-identifier filters, wavelengths or frequencies.
    _sed1 In addition to _sed0, compute the flux (in Jy)
    _sed3 Present the SED as 3 vectors: (1) frequencies (GHz), (2) fluxes (Jy) and (3) errors on fluxes (Jy)
    _sed4 Present the SED as a set of formatted SED points; one point is formatted as GHz=Jy[errJy]${col}[filter] e.g. 241.77e+3=31.3[0.8]e-3${Jmag}[2MASS:J] for a flux in the 2MASS J-band, or 353.00=8.91[0.21]${S}@{Freq} for a flux from the column S and the frequency from the column Freq.

  • ucd-specified columns: names starting with an asterisk * and followed by an UCD like e.g. *meta.id;meta.main
  • columns with links to images: *Mime(image/fits)
  • the list of the default columns: specified by a single asterisk *
  • the list of all columns: specified by a double asterisk **
-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:
h (header) add the column names
u (unit) add the units of each column
U (UCD1) give the UCD1 (default is UCD1+)
2 (2UCDs) give the two UCDs (UCD1 and UCD1+)
D (Description) adds the description of columns
L (Links) add the definition of Links (may result in more columns than what was asked)

The default is huD; to get for instance the 2 UCDs, add   -out.meta=+2
-out.form= Some options on the output:
DTD (for VOTable output): use the DTD definition rather than the standard XML-Schema
bin64 (for VOTable output): use a binary 64-encoded output for the data
TSV (for VOTable output): use a Tab-Separated-Values representation of the data (the Astrores way)
groups (for VOTable output): use the groups of columns introduced in VOTable1.1
mini (for lists): minimize the output, i.e. keep a single table which gathers the results of the list (the list must be applied to a single table)
-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:

5.2.4  Constraints on columns

Any column (including the computed columns) can be constrained, e.g. specifying a range of values, of matching some pattern for the The generic way of specifying a contraint is column_name=constraint, e.g. Vmag=<12.5 to specify that only rows for which the column named Vmag is less than 12.5 are to be selected.

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.

5.2.5  Using lists in vizquery

There are 2 ways to specify a list of targets in vizquery :

  1. with the -list argument (introduced in July 2010)

    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

  2. the traditional way consists in embedding the list of targets in the input stream with the following conventions: An example of a query of a list of targets is given 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.

5.2.6  Examples

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

  1. Query the catalogues em 2MASS and USNO-A2 2arcmin around the object HD 226868, with distances to the target:

    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
    

  2. List nearby stars from the Hipparcos catalog, orderd by increasing distances from the Sun (decreasing parallaxes):

    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
    

  3. Query the USNO-B1 around a list of targets, and get the result as a VOTable

    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

  4. Query all parameters of the Hipparcos main catalog, and give the result as a VOTable for a sample of Hipparcos stars.

    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


10-Jul-2010 — François Ochsenbein () /srv/httpd/Pages/catstd/vizquery.htx