Commandline Utilities

This page lists a number of command-line utilities that can be used to work with the VO. These utilities display help when passed the --help flag, and show some examples of use when called with --examples.

The utilities are implemented as Python scripts which call functions of the AstroRuntime. Therefore you must launch VODesktop (which contains AstroRuntime) before making use of these utilities.

Data Access

These utilities retrieve data from VO services

cone.py

Performs a cone search against a catalogue. Returns the result as a VOTable, comma-separated-values, or view to a web-browser or plastic application (e.g. Topcat)

Download cone.py

 
Usage: cone.py [options] <radius> {<ra> <dec>| <object-name>}

Options:
  -h, --help            show this help message and exit
  -f FORMAT, --format=FORMAT
                        format to return results in: votable, csv, plastic,
                        browser (default: csv)
  -s ID, --service=ID   RegistryID or URL endpoint of the Cone Service to
                        query (default: ivo://fs.usno/cat/usnob)
  -b FILTER, --browse=FILTER
                        browse cone services that match a FILTER in a GUI, and
                        exit
  -l FILTER, --list=FILTER
                        list cone services that match a FILTER, and exit
  -e, --examples        display some examples of use and exit.

     
examples:

cone.py -b abell
        : browse all cone services that match 'abell'

cone.py 0.1 m32 
        : search of radius 0.1 decimal degree around m32, display results as csv

cone.py 0.1 83.822083 -5.391111
        : search of 0.1 decimal degree around a position, return results as csv

cone.py --service=ivo://nasa.heasarc/abell 0.2 m54
        : query a specific service by giving it's registry resource ID.

cone.py --service=http://some.catalogue.service/endpoint 0.2 ngc123
        : search a specific service by giving it's endpoint  

cone.py -fvotable 0.1 83.822083 -5.391111
        : do a search, return results as votable

cone.py --format=plastic 0.1 83.822083 -5.391111
        : send results to a running plastic application (e.g. Topcat)

cone.py -fbrowser 0.1 83.822083 -5.391111
        : do a search, display result in the system webbrowser

siap.py

Performs a search for images against a SIAP service. Returns the result as a VOTable, comma-separated-values, or view in a plastic application (e.g. Topcat) or system webbrowser. Can optionally download some or all of the images located. This script will work fairly well with SSAP (spectral access) services too.

Download siap.py

 
Usage: siap.py [options] <radius> {<ra> <dec>| <object-name>}

Perform an image search and display results, optionally download images

Options:
  -h, --help            show this help message and exit
  -f FORMAT, --format=FORMAT
                        format to return results in:  votable, csv, plastic,
                        browser (default: csv)
  -s ID, --service=ID   RegistryID or URL the Image Service to query (default:
                        ivo://nasa.heasarc/skyview/rass)
  -d n|ALL, --download=n|ALL
                        number of images to download (default: none)
  -b, --browse          browse all known SIAP services in a GUI, and exit
  -e, --examples        display some examples of use and exit.     
     

siap.py 0.1 m32 
        : search of radius 0.1 decimal degree around m32, display results as csv
        
siap.py --download=all 0.1 m32 
        : do same search, and save all images to local directory.
        
siap.py -d4 0.1 m32 
        : same search, save first 4 images to local directory

siap.py --service=ivo://adil.ncsa/targeted/SIA -d3 0.2 m54
        : query a specific service by giving it's registry resource ID.  

siap.py --service=http://some.siap.service/endpoint 0.1 45.6 -10.23
        : search a specific service by giving it's endpoint
        
siap.py -fvotable 0.1 83.822083 -5.391111
        : do a search, return results as votable
            
siap.py --format=plastic 0.1 ngc123
        : send results to a running plastic application (e.g. Topcat)
    
siap.py --format=browser 0.1 83.822083 -5.391111
        : do a search, display result in the system webbrowser

sesame.py

Resolve an object name to a position in decimal degrees or sexagesimal, or display all known aliases of the object name. Uses the CDS Sesame service.

Download sesame.py

 
Usage: sesame.py [options] <object-name>

Options:
  -h, --help      show this help message and exit
  -a, --all       Display full information for this object
  -d, --decimal   Return position in decimal degrees (default)
  -s, --sexa      Return position in sexagesimal
  -e, --examples  display some examples of use and exit.
    
    
sesame.py m32
    : resolve position of m32 in decimal degrees
    
sesame.py --sexa m54
    : resolve position of m54 in sexagesimal
    
sesame.py --all crab
    : display full information about object 'crab'

adql.py

Use ADQL (a version of SQL) to query a database service (DSA).

Download adql.py

     
Usage: adql.py [options] <adql-query> | <query-file>

Options:
  -h, --help            show this help message and exit
  -f FORMAT, --format=FORMAT
                        format to return results in: vot, votbin, csv, plastic
                        (default: csv)
  -s ID, --service=ID   RegistryID of the DSA to query (default:
                        ivo://wfau.roe.ac.uk/ukidssDR1-dsa/wsa/ceaApplication)
  -i, --inputfile       read query from a file
  -q, --query           read query from commandline (default)
  -m MYSPACE_LOCATION, --myspace=MYSPACE_LOCATION
                        use a myspace file to stage the result (useful for
                        large queries)
  -b, --browse          browse all known queryable databases in a GUI, and
                        exit
  -l, --list            list all known queryable database services, and exit
  -e, --examples        display some examples of use and exit.
    
adql.py "select * from Filter"
   : run a query against default database, return results as CSV

adql.py -fvot "select * from Filter" 
   : run a query, return a votable
   
adql.py -i query.adql
   : load query from a file,
   
adql.py --format=plastic -i query.adql   
   : send results to a running plastic application (e.g. Topcat)

adql.py --list
   : list the names and identifiers of all queryable database services
   
adql.py --service=ivo://wfau.roe.ac.uk/twomass-dsa/wsa "select top 10 * from twomass_psc"
   : query against 2MASS

adql.py -myspace=/results/temp/adql1.vot -i query.adql
   : stage results at '/results/temp/adql1.vot' within the user's myspace

app.py

Execute remote applications, and return results to local disk or myspace.

Download app.py

  
Usage: app.py <application-id> [interface-name] <parameter options>

 Execute a remote application, and return results to local disk or myspace.
Use '--browse' or '--list' to select an application.  Re-run this script with
the selected application's ID  plus '--help'  to receive application-specific
help.

Options:
  -h, --help      show this help message and exit
  -b, --browse    browse all known remote applications in a GUI, and exit
  -l, --list      list all known remote applications, and exit
  -e, --examples  display some examples of use and exit.
    
  
examples:
app.py --list
        : list all known applications

app.py ivo://org.astrogrid/HDFImager --help
        : display help about the Merlin HDFImage application
        
app.py ivo://org.astrogrid/SExtractor  simple --help
        : display help on how to execute the 'simple' interface of SExtractor 

app.py ivo://wfau.roe.ac.uk/first-dsa/wsa/ceaApplication ConeSearch --help
        : display help for the 'ConeSearch' interface to 'First Survey Catalogue'

app.py ivo://wfau.roe.ac.uk/first-dsa/wsa/ceaApplication ConeSearch  \
    --format=HTML --ra=120.0 --dec=35.0 --radius=0.3
        : run a 'ConeSearch' on the First Survey Catalogue, return results as HTML

For example, the help produced for the 'MERLIN HDF Image' application is as follows: 

  
% ./app.py ivo://org.astrogrid/HDFImager --help
Usage: app.py ivo://org.astrogrid/HDFImager <parameter options>

Execute Cut out HDF(N) (GOODS) MERLIN+VLA radio images -- This tool extracts
cutouts of chosen size and resolution from the MERLIN+VLA 1.4 GHz Hubble Deep
Field (N) (GOODS) 8-arcmin field

Options:
  -h, --help            show this help message and exit
  --imagesize=real      Image Size: Image size (arcsec) in range 8 to 128
                        arcsec. (default: 12.0)
  --dec=DEC             Dec. in sexagesimal (colon-separated) or in decimal
                        degrees. Must be in format and range (+62:08:42.6 to
                        +62:17:13.3) or (+62.145167 to +62.287028) (J2000,
                        number of decimal places optional). If blank, Name
                        will be used. (default: +62.27472)
  --name=NAME           HDF name: HDF source name like J123613.97+620852.6
                        (decimal places optional) Only give either (RA and
                        Dec) or Name! (default: J123646.4+621629)
  --resolution=real     Resolution (arcsec), one of 0.2, 0.3, 0.4, 0.5 arcsec.
                        [0.2|0.3|0.4|0.5]  (default: 0.4)
  --ra=RA               RA in sexagesimal (colon-separated) or in decimal
                        degrees. Must be in format and range (12:36:12.97 to
                        12:37:24.95) or (189.054042 to 189.353958) (J2000,
                        number of decimal places optional). If blank, Name
                        will be used. (default: 189.19333)
  --hdfradioimages=VOTable
                        MERLIN+VLA HDF Images List: Name for VOTable which
                        will contain image URLs and metadata (output param -
                        only needed to write to myspace)
  -b, --browse          browse all known remote applications in a GUI, and
                        exit
  -l, --list            list all known remote applications, and exit
  -e, --examples        display some examples of use and exit.

plastic.py

Send a file or URL containing votable, fits, or spectrum data to a PLASTIC application (such as Topcat or Aladin)

Download plastic.py

Usage: plastic.py [options] <file | url>

Options:
  -h, --help      show this help message and exit
  -v, --vot       Treat as a votable (default)
  -s, --spec      Treat as a spectrum
  -f, --fits      Treat as a fits image
  -e, --examples  display some examples of use and exit
         
    
plastic.py mytable.vot
    : send the file 'mytable.vot' to any plastic table viewer
    
plastic.py -s downloads/spectra.fits
    : send the file 'downloads/spectra.fits' to any plastic specra viewers
    
plastic.py -i http://someServer/foo/images.fits
    : send this http url to any plastic image viewers

Registry

Utilities to query a VO Registry

search.py

Search the registry by simple query or ID, and display results in various ways. The query language accepted as the same as is used in VOExplorer smartlists - SRQL.

Download search.py

   
Usage: search.py [options] <srql> | <identifier>

Options:
  -h, --help            show this help message and exit
  -i, --id              treat arguments as a match against a full registry
                        identifier
  -q, --srql            treat arguments as SRQL (default)
  -f FORMAT, --format=FORMAT
                        format to return results as: [identifier | summary |
                        xml | browse | plastic] (default: summary)
  -e, --examples        display some examples of use and exit

    
search.py abell
    : display summary for resources matching 'abell'

search.py abell and noras
    : display summary for resources matching 'abell' and 'noras'

search.py --format==identifier waveband = radio and type = image
    : list identifiers of all image services providing radio images

search.py --format==plastic publisher = vizier and subject = agn
    : display resources with subject 'AGN' from Vizier in a PLASTIC viewer (e.g. VOExplorer)
    
search.py --format=browse ucd = redshift AND waveband = infrared
    : browse all IR Redshift resources
    
search.py --format=xml abell and not type = cone
    : display xml of resources that match 'abell' but are not cone services.

search.py -i "ivo://nasa.heasarc/skyview/first"
    : display summary of the resource 'ivo://nasa.heasarc/skyview/first'

search.py --format=xml -i "ivo://nasa.heasarc/skyview/first" 
    : display xml of the resource 'ivo://nasa.heasarc/skyview/first'

xquery.py

Search the registry using an XQuery.

Download xquery.py

  
Usage: xquery.py [options] <xquery> | <query-file>

Options:
  -h, --help       show this help message and exit
  -i, --inputfile  read query from a file (default)
  -q, --query      read query from commandline
  -e, --examples   display some examples of use and exit
       
    
  
xquery.py query.xq
    : run a query stored in file 'query.xq'

xquery.py -q "<size>{count(//vor:Resource)}</size>"
    :run a query provided on the commandline

Sample XQueries
<size>{count(//vor:Resource)}</size>
    : count the number of resources held in the registry
    
//vor:Resource[@xsi:type &= '*DataCollection']
    : list details of all DataCollection resources
    
<dl>
{
for $r in //vor:Resource[@xsi:type &= '*DataCollection']
order by $r/title
return <dt>{$r/title/text()}</dt><dd> : {$r/identifier/text()}</dd>
}
</dl>
    : produce a HTML description list of the titles and identifiers of
    : all registered DataCollections.

Myspace

Utilities to read and write files in Myspace

vols.py

List contents of myspace directories

Download vols.py

   
Usage: vols.py [options] [node-ivorn or path]

Options:
  -h, --help          show this help message and exit
  -l, --long          long format
  -1, --one-per-line  list one file per line
  -d, --directory     list directory instead of contents
  -F, --classify      append indicator of type to entries
  -Q, --quote         enclose filenames in quotes
  -e, --examples      display some examples of use and exit.
      
    
vols.py
        : list contents of user's home myspace directory
        
vols.py foo/bar
        : list contents of subdirectory 'foo/bar'
        
vols -l foo/bar
        : list long details of subdirectory 'foo/bar'
        
vols -F foo
        : list directory, indicating subdirectories

voget.py

Read contents of a myspace file

Download voget.py

   
Usage: voget.py [options] [node-ivorn or path]

Options:
  -h, --help            show this help message and exit
  -u, --url             display the download URL, instead of file contents
  -o FILE, --output=FILE
                        Save contents to file
  -e, --examples        display some examples of use and exit.
      
    
voget.py dsa/results.vot
        : display contents of results.vot
        
voget.py --url dsa/results.vot
        : display download url of results.vot

voget.py -o myresults.vot dsa/results.vot
        : download dsa/results.vot as ./myresults.vot

voput.py

Write contents of a myspace file

Download voput.py

     
Usage: voput.py [options] <local file> <myspace ivorn or path>

Options:
  -h, --help      show this help message and exit
  -e, --examples  display some examples of use and exit.
    
voput.py localdir/localfile.txt myspacedir/subdir/myspacefile.txt
        : copy localfile.txt from localdisk to myspace as myspacefile.txt
        : creating myspacedir and subdir if necessary

vomkdir.py

Make myspace directories

Download vomkdir.py

Usage: vomkdir.py [options] <myspace ivorn or path>

Options:
  -h, --help       show this help message and exit
  -d, --directory  allow removal of directories
  -e, --examples   display some examples of use and exit.
    
vomkdir.py dir/subdir/subsubdir
      : create subsubdir, and it's parent directories if required

vorm.py

Delete a myspace file or directory

Download vorm.py

  
Usage: vorm.py [options] <myspace ivorn or path>

Options:
  -h, --help       show this help message and exit
  -d, --directory  allow removal of directories
  -e, --examples   display some examples of use and exit.
    
vorm.py  dir/file.txt
        : delete file.txt from myspace.
vorm.py -d dir/subdir
        : delete the directory 'subdir' and all it's contents.