Chandra X-Ray Observatory
	(CXC)
Skip to the navigation links
Last modified: September 2014

URL: http://cxc.harvard.edu/ciao/ahelp/obsid_search_csc.html
AHELP for CIAO 4.9

obsid_search_csc

Context: tools

Synopsis

Search the Chandra Source Catalog by OBS_ID

Syntax

obsid_search_csc  obsid outfile [columns] [download] [root] [bands]
[filetype] [catalog] [verbose] [clobber]

Description

'obsid_search_csc' uses the command line interface to the Chandra Source Catalog (CSC) to retrieve source properties and associated data products by Observation ID (obsid).

Users enter one or more OBS_ID values and the tool will query the CSC. The source properties results are written, one line per source, to a tab-separated-value (TSV) format output file, and when verbose is one or higher a subset of the data for each source is printed to the screen. The output file will contain a default set of catalog columns unless this is overridden with the 'columns' parameter. The data products associated with the sources may also be retrieved including the event files, response files (ARF, RMF, PSF, exposure map), and related histograms (spectra, lightcurves, images).

More complex queries including doing cross matches must be done using the CSCView application. Users whose research makes use of the Chandra Source Catalog should cite: Evans et al 2010, ApJS 189, 37.

Example 1

unix% obsid_search_csc obsid=635 outfile=635.tsv download=none mode=h

Search for all sources that were detected in OBS_ID 635.

obsid_search_csc
           obsid = 635
         outfile = 635.tsv
         columns = INDEF
        download = none
            root = ./
           bands = broad,wide
       filetypes = regevt,pha,arf,rmf,lc,psf,regexp
         catalog = csc1
         verbose = 1
         clobber = no
            mode = h


94 rows returned by query
94 Different Master Source(s).
1 Different Observation(s).

name                    ra              dec             obsid
CXO J162602.2-242348    246.50924       -24.39670         635
CXO J162603.1-242336    246.51290       -24.39352         635
CXO J162604.3-242252    246.51817       -24.38122         635
CXO J162605.8-242756    246.52432       -24.46570         635
...

Returns a TSV format file with source list. The default set of columns returned are not printed to the screen but are saved in the TSV file.

% dmlist "635.tsv[opt kernel=text/tsv]" cols
 
--------------------------------------------------------------------------------
Columns for Table Block 635.tsv
--------------------------------------------------------------------------------
 
ColNo  Name                 Unit        Type             Range
   1   name                              String[20]                          Source name in the format 'CXO Jhhmmss.s +/- ddmmss'
   2   ra                   deg          Real4          -Inf:+Inf            Source position, ICRS right ascension
   3   dec                  deg          Real4          -Inf:+Inf            Source position, ICRS declination
   4   err_ellipse_r0       arcsec       Real4          -Inf:+Inf            Major radius of the 95% confidence level error ellipse
   5   conf_flag                         String[5]                           Source regions overlap (source is confused)
   6   sat_src_flag                      String[5]                           Source is saturated in all observations; source properties are unreliable
   7   significance                      Real4          -Inf:+Inf            Highest source flux significance across all observations
...

Example 2

unix% obsid_search_csc 635,637 outfile=none download=ask filetype=evt
columns=o.cnts_aper_b

Search for two observations obsid=635 and 637. We have asked that the full field evt file be return but will be prompted (download=ask). Additionally we require the broad-band source counts for each observation.

obsid_search_csc
           obsid = 635,637
         outfile = none
         columns = o.cnts_aper_b
        download = ask
            root = ./
           bands = broad,wide
       filetypes = evt
         catalog = csc1
         verbose = 1
         clobber = no
            mode = ql


175 rows returned by query
152 Different Master Source(s).
2 Different Observation(s).

name                    ra              dec             obsid   cnts_aper_b
CXO J162538.1-242235    246.40889       -24.37654         637          3569
CXO J162541.3-242138    246.42232       -24.35970         637           265
CXO J162552.5-241710    246.46882       -24.28632         637           149
...
CXO J162752.0-244049    246.96687       -24.68049         635          3849
CXO J162754.5-243717    246.97730       -24.62162         635            97
CXO J162755.2-242839    246.98017       -24.47765         635            91

If you use this data, please cite Evans et al 2010, ApJS 189, 37

Download data for CXO J162538.1-242235 in 00637_001 [y,n,a,q]: y
Retrieving files for obsid_obi 00637_001
Retrieved file .//637/acisf00637_001N002_evt3.fits
Download data for CXO J162541.3-242138 in 00637_001 [y,n,a,q]: a
...

When prompted for downloads: 'y' will retrieve the file and continue onto the next. 'n' will skip the current file and continue. 'a' will retrieve the remaining files with further prompting, and 'q' will skip the current file and will not retrieve nor prompt for any remaining files.

Example 3

unix% obsid_search_csc @bootes.lis

The list of observations can also be supplied using standard CIAO stacks.

Parameters

name type def min max reqd stacks
obsid string       yes yes
outfile file       yes  
columns string INDEF     no yes
download string none        
root file          
bands string broad,wide        
filetype string regevt,pha,arf,rmf,lc,psf,regexp        
catalog string csc1        
verbose integer 1 0 5    
clobber boolean no        

Detailed Parameter Descriptions

Parameter=obsid (string required stacks=yes)

Observation Identification

The OBS_ID number. Multiple obsid's may be input via a comma separated list or any other stack.

Parameter=outfile (file required)

Name of output table.

The output file name. If left blank or set to "none", the the table of source properties is not saved.

The output is the same Tab Separated Value (tsv) format as returned by CSCView. To use the file with DM tools users must explicitly specify the kernel:

