/ csc / download / vo.html

Virtual Observatory Guide

CSC 2.1 can be accessed using Virtual Observatory-compatible tools such as cone search, Simple Image Access Protocol (SIAP), and the Table Access Protocol (TAP), which allows general-purpose queries written using the Astronomical Data Query Language (ADQL) syntax.

Check the URL

Please note that the CSC 2.1 URLs use the name /csc21XXX/ and the CSC 2.0 URLs use /csc2XXX/.

The Chandra Source Catalog can be accessed and searched using a number of interfaces defined by the International Virtual Observatory Association. These interfaces may often be used directly - via tools such as TopCat and ESA Sky - or from a web page, but they can also be accessed from Python using PyVO, or using tools such as curl or wget.

IVOA interfaces for the CSC
Method	Service
The VO cone-search service lets you find CSC sources near one or more locations on the sky.	http://cda.cfa.harvard.edu/csc21scs/
The VO Simple Image Access Protocol (SIAP) service can be used to identify images, in FITS or JPEG format, of sources and stacks in the CSC.	http://cda.cfa.harvard.edu/csc21siap/
The VO Table Access Protocol (TAP) service can be used to query the CSC database using the ADQL.	http://cda.cfa.harvard.edu/csc21tap/

Using PyVO

PyVO provides access to astronomical data using IVOA standards. Below are examples of how to use our TAP service from a python session, such as within a Jupyter Notebook.

1000 master sources

For a selection of 1000 sources and master source table columns:

import pyvo as vo

tap = vo.dal.TAPService('http://cda.cfa.harvard.edu/csc21tap')

qry = """
SELECT top 1000
  m.name,m.ra,m.dec,m.err_ellipse_r0,m.err_ellipse_r1,m.err_ellipse_ang,
  m.significance,m.likelihood_class,m.conf_flag,m.sat_src_flag,
  m.streak_src_flag,m.flux_aper_b,m.flux_aper_lolim_b,m.flux_aper_hilim_b,
  m.flux_aper_w,m.flux_aper_lolim_w,m.flux_aper_hilim_w,m.flux_aper_avg_b,
  m.flux_aper_avg_lolim_b,m.flux_aper_avg_hilim_b,m.flux_aper_avg_w,
  m.flux_aper_avg_lolim_w,m.flux_aper_avg_hilim_w

FROM csc21.master_source m

WHERE m.name NOT LIKE '%X'

ORDER BY name ASC
"""

results = tap.search(qry)

1000 stack detections

For a selection of 1000 stack detections and stacked-observation detections table columns, including an association with the corresponding master sources:

import pyvo as vo

tap = vo.dal.TAPService('http://cda.cfa.harvard.edu/csc21tap')

qry = """
SELECT top 1000
  m.name,m.ra,m.dec,s.detect_stack_id,s.region_id,s.theta_mean,
  s.flux_significance_b,s.flux_significance_w,s.likelihood_b,
  s.likelihood_w,s.var_flag,s.var_inter_hard_flag,s.src_cnts_aper_w,
  s.src_rate_aper_b,s.src_rate_aper_w,s.flux_aper_b,s.flux_aper_lolim_b,
  s.flux_aper_hilim_b,s.flux_aper_w,s.flux_aper_lolim_w,
  s.flux_aper_hilim_w,s.hard_hm,s.hard_hm_lolim,s.hard_hm_hilim,
  s.hard_ms,s.hard_ms_lolim,s.hard_ms_hilim,s.var_intra_index_b,
  s.var_intra_index_w,s.var_inter_index_b,s.var_inter_index_w 

FROM csc21.master_stack_assoc a,
     csc21.master_source m,
     csc21.stack_source s 

WHERE ((a.match_type = 'u')) AND s.detect_stack_id=a.detect_stack_id 
    AND s.region_id = a.region_id AND m.name=a.name 

ORDER BY name ASC
"""

results = tap.search(qry)

1000 observation detections

For a selection of 1000 observation detections and per-observation detections table columns, including an association with the corresponding master sources:

import pyvo as vo

tap = vo.dal.TAPService('http://cda.cfa.harvard.edu/csc21tap')

