Search https://cxc.harvard.edu/ciao/
Contact the CXC HelpDesk
Last modified: December 2022

URL: https://cxc.cfa.harvard.edu/ciao/ahelp/search_csc.html
/ ciao4.15 / ahelp / search_csc.html
Jump to: Description · Examples · Parameters · Changes in the scripts 4.14.3 (September 2022) release · Changes in the script 4.11.5 (October 2019) release · Changes in the scripts 4.11.2 (April 2019) release · Changes in the scripts 4.6.6 (September 2014) release · Bugs · See Also

AHELP for CIAO 4.15

search_csc

Context: Tools::Download

Synopsis

Perform a position search on the Chandra Source Catalog

Syntax

search_csc  pos radius outfile [radunit] [columns] [sensitivity]
[download] [root] [bands] [filetype] [catalog] [verbose] [clobber]

Description

'search_csc' uses the command line interface to the Chandra Source Catalog (CSC) to retrieve source properties and associated data products for a single position and radius.

Users may enter either a comma-separated RA, Dec position or an object name, along with a search radius. 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.

Examples

Example 1

unix% search_csc pos="83.831577 ,-5.3993566" radius="0.02"
outfile="orion_src.tsv" root=. download=all catalog=csc1

Perform at 0.02 arcmin radius search around the position RA=83.831577 , Dec=-5.3993566. A tab-separated table with various properties are output to the ASCII file "orion_src.tsv". Since download=all, then all the requested data products will be retrieved without prompting. The above command will generate the following screen output 

search_csc
             pos = 83.831577 ,-5.3993566
          radius = 0.02
         outfile = orion_src.tsv
         radunit = arcmin
         columns = INDEF
     sensitivity = no
        download = all
            root = .
           bands = broad,wide
       filetypes = regevt,pha,arf,rmf,lc,psf,regexp
         catalog = csc1
         verbose = 1
         clobber = no
            mode = ql


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

name                    ra              dec             sepn    obsid
CXO J053519.6-052357     83.83170        -5.39921       0.012'   3744
CXO J053519.6-052357     83.83170        -5.39921       0.012'     26
CXO J053519.6-052357     83.83170        -5.39921       0.012'   1522
CXO J053519.6-052357     83.83170        -5.39921       0.012'   4395
CXO J053519.6-052357     83.83170        -5.39921       0.012'   4396
CXO J053519.6-052357     83.83170        -5.39921       0.012'   3498
CXO J053519.6-052357     83.83170        -5.39921       0.012'   4373
CXO J053519.6-052357     83.83170        -5.39921       0.012'   4374

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

Retrieving files for obsid_obi 03744_000
Retrieved file ./CXOJ053519.6-052357/03744_000/r0252/acisf03744_000N001_r0252_pha3.fits
Retrieved file ./CXOJ053519.6-052357/03744_000/r0252/acisf03744_000N001_r0252b_psf3.fits
Retrieved file ./CXOJ053519.6-052357/03744_000/r0252/acisf03744_000N001_r0252_regevt3.fits
Retrieved file ./CXOJ053519.6-052357/03744_000/r0252/acisf03744_000N001_r0252_rmf3.fits
Retrieved file ./CXOJ053519.6-052357/03744_000/r0252/acisf03744_000N001_r0252b_regexp3.fits
Retrieved file ./CXOJ053519.6-052357/03744_000/r0252/acisf03744_000N001_r0252_arf3.fits
Retrieved file ./CXOJ053519.6-052357/03744_000/r0252/acisf03744_000N001_r0252b_lc3.fits
Retrieving files for obsid_obi 00026_000
pha is not available for HRC observation 00026_000
Retrieved file ./CXOJ053519.6-052357/00026_000/r0072/hrcf00026_000N001_r0072w_psf3.fits
Retrieved file ./CXOJ053519.6-052357/00026_000/r0072/hrcf00026_000N001_r0072_regevt3.fits
rmf is not available for HRC observation 00026_000
Retrieved file ./CXOJ053519.6-052357/00026_000/r0072/hrcf00026_000N001_r0072w_regexp3.fits
...

Example 2

unix% search_csc pos="16:26:24.162, -24:24:49.41" radius=0.6
outfile=rho_oph.tsv filetypes=evt,fov,pha,arf,rmf,reg verbose=2 mode=h
download=all root=/arc catalog=csc1

