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

	
	||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 ()
Contents ⋅ Previous ⋅ Next
©UDS/CNRS  Contact: Question@simbad