Browse Browse Help Help Latest Version New/Updated Tables

Using the Batch Interface to the HEASARC Databases

The HEASARC Database Batch Interface

Topics:

• Getting Started and Software Installation
• Usage
• Examples

Getting Started and Software Installation

There are two versions of the batch program. The older version requires two scripts to be downloaded from the HEASARC anonymous FTP server:

1. browse_extract.pl updated November 16, 2006
2. webquery.pl (Perl 5.x and higher) OR webquery.pl (Perl 4.x)

The newer version of the batch script was created in response to reports of problems running the webquery scripts from behind firewalls and proxies. This version uses wget instead of webquery to do the data download. Only one script is needed for this version however it is necessary to have wget installed. Many systems have wget pre-installed and you can easily download a version from the web if not. After making sure wget is accessible on your system just substitute browse_extract_wget.pl for browse_extract.pl. The command syntax is the same.

1. browse_extract_wget.pl updated August 1, 2008

Note: These scripts are in the public domain. Please feel free to copy and modify them to use however you wish. However, we can only support the versions of the scripts that we have made available.

Usage

The syntax of the command is:

browse_extract.pl table=table name

optional arguments:
[position=name_or_position]
[coordinates=csys]
[equinox=year]
[radius=arcmin]
[fields=STANDARD/ALL/list]
[name_resolver=NED/SIMBAD]
[infile=input_list]
[outfile=output_file]
[format=batch|FITS|VOTable|Excel|HTML]
[sortvar=column_name]
[param=name,value /or/ name=value]...

browse_extract.pl table=xxx
to just get a list of available tables. Only VizieR tables directly linked within the HEASARC will be noted, but any VizieR table can be queried using browse_extract.

All arguments are case insensitive.

Explanation of command line arguments:

table

This is the abbreviated or short table name as used in the HEASARC, e.g., ABELL, XTEOBS, ROSPUBLIC. This is given as the short name in the Browse Web interfaces.

position

is either the name of an object a set of coordinates around which the search is to take place. If a name is given it will be resolved using the service given in the name_resolver keyword or SIMBAD by default. The syntax for coordinates is that supported in the Browse Web services. If the coordinates string contains embedded spaces, then this argument should be enclosed in quotes. Multiple positions may be separated by semicolons but these will then be processed together giving a combined count for all specified targes.

The Position argument can be specified as "none" or "null" if the user does not wish to specify and positions.

coordinates

This argument should be either "Equatorial" or "Galactic". The default is Equatorial. It is used to determine the input coordinates if used and the display coordinate system for the primary coordinates in the table.

equinox

is the equinox year for input and output coordinates. It defaults to 2000 (and is ignored for Galactic coordinates).

radius

Radius gives the radius in arcminutes out to which the search is to take place. This defaults to 60.

Note that this is different from the interactive Browse system where the default differs from table to table.

fields

This argument indicates which parameters are to be retrieved from the table. The default, "Standard", indicates that only a limited set of parameters will be retrieved. "All" will retrieve all parameters from the table. A list of specific fields separated by commas may also be specified.

name_resolver

may be used to select the system used to convert names into coordinates. The currently supported services are NED and SIMBAD. The default is SIMBAD.

infile

specifies a file containing objects to be searched. Each line in the file will be used as the Position. If no Infile or Position argument is give then the positions will be read from the standard input.

outfile

specifies a file to contain the table of returned results. If not specified the results will be printed on standard output

format

specifies the desired output format. When anything other than the batch format is requested, all positions will be searched at once. In batch queries each line of the input is specified as a distinct query. Current valid formats include:
Batch - The default format.
HTML - The Text Table format in the Web version of Browse
FITS - A FITS ASCII table (The results are in the first extension).
EXCEL - An Excel compatible output format.
VOTable - The Virtual Observatory Table format.
Text - The Pure Text format in the Web version of Browse

sortvar

may be used to specify the field on which the results will be sorted. This variable need not be displayed.

param

param=name,value argument is used to do parameter searches. The syntax of the value parameter is the same as used in the Browse Web interface, e.g., 3000, >5000, 4..10, 3C*273 are possible values which search for data with a value equal to 3000, greater than 5000, between 4 and 10 or matching the strings '3C273', '3CXXXXX273', etc., respectively. If the name of the parameter does not conflict with one of the other arguments to browse_extract, then the simpler syntax
name=value
may be used.

In some environments characters in the value may need to be escaped, e.g., exposure='>2000' or exposure=\>2000

Users may specify the target positions using the position argument, using a predefined file specified with infile, or from the standard input. In the latter two cases each line until an EOF will be used as a position.

Examples

% browse_extract.pl table=rospublic position=3c273 name_resolver=ned

should print to standard output a table like the following:

seq_id     |instrument|exposure|ra(2000)  |dec(2000)  |name              |public_date(ISO)|
RP600242   |PSPC      |    3078|12 27 43.2|+01 36 00.0|GIOVANELLI-HAYNES |      1994-03-22|
RP600242A01|PSPC      |   24830|12 27 43.2|+01 36 00.0|GIOVANELLI-HAYNES |      1994-03-22|
RH120001   |HRI       |       0|12 29 04.8|+02 03 00.0|XRT/HRI NORTH DUMM|      1995-08-01|
WP141509N00|PSPC      |    3332|12 29 04.8|+02 03 00.0|3C273             |      1994-09-28|
RP120000N00|PSPC      |     916|12 29 04.8|+02 03 00.0|XRT/PSPC NORTH DUM|      1995-01-31|
WF700191   |PSPC      |    3291|12 29 04.8|+02 03 00.0|3C273             |      1996-02-07|
WP700191   |PSPC      |    6243|12 29 04.8|+02 03 00.0|3C273             |      1996-02-07|
RP141520N00|PSPC      |     485|12 29 04.8|+02 03 00.0|3C273             |      1995-09-27|
WH700234   |HRI       |   17174|12 29 07.2|+02 03 00.0|3C 273            |      1993-07-20|
...
Search of table ROSPUBLIC around '3c273' with a radius 60' returns 25 rows

I might first do a query of all WGACAT sources within 80' of the galactic center using:

% browse_extract.pl table=wgacat radius=80 coordinates=galactic position='0.,0.' outfile=wgacat_gc.list

359.386118, 1.149945
359.510470, 1.223261
359.274779, 0.933392
359.279818, 0.934399
359.383583, 0.977861
359.389096, 0.979161
359.392070, 0.972419
359.292038, 0.907242
359.389873, 0.967603
359.390891, 0.967811
359.393223, 0.969269
...

If this result is stored as wgacat_galcen.dat, we can find nearby HST Guide Star Catalog positions with:

browse_extract.pl table=gsc coordinates=galactic infile=wgacat_galcen.dat outfile=wgacat_galcen_guidestars.dat

% browse_extract.pl table=rassfsc hardness_ratio_1-hardness_ratio_2='>1' position=null

HEASARC Acknowledgment

Browse is provided by the Laboratory for High Energy Astrophysics at NASA/Goddard Space Flight Center. If using this service made a significant contribution to a research project, please make the following acknowledgment in any resulting publication:

"This research has made use of data obtained through the High Energy Astrophysics Science Archive Research Center Online Service, provided by the NASA/Goddard Space Flight Center."

Please send a preprint or reprint of the paper to:

	The HEASARC
	Code 660.2
	NASA/Goddard Space Flight Center
	Greenbelt, Maryland, 20771, USA