The HEASARC Database System

Utility Applications

HDBfilter

The HDBfilter application provides capabilities to process the HDBmc client application's SQL query results. It can reformat the results into either a name=value pair or a compressed table format, convert Right Ascension and Declination values to degrees, convert Class value to ASCII representation, precess equatorial coordinates, and perform a cone search. It verifies 10 optional and 1 required command line arguments: layout (optional), equinox year (optional), Right Ascension name (optional), Declination name (optional), Class name (optional), Right Ascension mode (optional), Declination mode (optional), Class mode (optional), source and destination equinox years for precession (optional) , Right Ascension, Declination, and radius for cone search (optional), and input file specification; sequentially reads the contents of the input file; calls the load_table function to load the information into a dynamically allocated table array (for table layout); calls the ra_str2deg, ra_deg2hms, dec_str2deg, and dec_deg2dms AUTIL functions to perform necessary format conversions of Right Ascension and Declination values; calls the slaPreces SLA routine for coordinate precession; calls the slaDsep SLA routine to determine the distance between two points on a sphere (for cone search); calls the print_buffer routine to write the results to standard output; and frees the dynamically allocated table array via a call to the free_table routine (for table layout). For various string manipulations, the partok, strcnvprnt, and strtrm UTIL routines are used. The table format is compressed, to prevent the display of needlessly wide columns. The column width is set to that of the longest value present.

graphical depiction of the relationship of HDBfilter to all
subroutines

Command arguments:

        HDBfilter [-layout=pair|table] [-raname=name|ra] [-decname=name|dec]
                    [-ra=hms|deg] [-dec=dms|deg] [-precess=from_year,to_year]
                    [-cone=ra,dec,radius] file

Options:

-layout=pair|table
Converts the data to either name=value pair (pair) or table (table) format. Default is table.
-equinox=eq
Appends the specificed equinox year to ra and dec parameter headers.
-raname=name|ra
Specifies the right ascension parameter name. Default is ra.
-decname=name|dec
Specifies the declination parameter name. Default is dec.
-classname=name|class
Specifies the class parameter name. Default is class.
-ra=hms|deg
Converts right ascension data to either hh mm ss (hms) or degrees (deg) format. Default is degrees.
-dec=dms|deg
Converts declination data to either dd mm ss (dms) or degrees (deg) format. Default is degrees.
-class=ascii|integer
Converts class to either integer or ASCII. Default is integer.
-precess=from_year,to_year
Performs coordinate precession of right ascension and declination data.
-cone=ra,dec,radius Filters data based on cone search. Values for ra and dec are in degrees and radius in arc minutes.

Either a filename or a minus sign (-) can be specified for the file argument (useful for pipe). In either case, the contents of the data must be in SQL table format.

Examples:

HDBfilter layout=pair -ra=hms -dec=dms -precess=1950,2000 test.table

HDBmc "sql=select * from heasarc_ascapublic where name like 'ABELL%' | HDBfilter -

The following example executes HDBmc client to query the heasarc_ariel5 table and pipes the output of the query to the HDBfilter application with all options specified:

% HDBmc "sql=select name,ra,dec,class from heasarc_ariel5" | HDBfilter -layout=table -equinox=2000 -raname=ra -decname=dec -classname=class -ra=hms -dec=dms -class=ascii -precess=1950,2000 -cone=0,0,60 -

+-------+----------+-----------+------------+
|name   |ra(2000)  |dec(2000)  |class       |
+-------+----------+-----------+------------+
|TRA X-1|00 02 33.7|+00 16 42.2|UNIDENTIFIED|#90
|SRC_158|00 02 33.7|+00 16 42.2|UNIDENTIFIED|#138
+-------+----------+-----------+------------+
(2 rows)

HDBrect

The HDBrect application calculates the minimum and maximum values of Right Ascension and Declination values for a rectangle that encloses a sphere. It verifies 1 optional and 4 required command line arguments: mode (optional), equinox year, longitude of center, latitude of center, and radius; calls the slaGaleq SLA routine to convert the input coordinates from galactic to equatorial or the slaEcleq SLA routine to convert the input coordinates from ecliptic to equatorial, depending on the optional mode argument; calls the slaPreces SLA routine to perform precession of coordinates; calls the sphrect AUTIL routine to calculate the rectangle; and prints the results in degrees to standard output.

graphical depiction of the relationship of
HDBrect to all subroutines

Command arguments:

HDBrect [-mode=galactic|ecliptic|equatorial] e l b r

Option

-mode=galactic|ecliptic|equatorial
Performs either galactic to equatorial (galactic) or ecliptic to equatorial (ecliptic) conversion. The default is equatorial.

Arguments:

  • e Equinox year of coordinates.
  • l Longitude of center in degrees.
  • b Latitude of center in degrees.
  • r Radius in arc minutes.

Example:

HDBrect -mode=galactic 1950 18.94 -73.70 60

HDBprec

The HDBprec application performs precession of equatorial coordinates. It verifies 4 command line arguments: source equinox year, destination equinox year, Right Ascension, and Declination; calls the slaPreces SLA routine to precess the coordinates; and writes the results in degrees to standard output. The verification of Right Ascension and Declination values are via calls to the ra_str2deg and dec_str2deg AUTIL functions, respectively.

graphical depiction of the relationship of
HDBprec to all subroutines

Command arguments:

HDBprec eq0 eq1 ra dec

Arguments:

  • eq0 Equinox year of coordinates (from).
  • eq1 Equinox year of coordinates (to).
  • ra Right Ascension in degrees.
  • dec Declination in degrees.

Example:

HDBprec 1950 2000 18.94 -73.70


Documentation prepared by the HEASARC Database Group
HEASARC Home | Observatories | Archive | Calibration | Software | Tools | Students/Teachers/Public

Last modified: Thursday, 17-Jun-2004 22:53:07 EDT

The Astrophysics Science Division (ASD) at NASA's Goddard Space Flight Center (GSFC) seeks a creative, innovative individual with strong teamwork and leadership skills to serve as Director of the High Energy Astrophysics Science Archive Research Center (HEASARC). This will be a permanent civil servant position. + Learn more.