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=csc2
Perform at 0.02 arcmin radius search around the position RA=83.831577 , Dec=-5.3993566 for CSC 2. 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 = csc2
verbose = 1
clobber = no
mode = ql
13 rows returned by query
1 Different Master Source(s).
13 Different Observation(s).
name ra dec sepn obsid
2CXO J053519.6-052357 8.383170e+01 -5.399215e+00 0.011' 26
2CXO J053519.6-052357 8.383170e+01 -5.399215e+00 0.011' 1522
2CXO J053519.6-052357 8.383170e+01 -5.399215e+00 0.011' 3498
2CXO J053519.6-052357 8.383170e+01 -5.399215e+00 0.011' 3744
2CXO J053519.6-052357 8.383170e+01 -5.399215e+00 0.011' 4373
2CXO J053519.6-052357 8.383170e+01 -5.399215e+00 0.011' 4374
2CXO J053519.6-052357 8.383170e+01 -5.399215e+00 0.011' 4395
2CXO J053519.6-052357 8.383170e+01 -5.399215e+00 0.011' 4396
2CXO J053519.6-052357 8.383170e+01 -5.399215e+00 0.011' 13637
2CXO J053519.6-052357 8.383170e+01 -5.399215e+00 0.011' 14334
2CXO J053519.6-052357 8.383170e+01 -5.399215e+00 0.011' 14335
2CXO J053519.6-052357 8.383170e+01 -5.399215e+00 0.011' 15546
2CXO J053519.6-052357 8.383170e+01 -5.399215e+00 0.011' 6419
Retrieving files for obsid_obi 00026_000
Retrieved file ./2CXOJ053519.6-052357/00026_000/hrcf00026_000N020_r0168_regevt3.fits
pha is not available for HRC observation 00026_000
Retrieved file ./2CXOJ053519.6-052357/00026_000/hrcf00026_000N021_r0168_arf3.fits
rmf is not available for HRC observation 00026_000
Retrieved file ./2CXOJ053519.6-052357/00026_000/hrcf00026_000N028_r0168w_psf3.fits
Retrieved file ./2CXOJ053519.6-052357/00026_000/hrcf00026_000N021_r0168w_regexp3.fits
Retrieved file ./2CXOJ053519.6-052357/00026_000/hrcf00026_000N021_r0168w_lc3.fits
Retrieving files for obsid_obi 01522_002
Retrieved file ./2CXOJ053519.6-052357/01522_002/acisf01522_002N020_r0397_regevt3.fits
Retrieved file ./2CXOJ053519.6-052357/01522_002/acisf01522_002N022_r0397_pha3.fits
Retrieved file ./2CXOJ053519.6-052357/01522_002/acisf01522_002N021_r0397_arf3.fits
Retrieved file ./2CXOJ053519.6-052357/01522_002/acisf01522_002N021_r0397_rmf3.fits
Retrieved file ./2CXOJ053519.6-052357/01522_002/acisf01522_002N028_r0397b_psf3.fits
Retrieved file ./2CXOJ053519.6-052357/01522_002/acisf01522_002N021_r0397b_regexp3.fits
Retrieved file ./2CXOJ053519.6-052357/01522_002/acisf01522_002N021_r0397b_lc3.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=csc2
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 = csc2
verbose = 2
clobber = no
mode = h
20 rows returned by query
4 Different Master Source(s).
5 Different Observation(s).
name ra dec sepn obsid
2CXO J162622.1-242448 2.465925e+02 -2.441344e+01 0.45' 619
2CXO J162622.1-242448 2.465925e+02 -2.441344e+01 0.45' 637
2CXO J162622.1-242448 2.465925e+02 -2.441344e+01 0.45' 618
2CXO J162622.1-242448 2.465925e+02 -2.441344e+01 0.45' 617
2CXO J162622.1-242448 2.465925e+02 -2.441344e+01 0.45' 635
2CXO J162623.5-242439 2.465983e+02 -2.441104e+01 0.21' 618
2CXO J162623.5-242439 2.465983e+02 -2.441104e+01 0.21' 617
2CXO J162623.5-242439 2.465983e+02 -2.441104e+01 0.21' 619
2CXO J162623.5-242439 2.465983e+02 -2.441104e+01 0.21' 637
2CXO J162623.5-242439 2.465983e+02 -2.441104e+01 0.21' 635
2CXO J162624.0-242448 2.466002e+02 -2.441341e+01 0.032' 617
2CXO J162624.0-242448 2.466002e+02 -2.441341e+01 0.032' 619
2CXO J162624.0-242448 2.466002e+02 -2.441341e+01 0.032' 637
2CXO J162624.0-242448 2.466002e+02 -2.441341e+01 0.032' 618
2CXO J162624.0-242448 2.466002e+02 -2.441341e+01 0.032' 635
2CXO J162625.3-242444 2.466054e+02 -2.441249e+01 0.27' 637
2CXO J162625.3-242444 2.466054e+02 -2.441249e+01 0.27' 619
2CXO J162625.3-242444 2.466054e+02 -2.441249e+01 0.27' 618
2CXO J162625.3-242444 2.466054e+02 -2.441249e+01 0.27' 617
2CXO J162625.3-242444 2.466054e+02 -2.441249e+01 0.27' 635
Retrieving files for obsid_obi 00619_000
Retrieved file ./arc/2CXOJ162622.1-242448/00619_000/acisf00619_000N020_evt3.fits
Retrieved file ./arc/2CXOJ162622.1-242448/00619_000/acisf00619_000N020_fov3.fits
Contacting resource 'http://cda.cfa.harvard.edu/csccli/browse?packageset=619.0.38%2Fspectrum%2F&version=rel2.0'
Contacting resource 'http://cda.cfa.harvard.edu/csccli/browse?packageset=619.0.38%2Farf%2F&version=rel2.0'
Contacting resource 'http://cda.cfa.harvard.edu/csccli/browse?packageset=619.0.38%2Frmf%2F&version=rel2.0'
Retrieved file ./arc/2CXOJ162622.1-242448/00619_000/acisf00619_000N023_r0038_reg3.fits
Retrieving files for obsid_obi 00637_001
...
Retrieving files for obsid_obi 00617_000
File acisf00617_000N020_evt3.fits already retrieved, will make a copy
File acisf00617_000N020_fov3.fits already retrieved, will make a copy
Contacting resource 'http://cda.cfa.harvard.edu/csccli/browse?packageset=617.0.91%2Fspectrum%2F&version=rel2.0'
Contacting resource 'http://cda.cfa.harvard.edu/csccli/browse?packageset=617.0.91%2Farf%2F&version=rel2.0'
Contacting resource 'http://cda.cfa.harvard.edu/csccli/browse?packageset=617.0.91%2Frmf%2F&version=rel2.0'
Retrieved file ./arc/2CXOJ162625.3-242444/00617_000/acisf00617_000N023_r0091_reg3.fits
Retrieving files for obsid_obi 00635_000
File acisf00635_000N020_evt3.fits already retrieved, will make a copy
File acisf00635_000N020_fov3.fits already retrieved, will make a copy
File acisf00635_000N022_r0095_pha3.fits already retrieved, will make a copy
File acisf00635_000N021_r0095_arf3.fits already retrieved, will make a copy
File acisf00635_000N021_r0095_rmf3.fits already retrieved, will make a copy
File acisf00635_000N021_r0095_reg3.fits already retrieved, will make a copy
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=csc2
Use the name resolver to search for sources with 1 arcmin of M81 for CSC 2.
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.88821939854 dec=69.06529514038
Required column s.detect_stack_id was added to columns
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
689 rows returned by query
30 Different Master Source(s).
24 Different Observation(s).
name ra dec sepn obsid cnts_aper_b
2CXO J095526.3+690437 1.488596e+02 6.907699e+01 0.93' 390 5
2CXO J095526.3+690437 1.488596e+02 6.907699e+01 0.93' 4751 28
2CXO J095526.3+690437 1.488596e+02 6.907699e+01 0.93' 735 66
2CXO J095526.3+690437 1.488596e+02 6.907699e+01 0.93' 9122 3
2CXO J095526.3+690437 1.488596e+02 6.907699e+01 0.93' 12301 9
2CXO J095526.3+690437 1.488596e+02 6.907699e+01 0.93' 9805 0
2CXO J095526.3+690437 1.488596e+02 6.907699e+01 0.93' 2706 NaN
2CXO J095526.3+690437 1.488596e+02 6.907699e+01 0.93' 2938 NaN
2CXO J095526.3+690437 1.488596e+02 6.907699e+01 0.93' 9540 44
..
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 and 2938, which are HRC observations and thus do 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. Note that this capability is only provided for searches of version 1 of CSC; the sensitivity calculation for version 2 are more complex and are not amenable to scripting at this time.
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 '2CXO 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:
- "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=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
- "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.
For catalog=csc2 and catalog=current the list of filetype values is
- evt - per observation event file
- asol - per observation aspect solution with astrometric corrections applied
- ahst - aspect histograms
- bpix - bad pixel file
- fov - field of view file
- pixmask - pixel mask file
- img - exposure corrected and background subtracted full field image
- bkgimg - background image
- exp - exposure maps
- poly - convex hull polygon regions
- regevt - per region, per observation event file
- pha - spectrum
- arf - Auxillary response file
- rmf - Response matrix
- reg - source region definitions
- regimg - image around source region
- psf - simulated PSF image
- regexp - exposure map around source region
- lc - lightcurve
- draws - MCMC random sample draws
- aperphot - aperture photometry results
- stkevt - merged event file for observations in detect stack
- stkfov - merged FOV file for detect stack
- stkecorrimg - detect stack exposure corrected image
- stkbkgimg - detect stack background image
- stkexpmap - exposure map for detect stack
- sensity - limiting sensitivity for detect stack
- stkregevt - merged detect stack event file around source region
- stksrcreg - source region for detect stack
- stkregimg - merged detect stack image around source region
- stkregexp - combined detect stack exposure map
- stkdraws - MCMC draws from combined detect stack photometry
- stkaperphot - photometry results for detect stack
- mrgsrc - master source properties tables
- bayesblks - Bayesian blocks definitions
- srcaperphot - master source aperture photometry
- srcpoly - master extended source region polygons
The valid options for catalog=csc1 are
- 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 ("2CXOJ..." or "CXOJ..."), and then by region id. and then by region id. This hierarchy ensures that the large per-obi files are only retrieved/stored once per master source.
If filetype is left blank, all available 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.15.3 (August 2023) release
Added the master 'srcpoly' file type to retrieve the Per-Master extended source polygon regions.
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.
About Contributed Software
This script is not an official part of the CIAO release but is made available as "contributed" software via the CIAO scripts page. Please see this page for installation instructions.
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
- download_chandra_obsid, download_obsid_caldb, find_chandra_obsid, obsid_search_csc
- tools::utilities
- splitobs