HEASARC Browse Batch Interface

Using the Batch Interface to the HEASARC Databases

The HEASARC Browse Batch Interface allows users to query the HEASARC database outside of a web browser. The Batch Interface can be used from within a script to query the HEASARC database and retrieve results. This document discusses how to use this interface.

The HEASARC Database Batch Interface

Topics:

Getting Started and Software Installation
Usage
Examples

The Browse Batch Interface allows you to query the HEASARC database as if it were local to the user's computer. Basically, you download a small Perl script which acts as a local client to query the HEASARC database. This client can be easily called from other programs or from within scripts in addition to being used from the command line.

Getting Started and Software Installation

In order to use the Batch Interface, you will need access to a computer with Perl (greater that 5.8.0) and either GNU wget or curl installed on it.

There are multiple versions of the Browse Batch Interface program, but the default (recommended) version will use curl if it is present (such as on macOS) and GNU wget (such as on Linux) otherwise. If you prefer to use GNU wget always or to use curl always, there are versions for that. In order to use the Browse Batch Interface program, you must have one of those tools installed on and it must be in your shell's command path. Many systems have either curl or wget pre-installed. If not, you can easily download a version and install it.

browse_extract.pl automatically detects if curl is present (in /usr/bin/) and uses that. Otherwise, it will use wget. Recommended for usage on macOS computers especially, but it will work on all types.
browse_extract_wget.pl will use only wget.
browse_extract_curl.pl will use only curl.

All versions were last updated on 2021-08-16.

Once you've downloaded one of these files, make sure they have executable permissions and place them in your executable path. These scripts assume your system has the Perl command installed in /usr/bin/. If Perl has been installed elsewhere on your machine, you should edit the first line of the script to change #!/usr/bin/perl to the correct location.

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

Usage

To use the Browse Batch Interface, type the browse_extract.pl (or browse_extract_curl.pl or browse_extract_wget.pl) command at the Unix shell prompt followed by some options. Many options are available, but you only need to specify the table to be searched and the astronomical position(s) of interest.

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]...

or

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 except VizieR table parameters.

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

Are there any public ROSAT observations of 3C273?

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

should print to standard output something 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

An example using an input and output file:

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

The results of that query can be edited (manually or by a simple script) to produce at file like:

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

plus 340 more lines.

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

It will take a while to process 350 positions...

A parameter query example:

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

A VizieR table example:
```
% browse_extract.pl table=I/284 position="0.0,0.0" coordinates=equatorial equinox=2000.0 radius=12.0 B1mag=\>19.9
```
Note that VizieR table parameters are case-sensitive. Check the VizieR table information pages for correct parameter spelling.

If you have questions concerning the installation or usage of these scripts please contact the Browse Help Desk.

HEASARC Acknowledgment

Browse is provided by the Astrophysics Science Division 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