qry = """
SELECT top 1000
  m.name,m.ra,m.dec,o.obsid,o.obi,o.gti_obs,o.gti_end,o.region_id,
  o.theta,o.phi,o.flux_significance_b,o.flux_significance_w,
  o.likelihood_b,o.likelihood_w,o.var_code,o.cnts_aper_b,o.cnts_aper_w,
  o.src_cnts_aper_b,o.src_cnts_aper_w,o.src_rate_aper_b,o.src_rate_aper_w,
  o.flux_aper_b,o.flux_aper_lolim_b,o.flux_aper_hilim_b,o.flux_aper_w,
  o.flux_aper_lolim_w,o.flux_aper_hilim_w,o.hard_hm,o.hard_hm_lolim,
  o.hard_hm_hilim,o.hard_ms,o.hard_ms_lolim,o.hard_ms_hilim,
  o.var_index_b,o.var_index_w,o.livetime,o.detector
 
FROM csc21.master_source m,
     csc21.master_stack_assoc a,
     csc21.observation_source o,
     csc21.stack_observation_assoc b,
     csc21.stack_source s

WHERE ((a.match_type = 'u')) AND s.detect_stack_id=a.detect_stack_id AND s.region_id = a.region_id AND m.name=a.name AND s.detect_stack_id = b.detect_stack_id and s.region_id = b.region_id and b.obsid = o.obsid and b.obi = o.obi and b.region_id = o.region_id

ORDER BY name ASC
"""

results = tap.search(qry)

For a more-detailed example, such as using the cone-search query and accessing catalog data tables and products, see the ADQL and the CSC page and the "Accessing release 2.1 of the Chandra Source Catalog with PyVO" notebook.

The PyVO module can be installed into your CIAO environment with the command:

% pip install pyvo
Collecting pyvo
  Downloading pyvo-1.5.1-py3-none-any.whl.metadata (4.7 kB)
...
Installing collected packages: pyvo
Successfully installed pyvo-1.5.1

(the exact version of the package may be different than shown here).

Using Python

Although PyVO provides the best interface to the IVOA CSC services, you can call the services directly. Visiting the service URL - such as http://cda.cfa.harvard.edu/csc21scs/ - will report the URL to use, along with the required and optional arguments.

Python example

The following Python example shows a query being made to find all sources within 0.05 degrees of Right Ascension 246.7925 and Declination -24.32027. The response is in VOTable format.

from urllib.request import urlopen
from urllib.parse import urlencode

# Note that the parameter names are case sensitive
baseurl = 'http://cda.cfa.harvard.edu/csc21scs/coneSearch'
params = {'RA': 246.7925, 'DEC': -24.32027, 'SR': 0.05, 'VERB': 1}
url = f'{baseurl}?{urlencode(params)}'

rsp = urlopen(url).read().decode('utf-8')
print(rsp)

More information in using the Python urllib module can be found at HOWTO Fetch Internet Resources Using The urllib Package. Note that this example does not try to deal with any errors, such as invalid parameters or network errors.

Command-line tools

The IVOA interfaces can be also called using curl or wget.

curl and wget Cone Search example

The python query from above can also be run using either of the following, which will create the cone.vot VOTable file:

curl

unix% curl --output cone.vot \
  --data RA=246.7925 \
  --data DEC=-24.32027 \
  --data SR=0.05 \
  --data VERB=1 \
  http://cda.cfa.harvard.edu/csc21scs/coneSearch

wget

unix% wget -O cone.vot \
  'http://cda.cfa.harvard.edu/csc21scs/coneSearch?RA=246.7925&DEC=-24.32027&SR=0.05&VERB=1'

curl and wget SIAP example

The Simple Image Access Protocol has a similar interface, but note that the position is specified as a pair of coordinates, and a "format" argument is needed to select what type of image should be returned. In this example we use a significantly-larger search radius than for the cone-search:

curl

unix% curl --output images.vot \
  --data POS=246.7925,-24.32027 \
  --data SIZE=0.4 \
  --data VERB=2 \
  --data FORMAT=ALL \
  http://cda.cfa.harvard.edu/csc21siap/queryImages

wget

unix% wget -O images.vot \
  'http://cda.cfa.harvard.edu/csc21siap/queryImages?POS=246.7925,-24.32027&SIZE=0.4&VERB=2&FORMAT=ALL'

curl TAP example

This does not search for sources or images near a given location, but instead runs a simple query of 5 sources.

curl

unix% curl --request POST \
  --location \
  --data REQUEST=doQuery \
  --data PHASE=RUN \
  --data FORMAT=votable \
  --data LANG=ADQL \
  --data 'QUERY=select TOP 5 m.name, m.ra, m.dec from csc21.master_source m' \
  http://cda.cfa.harvard.edu/csc21tap/sync

The queries from the PyVO examples can be used instead, but long queries can be annoying to send to curl!

/ csc / download / vo.html