cda_search

Context: contrib

Synopsis

Find publicly-available Chandra ObsIds from the Chandra archive (Python interface).

Syntax

from ciao_contrib.cda.search import search_chandra_archive,
get_chandra_obs
sr = search_chandra_archive(ra, dec, size=0.1, instrument=None,
grating=None)
co = get_chandra_obs(sr, ra=None, dec=None, fmt=None)

ra and dec are in decimal degrees (ICRS). The size argument is a
radius, in degrees. The instrument argument can be one of "acis",
"acis-i", "acis-s", "hrc", "hrc-i", or "hrc-s". The grating argument
can be "none", "letg", or "hetg".

The fmt argument can be " " or ":" .

The Python help command - help(search_chandra_archive) - can be used

Description

The search_chandra_archive routine will find all publically-available observations that overlap the given position (or circle, if radius is not 0), by querying the Chandra Footprint Service. The instrument and grating arguments can be used to filter the search. It returns a NumPy structured array if there was a match, otherwise None.

The get_chandra_obs routine converts the return value of search_chandra_archive into an OrderedDict. If the ra and dec arguments are given then an extra field is included, giving the separation of each observation from the position. If the fmt argument is given then extra fields are added containing the RA and Dec values converted to strings.

These routines are used by the find_chandra_obsid script but they can be used from a Python script or session.

Loading the routines

The routines can be loaded into a Python session or script by saying:

from ciao_contrib.cda.search import *

Examples

Example 1

>>> from ciao_contrib.cda.search import *
>>> sr = search_chandra_archive(8.815, -43.566, size=0.3)
>>> print(sr == None)
False
>>> print(sr.size)
52
>>> print(sr.dtype.names[0:5])
('ObsId', 'target_name', 'obs_date', 'RA', 'Dec')
>>> print(sr['ObsId'][0:10])
[7016 7016 7016 7016 7016 7016 7016 7016 7017 7017]
>>> print(sr[0])
(7016, 'ELAIS-S1 A', '2005-09-26T22:17:00', 8.80125, -43.3555555555556,
7900290, ...
print(sr[0]['target_name'])
ELAIS-S1 A

Here we search the Chandra Archive for public observations within 0.3 degrees of RA=8.815 and Dec=-43.566. As the return is not None, there were matches ( at the time of writing there were 52 matches, but as we show below, this does not mean 52 different ObsIds). Since the return value is a NumPy structured array, we can query it by colummn (e.g. 'ObsId') or by row (e.g. '[0]').

Example 2

>>> obs = get_chandra_obs(sr)
>>> print(obs.keys())
['obsid', 'instrument', 'grating', 'exposure', 'ra', 'dec', 'target',
'obsdate', 'piname']
>>> print(obs['obsid'])
[7016, 7017, 7018, 7019, 7020, 7328]

The get_chandra_obs() routine takes the return value from search_chandra_obsid and converts it to a dictionary (actually a collections.OrderedDict object), ensures there's only one entry per ObsId, and returns only a subset of the columns (after renaming them).

The ciao_contrib.cda.download_chandra_obsids routine (ahelp cda_data) can be used to download the data.

Example 3

>>> obs2 = get_chandra_obs(sr, ra=8.815, dec=-43.566)
>>> s1 = set(obs.keys())
>>> s2 = set(obs2.keys())
>>> print(s2.difference(s1))
set(['separation'])
>>> print(obs2['separation'])
[12.640858276726794, 20.931687543092089, ..., 7.2534106580554472]

By adding in ra and dec arguments to the get_chandra_obs call, an extra column - called "separation" - is added, which gives the separation of the observation from the position in arcminutes. Here we calculate the separation of the observations from the search position.

Values returned by get_chandra_obs

The keys of the dictionary returned by get_chandra_obs are listed in the table below:

get_chandra_obs keys

Key name	Description
obsid	ObsId of the observation
instrument	One of 'ACIS-I', 'ACIS-S', 'HRC-I', or 'HRC-S'.
grating	One of 'NONE', 'LETG', or 'HETG'.
exposure	The exposure time in kiloseconds.
ra	The aim-point Right Ascension in decimal degrees (ICRS).
dec	The aim-point Declination in decimal degrees (ICRS).
target	The target name (from the observation proposal).
obsdate	The start of the observation, in YYYY-MM-DDTHH:MM:SS format.
piname	The PI's last name.
separation	Only created if ra and dec arguments are not None, this is the separation between the aim point of the observation and the given RA and Dec, in arc minutes.
rastr	If fmt is not None then this is the ra column converted to a string version using the coords.format.deg2ra routine.
decstr	If fmt is not None then this is the dec column converted to a string version using the coords.format.deg2dec routine.

Changes in the scripts 4.5.4 (August 2013) release

Documentation for the ciao_contrib.cda.search module is new in this release.

About Contributed Software

This module 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.