idlastro / Web Socket Procedures: QUERY_IRSA_CAT

[Source code]

NAME
QUERY_IRSA_CAT
PURPOSE
Query a catalog in the NASA/IPAC Infrared Science Archive (IRSA)
by position or resolvable target name.
EXPLANATION
Uses the IDLnetURL object to do a spatial cone search of a
catalog in the IRSA (https://irsa.ipac.caltech.edu/) database.  
Returns the table data in an array of structures.  Allows an 
additional structure with table column information (required 
to write the table later), and also a string array of headers.  If 
outfile is set, it saves the table as an IPAC table file.  This 
can be slow for large query results, so write only if needed.    
CALLING SEQUENCE
info = query_irsa_cat(targetname_or_coords, [catalog=catalog,
radius=radius, radunits=radunits, outfile=outfile,
change_null=change_null, table_col_info=table_col_info, 
table_hdr=table_hdr, /DEBUG])
REQUIRED INPUT
TARGETNAME_OR_COORDS - Either a string giving a resolvable target
       name (with J2000 coordinates determined by NED or SIMBAD), or a 
       2-element numeric vector giving the J2000 right ascension 
       and declination, both in degrees.
OPTIONAL INPUT
CATALOG - string giving the identifier of the IRSA catalog to be
       searched.  The complete list of catalogs and identifier
       strings is available in XML format at:
         https://irsa.ipac.caltech.edu/cgi-bin/Gator/nph-scan?mode=xml
       or as an IPAC Table (ascii) at:
         https://irsa.ipac.caltech.edu/cgi-bin/Gator/nph-scan?mode=ascii
       The identifier string is under "catname".
       If this keyword is omitted, the program will query the 2MASS Point
       Source Catalog ('fp_psc').
       Examples of current IRSA catalogs include:  
          'wise_allwise_p3as_psd' - AllWISE Source Catalog
          'fp_psc' - 2MASS Point Source Catalog
          'iraspsc' - IRAS Point Source Catalog v2.1 (PSC)
          'irasfsc' - IRAS Faint Source Catalog v2.0
          'cosmos_ib_phot' - COSMOS Intermediate and Broad Band Photometry Catalog 2008
RADIUS - scalar input of the radius of the search with default of
       60 (arcsec). IRSA catalogs have maximum allowable search 
       radii.  These are listed on the corresponding web
       interface page for the catalog search, or in the
       nph-scan return table under "coneradius".
RADUNITS - string giving the units of the radius (default is 'arcsec').
OUTFILE - if present, the query result is written to this filename.
CHANGE_NULL - a numeric value (input as integer) to put in the
       structure if the table uses a string for null
       integer values (default is -9999).
TABLE_COL_INFO - An IDL structure with table column headers.
       (required if table is written with write_ipac_table).
TABLE_HDR - An string array with header comments and keywords.
DEBUG - /DEBUG provides some additional output.
OUTPUT
info - An IDL structure with the query result rows.  The structure
       tags are the catalog column names, modified as needed for IDL.
       If the query fails or is invalid, the return value is -1.  
EXAMPLES
(1) Plot a histogram of the J magnitudes of all 2MASS
    point sources within 10 arcminutes of the center of the
    globular cluster M13.  Save the IPAC table. 
  IDL> info = query_irsa_cat('m13',radius=10,radunits='arcmin',outfile='save.tbl')
  IDL> help,/struct,info
  IDL> plothist,info.j_m,xran=[10,20]
(2) Find the position of the faintest IRAS 60 micron
    source within 1 degree of central position of the
    COSMOS survey (10h00m28.6s +02d12m21.0s in J2000)
  IDL> info = query_irsa_cat([150.11917,2.205833], catalog='irasfsc', radius=1, radunits='deg')
  IDL> help,/struct,info
  IDL> idx = where(info.fnu_60 eq min(info.fnu_60))
  IDL> print, (info.ra)[idx], (info.dec)[idx]
PROCEDURES USED
READ_IPAC_VAR  comes with query_irsa_cat.pro
VALID_NUM  from IDLastro
NOTES
The program writes an output IPAC table file only if the
OUTFILE keyword is set.
MODIFICATION HISTORY
Adapted from queryvizier.pro - H. Teplitz, IPAC  September 2010
Removed requirement of writing/reading IPAC table file -
  T. Brooke, IPAC May 2011
Longer timeout for webget, added change_null - TYB June 2013
Added status message - TYB Jan 2016
Replace webget with IDLnetURL and redo structues - TYB Aug 2017