Perform a 0.6' cone search around the given position. Return a different subset of the products. 

             pos = 16:26:24.162, -24:24:49.41
          radius = 0.6
         outfile = rho_oph.tsv
         radunit = arcmin
         columns = INDEF
     sensitivity = no
        download = all
            root = ./arc
           bands = broad,wide
       filetypes = evt,fov,pha,arf,rmf,reg
         catalog = csc1
         verbose = 2
         clobber = no
            mode = h


11 rows returned by query
3 Different Master Source(s).
5 Different Observation(s).

name                    ra              dec             sepn    obsid
CXO J162623.5-242439    246.59829       -24.41099       0.21'     635
CXO J162623.5-242439    246.59829       -24.41099       0.21'     618
CXO J162623.5-242439    246.59829       -24.41099       0.21'     637
CXO J162624.0-242448    246.60020       -24.41339       0.033'    617
CXO J162624.0-242448    246.60020       -24.41339       0.033'    619
CXO J162624.0-242448    246.60020       -24.41339       0.033'    635
CXO J162624.0-242448    246.60020       -24.41339       0.033'    618
CXO J162624.0-242448    246.60020       -24.41339       0.033'    637
CXO J162625.3-242444    246.60540       -24.41247       0.27'     635
CXO J162625.3-242444    246.60540       -24.41247       0.27'     618
CXO J162625.3-242444    246.60540       -24.41247       0.27'     637

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

Retrieving files for obsid_obi 00635_000
...
Retrieved file ./arc/CXOJ162623.5-242439/00635_000/r0099/acisf00635_000N001_r0099_arf3.fits
Retrieving files for obsid_obi 00618_000
Found multiple files for ('fov', '  618', '  0', '', '', 'ACIS')

Retrieved file ./arc/CXOJ162623.5-242439/00618_000/acisf00618_000N002_fov3.fits
...

This search returns 3 sources that has data in 5 observations. The same observation level products (eg event file) are queued multiple times for retrival but copies are made instead. The multiple files information is only printed with verbose=2 and higher.

Example 3

unix% search_csc "M81" radius=1 clob+ out="m81.tsv" download=none
verb=2 mode=h columns="o.cnts_aper_b" catalog=csc1

Use the name resolver to search for sources with 1arcmin of M81. 

search_csc
             pos = M81
          radius = 1
         outfile = m81.tsv
         radunit = arcmin
         columns = o.cnts_aper_b
     sensitivity = no
        download = none
            root = ./
           bands = broad,wide
       filetypes = regevt,pha,arf,rmf,lc,psf,regexp
         catalog = csc1
         verbose = 2
         clobber = yes
            mode = h

Resolved M81 to ra=148.88822 dec=69.06529
Required column a.match_type was added to columns
Required column o.region_id was added to columns
Required column o.obi was added to columns
Required column o.obsid was added to columns
Required column o.instrument was added to columns
Required column m.dec was added to columns
Required column m.ra was added to columns
Required column m.name was added to columns

299 rows returned by query
35 Different Master Source(s).
22 Different Observation(s).

name                    ra              dec             sepn    obsid   cnts_aper_b
CXO J095526.2+690437    148.85954        69.07696       0.93'     735            67
CXO J095527.0+690415    148.86260        69.07089       0.64'     735            77
CXO J095527.8+690400    148.86583        69.06683       0.49'    5948            19
CXO J095527.8+690400    148.86583        69.06683       0.49'    5935            20
CXO J095527.8+690400    148.86583        69.06683       0.49'    5936            17
CXO J095527.8+690400    148.86583        69.06683       0.49'    5937            13
CXO J095527.8+690400    148.86583        69.06683       0.49'    5938            22
CXO J095527.8+690400    148.86583        69.06683       0.49'    5939            15
...
CXO J095532.0+690354    148.88363        69.06512       0.099'   5937            48
CXO J095532.0+690354    148.88363        69.06512       0.099'   2706           NaN
CXO J095532.0+690354    148.88363        69.06512       0.099'   9540         27916
...