unix% dmlist "mysrc.tsv[opt kernel=text/tsv]" cols
--------------------------------------------------------------------------------
Columns for Table Block mysrc.tsv
--------------------------------------------------------------------------------
 
ColNo  Name                 Unit        Type             Range
   1   name                              String[20]                          Source name in the format 'CXO Jhhmmss.s +/- ddmmss'
   2   ra                                String[12]                          Source position, ICRS right ascension
   3   dec                               String[11]                          Source position, ICRS declination
   4   err_ellipse_r0       arcsec       Real4          -Inf:+Inf            Major radius of the 95% confidence level error ellipse
   5   conf_flag                         String[5]                           Source regions overlap (source is confused)
   6   sat_src_flag                      String[5]                           Source is saturated; source properties are unreliable
   7   significance                      Real4          -Inf:+Inf            Highest source flux significance across all observations
   8   flux_aper_b          erg/s/cm^2   Real4          -Inf:+Inf            Aperture-corrected net energy flux inferred from the source region aper
   ...
   

Parameter=columns (string not required default=INDEF stacks=yes)

The list of catalog columns to return.

The list of catalog columns to return. The default (INDEF) returns the list of columns returned by the combination of CSCView Master Summary and Obsid Summary defaults.

Several columns will be added to the query if they are not explicitly provided. These inlcude: m.name, m.ra, m.dec, o.instrument, o.obsid, o.obi, o.region_id, and a.match_type.

The prefix "m." or "o." should be used to specify the if the property is a Master Source property (ie a value derived from all individual observations) or an Obi Source property (computed from a single observation). The list of columns can also be input via a stack, eg columns=@my_favorite_cols.lis

The following special values may be used to return the standard set of columns defined by CSCView:

  • "MSBS" , the set of Master Source Basic Summary columns
  • "MSS", the set of Master Source Summary columns
  • "MSP", the set of Master Source Photometry columns
  • "MSV", the set of Master Source Variability columns
  • "SOS", the set of Source Observation Summary columns
  • "SOP", the set of Source Observation Photometry columns
  • "SOV", the set of Source Observation Variability columns

The values are case-sensitive, and can be used with other values such as

unix% search_csc ... columns="SOS,a.match_type,o.livetime" ...

Parameter=download (string default=none)

Retrieve the associated data products?

Determine if data products should be retrieved. The valid options are

  • "none" : no datasets are retrieved
  • "ask" : ask for each master source if products should be retrieved.
  • "all" : all products will be retrieved without asking

When asked, users have 4 choices

  • y : yes to the current source
  • n : no to the current source
  • a : yes to the current source and all remaining sources
  • q : no to the current source and all remaining sources

Parameter=root (file default=)

Output root directory for data products.

Parameter=bands (string default=broad,wide)

A comma separated list of energy bands

Various data products are stored in different energy bands.

  • broad - ACIS 0.5 - 7.0 keV
  • soft - ACIS 0.5 - 1.2 keV
  • medium - ACIS 1.2 - 2.0 keV
  • hard - ACIS 2.0 - 7.0
  • ultrasoft - ACIS 0.2 - 0.5
  • wide - HRC

This parameter is the list of energy bands for those products.

If bands is blank, all bands are retrieved.

Parameter=filetype (string default=regevt,pha,arf,rmf,lc,psf,regexp)

Comma separated list of file types to retrieve.

List of files to retrieve. The following list gives the valid options.

  • evt - Level 3 event file for entire observation
  • exp - Full field exposure map (per energy band)
  • ahst - Aspect histogram file
  • bpix - Level 3 badpixel file
  • fov - Level 3 field of view file
  • bkgimg - Background image (per energy band)
  • sens - Sensitivity map (per energy band)
  • img - Exposure corrected, background subtracted full field image (per energy band)
  • reg - Source region defintion
  • arf - Auxillary Response File for spectral fitting
  • rmf - Response Matrix File for spectral fitting
  • pha - Spectrum
  • regevt - Event file for just area around current source
  • regexp - Region exposure map (per energy band)
  • regimg - Exposure corrected image of source (per energy band)
  • psf - Point Spread Function (per energy band)
  • lc - Light curve (per energy band)

It is possible that the same file may be queued for retrieve more than once. The script will recognize this and will instead make a copy of the file instead of re-retrieving it from the archive.

The script will check if the file it is about to retrieve already exists. If so it will skip the and inform the user.

Files are place in subdirectories of the current directory. They are organized by OBS_ID, source name "CXOJ...", and then by region id. This heiarchry ensures that the large per-obi files are only retrieved/stored once per master source.

If filetype is left blank, all avialble file types are retrieved.

Parameter=catalog (string default=csc1)

Fixed at 'csc1'. Added for future expansion.

Parameter=verbose (integer default=1 min=0 max=5)

Tool chatter level.

Parameter=clobber (boolean default=no)

Remove outfile if it already exists?

This only applies to outfile. Products are never overwritten.

Changes in the scripts 4.6.6 (September 2014) release

Corrects the "MSBS" (master source basic summary) macro.

Provide more information when CSC servers are down and the catalog is not available.

Bugs

Release 2 of Chandra Source Catalog not supported

This script does not support the current release 2 version of the Chandra Source Catalog.

See Also

contrib
cda_data, cda_search
tools
download_chandra_obsid, download_obsid_caldb, find_chandra_obsid, list_datasetid, search_csc, splitobs

Last modified: September 2014
Smithsonian Institute Smithsonian Institute

The Chandra X-Ray Center (CXC) is operated for NASA by the Smithsonian Astrophysical Observatory. 60 Garden Street, Cambridge, MA 02138 USA.   Email:   cxchelp@head.cfa.harvard.edu Smithsonian Institution, Copyright © 1998-2017. All rights reserved.