/ csc / quick / location.html

Is my source in Release 2.0 of the Chandra Source Catalog?

There are three approaches for searching CSC 2.0 described below: using the CSCweb interface, the CSCview application, or by writing an ADQL query. The catalog coverage section describes ways of approximating the sky current sky coverage of CSC 2.0, although the use of the limiting sensitivity service provided by the Quick-Search interface is to be preferred.

CSCweb Quick-Search interface

The quick-search interface is a web page which accepts one or more positions and returns basic master-source properties from the catalog. It also provides the limiting-sensitivity value for the location, and so can be used to identify whether the catalog could have identified the source - which requires that there was at least one Chandra observation covering the sky, and that the observation was sensitive enough to detect the source.

CSCview

The CSCview application provides a quick way to search the catalog by location. A brief run-through of the steps required is provided here, and the CSCview help pages can be read for more information. The following requires that CSCview has been downloaded, Java is installed, and that cscview.jar is in the current working directory (Mac OS users can download a DMG which provides a CSCview application).

Start CSCview with:

unix% java -jar cscview.jar

or, for Java 9 users:

unix% java --add-modules java.se.ee -jar cscview.jar

Select the "Release 2.0" database on the Catalog tab, and then select the Search icon just below the File menu.

The Query should be selected, a number of "windows" have appeared, and the title changed to "Chandra Source Catalog Release 2.0".
A position search can be started by selecting the "Cone" radio button which appears below the label "Position Search:" in the middle of the window. When selected, the area to the right will change to allow a search by name or coordinates. Select the "By Coordinates" button and change from Equatorial to Galactic if necessary. Insert the location - Equatorial coordinates can be given as decimal degrees or in sexagesimal notation - and change the search radius as desired.
Once the locaiton has been entered, selecting the Search icon will start the query. The tab will change to the "Results" tab, with a status message displayed at the bottom of the window. The message "Search completed" indicates that the query has finished, and the results will appear in the main area of the GUI. An empty result does not mean that the source is not part of CSC 2.0, as discussed in the coverage section below.
If one or more matches were found then basic properties will be reported for these sources (since the default query was used, which returns the name, location, and a basic aperture flux in the broad and wide bands (depending on whether the detection was on ACIS or HRC).

The source list can be downloaded, or data products for one or more sources can be selected at this stage. The CSCview help documentation can be read for more information on these capabilities.

An ADQL query

The ADQL interface to the catalog can be used. In the following example the curl command-line tool will be used, but any method that can make a HTTP request with parameters can be used. The ADQL command-line interface pages provide more information on the capabilities and syntax of this interface.

The ADQL query used in this example uses a 5 arcsecond search radius (0.083 arcminutes) in the WHERE clause to limit the search around a Right Ascension of 138.9683 degrees and Declination of 29.557 degrees. The columns returned are limited to the angular separation from this position, master-source name, and master-source significance. When broken into multiple lines the query looks like:

SELECT DISTINCT top 10 dbo.separation(m.ra, m.dec, 138.9683, 29.557)
as separation, m.name, m.significance
FROM master_source m
WHERE (dbo.cone_distance(m.ra, m.dec, 138.9683, 29.557) <= 0.083)
ORDER BY separation ASC

However, it must all be one one line otherwise the following call will fail. An example is the file location.adql, which is "evaluated" using the following call:

unix% curl --form query=@location.adql http://cda.cfa.harvard.edu/csccli/getProperties
#Column	separation	(E9.6)		(.separation)	[""]	[]
#Column	name	(A22)	Source name in the format '2CXO Jhhmmss.s{+|-}ddmmss[X]'(master_source.name)	[""]	[]
#Column	significance	(F9.2)	Highest flux significance (S/N) across all stacked observations and energy bands	(master_source.significance)	[""]	[]
separation	name	significance
     1.36	 2CXO J091552.3+293323	    54.79

The results are - by default - written out in as an ASCII column format, where the columns are tab separated. If written to a file - e.g. results.tsv - rather than displayed on screen, the CIAO Data Model can be used to process the output. For example:

unix% dmlist "results.tsv[opt kernel=text/tsv]" cols
 
--------------------------------------------------------------------------------
Columns for Table Block results.tsv
--------------------------------------------------------------------------------
 
ColNo  Name                 Unit        Type             Range
   1   separation                        Real4          -Inf:+Inf            
   2   name                              String[22]                          Source name in the format '2CXO Jhhmmss.s{+|-}ddmmss[X]'
   3   significance                      Real4          -Inf:+Inf            Highest flux significance (S/N) across all stacked observations and energy bands

These queries can also be made from Python; for example (using the six module included with CIAO), Note that the urlopen function requires the query string to be bytes-encoded. In this example the ADQL query is read from an external file but it can also be created directly in Python.

>>> from six.moves.urllib import parse, request
>>> qry = open('location.adql', 'r').read().strip()
>>> data = parse.urlencode({'query': qry})
>>> req = request.urlopen("http://cda.cfa.harvard.edu/csccli/getProperties", data.encode())
>>> answer = req.read()
>>> print(answer.decode())
#Column	separation	(E9.6)		(.separation)	[""]	[]
#Column	name	(A22)	Source name in the format '2CXO Jhhmmss.s{+|-}ddmmss[X]'(master_source.name)	[""]	[]
#Column	significance	(F9.2)	Highest flux significance (S/N) across all stacked observations and energy bands	(master_source.significance)	[""]	[]
separation	name	significance
     1.36	 2CXO J091552.3+293323	    54.79

Changing the ADQL query

The command-line interface page describes in more detail the functionality available (e.g. how to change output format) and more information on ADQL. One easy way to create a new query is to use CSCview to set up the query but to then use the Query sub-menu from the View menu, which displays the ADQL form of the query. This can be copied, or saved to a file, for use with the command-line interface.

Catalog coverage

[A view of the WWT web page, showing the stacks covering the Hubble Deep Field North and its neighbors. Several features of the WWT interface - showing the source locations in the area, information on a selected stack, and a handly list of commonly-visited locations - are shown.

As described above, the quick-search interface will return the limiting sensitivity for one or more points. The per-stack sensitivity images can also be downloaded via CSCview, although please note that overlapping stacks can mean that multiple stack images will need to be downloaded.

An approximate view of the catalog coverage can be found using the World Wide Telescope visualization, which lets you move around the sky, view the outlines of the stacks from CSC 2.0, and display source locations and basic properties. The background data can be changed between long (CMB) and short (Gamma ray) wavelengths.

/ csc / quick / location.html