The requested column 'o.cnts_aper_b' (the broad band, 0.5-7.0kev, source counts) is also printed. Note: columns may contain NaN value. In this example, the NaN belongs to obsid=2706, which is an HRC observation and thus does not have any broad band data.

Example 4

unix% search_csc pos='16:27:23.622, -24:35:07.21' radius=0.1 out=none
sensitivity=yes catalog=csc1

Perform a cone search with an additional lookup of the limiting sensitivity value at the requested location. In this case we find 

search_csc
             pos = 16:27:23.622, -24:35:07.21
          radius = 0.1
         outfile = none
         radunit = arcmin
         columns = INDEF
     sensitivity = yes
        download = none
            root = ./
           bands = broad,wide
       filetypes = regevt,pha,arf,rmf,lc,psf,regexp
         catalog = csc1
         verbose = 1
         clobber = no
            mode = ql

CSC Sensitivity for position: 16:27:23.622,-24:35:07.21
  broad band : 4.3461e-7 [photons/cm^2/s]
  wide band : NaN [photons/cm^2/s]

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

We find that there are no sources in the Chandra Source Catalog within 0.1 arcmin of this location with a broad band limiting sensitivity of 4.3 photon/cm^2/sec. The NaN value for the wide band indicates that no HRC observations, if any, that included this field were included in the catalog.

Parameters

name type def min max units reqd stacks
pos string       J2000 yes  
radius float   0 60   yes  
outfile file         yes  
radunit string arcmin       no  
columns string INDEF       no yes
sensitivity boolean no          
download string none          
root file            
bands string broad,wide          
filetype string regevt,pha,arf,rmf,lc,psf,regexp          
catalog string csc2          
verbose integer 1 0 5      
clobber boolean no          

Detailed Parameter Descriptions

Parameter=pos (string required units=J2000)

Comma separated location of cone search.

The location of the cone seach. It currently must be comma separated, but may be specified in either degrees or in sexagesimal format.

All coordinates are J2000.

Parameter=radius (float required min=0 max=60 units=)

Radius of the cone search.

Default units are arcmin but can be changed using the radunit parameter.

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=radunit (string not required default=arcmin)

Controls the units of the search radius

Can be either "arcsec", "arcmin", or "deg" (without quotes).

The separation column, 'sepn' that is returned is converted to the same units when displayed to the screen. The value saved in the .tsv file is kept in arcsec.

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:

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=sensitivity (boolean default=no)

Fetch the limiting sensitivity values?

Because Chandra is not a survey mission, different parts of the sky are exposed for varying lengths of time with different instrument configurations and thus different upper limits on source fluxes for non-detected sources.

The CSC limiting sensitivity service can retrieve the upper photon flux limit, in units of photon/cm^2/sec.

Setting this parameter to yes will query the limiting sensitivity service and will print the results for each specified energy band.

The CSC2 limiting sensitivity data are not currently available via this tool.

Parameter=download (string default=none)

Retrieve the associated data products?

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

When asked, users have 4 choices

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.

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.

For catalog=csc2 the valid filetype values are:

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 source name, "CXOJ...", observation id (obsid_obi), and then by region id. This heiarchry ensures that the large per-obi files are only retrieved/stored once per master src

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

Parameter=catalog (string default=csc2)

Select which version of CSC catalog: csc1|csc2|current

The "current" CSC catalog is, as of September 2022, the in-production version of CSC 2.1. Please see the Chandra Source Catalog Release 2.1 page for details and important caveats.

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.14.3 (September 2022) release

The script has been updated to support searching the "current" Chandra Source Catalog. The "current" CSC catalog is, as of September 2022, the in-production version of CSC 2.1. Please see the Chandra Source Catalog Release 2.1 page for details and important caveats.

Changes in the script 4.11.5 (October 2019) release

Version 2 of the Chandra Source Catalog has been officially released. The script has been updated to access csc2 by default. Users can access the previous version using catalog=csc1.

Note: The CSC2 limiting sensitivity data is not currently available via this tool.

Changes in the scripts 4.11.2 (April 2019) release

Corrects logic introduced to fall back to using curl if CXC websites redirect to secure sites. User errors such as incorrect column names would not have been reported correctly.

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

Caveats

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, obsid_search_csc, search_csc, splitobs
/ ciao4.15 / ahelp / search_csc.html