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.
Examples
Example 1
unix% obsid_search_csc obsid=635 outfile=635.tsv download=none mode=h catalog=csc2
Search for all sources that were detected in OBS_ID 635 in CSC 2:
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 = csc2
verbose = 1
clobber = no
mode = h
128 rows returned by query
128 Different Master Source(s).
1 Different Observation(s).
name ra dec obsid
2CXO J162603.0-242336 2.465126e+02 -2.439342e+01 635
2CXO J162605.7-242756 2.465241e+02 -2.446565e+01 635
2CXO J162606.3-242132 2.465264e+02 -2.435916e+01 635
2CXO J162607.0-242724 2.465293e+02 -2.445679e+01 635
...
2CXO J162754.6-243715 2.469778e+02 -2.462110e+01 635
2CXO J162755.1-242839 2.469800e+02 -2.447770e+01 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[22] Source name in the format '2CXO Jhhmmss.s{+|-}ddmmss[X]'
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 position error ellipse
5 conf_flag String[5] Source may be confused (source regions overlap in one or more contributing stack
6 sat_src_flag String[5] Source is saturated in all observations; source properties are unreliable
7 significance Real4 -Inf:+Inf Highest flux significance (S/N) across all stacked observations and energy bands
8 flux_aper_b erg/s/cm^2 Real4 -Inf:+Inf Aperture-corrected net energy flux inferred from the source region aperture, bes
...
63 detect_stack_id String[24] Detect stack identifier (designation of observation stack used for source detect
Example 2
unix% obsid_search_csc 635,637 outfile=none download=ask filetype=evt columns=o.cnts_aper_b catalog=csc2
Search for two observations obsid=635 and 637 from CSC 2. 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 = csc2
verbose = 1
clobber = no
mode = ql
228 rows returned by query
186 Different Master Source(s).
2 Different Observation(s).
name ra dec obsid cnts_aper_b
2CXO J162524.3-241543 2.463514e+02 -2.426214e+01 637 954
2CXO J162537.0-241759 2.464043e+02 -2.429996e+01 637 576
2CXO J162538.1-242235 2.464089e+02 -2.437658e+01 637 3064
2CXO J162541.2-242136 2.464219e+02 -2.436005e+01 637 354
2CXO J162552.4-241705 2.464686e+02 -2.428499e+01 637 175
...
2CXO J162754.6-243715 2.469778e+02 -2.462110e+01 635 39
2CXO J162755.1-242839 2.469800e+02 -2.447770e+01 635 65
Download data for 2CXO J162524.3-241543 in 00637_001 [y,n,a,q]: y
Retrieving files for obsid_obi 00637_001
Retrieved file ./637/acisf00637_001N020_evt3.fits
Download data for 2CXO J162537.0-241759 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 catalog=csc2
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 | csc2.1 | ||||
| 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 '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=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
- "SSS", the set of Stack Source Summary columns
- "SSP", the set of Stack Source Photometry 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.
For catalog=csc2, csc2.1, latest and 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 (FITS)
- stkregimg_jpg - merged detect stack image around source region (JPEG)
- 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. 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.1)
Select which version of CSC catalog: csc1|csc2|csc2.1|current|latest
Setting catalog="current" accesses the current, in production version of the CSC database; the values may change before an catalog is officially released. Setting catalog="latest" accesses the latest officially released catalog.
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.16.2 (August 2024) release
Added support for catalog=latest which will access the latest offical released version of the catalog.
Changes in the script 4.16.1 (April 2024) release
Updated for CSC 2.1 release; csc2.1 is now the default catalog.
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 scripts 4.12.1 (December 2019) release
Change URLs to use the secure CXC web server.
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.
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
There are no known bugs for this tool.
See Also
- contrib
- cda_data, cda_search
- tools::download
- download_chandra_obsid, download_obsid_caldb, find_chandra_obsid, search_csc
- tools::utilities
- splitobs