VizieR help - FAQ - Tutorial

Query VizieR using the batch mode.

5.1  The program

vizquery

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.1.1  Package Installation

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

5.1.2  Calling the program

Without any argument, 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.u-strasbg.fr/doc/vizquery.htx 
   Sites are:
	vizier.u-strasbg.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.1.3  Input to

The input_file_with_contraints (standard input by default if no contraint is given to the ) 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 paradigm; submitting list of targets is detailed below.

Each line of the input to may contain the following:

[missing file: asu-arg.htx]

5.1.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 , e.g. 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.1.5  Using lists in

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

  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

    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:
    • the list comes after the other qualifications, e.g. enter contraints on fluxes (e.g. ) before giving the list of targets
    • the list of targets starts by a line

      where myName can be replaced by a name of your choice (a suggestion: use the name of the file containing the targets)
    • each subsequent line, until the a line starting by , contain a target name (e.g. M99) or position (e.g. 01 23 45.6 +10 20 30), or a comment; there are possibilities of using sexagesimal or decimal values, see the various possibilities of specifying the center. Comments are lines starting by a hash (#); blank lines are ignored.
    • the line starting by closes the list.
    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 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.1.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

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

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

    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

  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:


10-Jul-2010 — François Ochsenbein ()

last update: 5 Sep 02:54