cda_data

Context: contrib

Synopsis

Download public data by ObsId from the Chandra archive (Python interface).

Syntax

from ciao_contrib.cda.data import download_chandra_obsids
rval = download_chandra_obsids(obsids, filetypes=None, mirror=None,
username=None, userpass=None)

obsids is a list of ObsId values (can be strings or integers). If
filetypes is not None then it should be an array of strings, each a
member of ciao_contrib.cda.data.known_file_types.

The return is an array of True or False values, indicating whether the
observation was found in the archive.

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

Description

The download_chandra_obsids routine downloads publically available ObsIds from the Chandra Data Archive. It is used by the download_chandra_obsid script but can be used from a Python script or session.

Loading the routine

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

from ciao_contrib.cda.data import download_chandra_obsids

Examples

Example 1

>>> from ciao_contrib.cda.data import download_chandra_obsids
>>> download_chandra_obsids([1843])
[True]

Download the data for ObsId 1843 into the current working directory; the data will be placed into the directory 1843/. Since the filetypes argument was not set all data is downloaded. Any existing data (i.e. from a previous download attempt) will not be over-written, although if the file size in the archive is larger than the local version it is assumed that the previous download had been interrupted and it will be restarted.

The [True] return argument indicates that ObsId 1843 was found in the archive, but it does not indicate whether any data was actually downloaded.

Example 2

>>> download_chandra_obsids([1842,1843], filetypes=['fov', 'asol'])
[True, True]

Here we download just the FOV (field-of-view) and ASOL (aspect solution) files for the two ObsIds.

Example 3

>>> import ciao_contrib.logger_wrapper as lw
>>> lw.initialize_logger("download", verbose=1)
>>> download_chandra_obsids([1842,1843], filetypes=['fov', 'asol'])
Downloading files for ObsId 1842, total size is 2 Mb.
...

The default behavior is to create no screen output. This can be changed by using the ciao_contrib.logger_wrapper module, as shown in this example (the verbose values are integers from 0 to 5, with the same meaning as the verbose parameter for CIAO tools).

Example 4

>>> mirror = 'ftp://cdaftp.cda.harvard.edu/pub'
>>> res = download_chandra_obsids(obsids, mirror=mirror)
>>> if not all(res): print("Some ObsIds were not found")

Here we download the observations given in the obsids array from a mirror site, using the mirror argument. The res variable can be inspected to find out if all the data was found in the archive; one example is shown above.

Note that for the mirror argument here we used the location of the Chandra Data Archive, so this particular run is equivalent to not setting the mirror argument.

File formats

When the filetypes argument is left at its default value of None, all the data files for an ObsId are downloaded. To restrict the files downloaded, supply an array of strings, where each element is one of the following (see the Chandra data products guide for more information):

Supported file formats

File format	Description
aoff	Aspect offset files
aqual	Aspect quality files
asol	Aspect solution files
bias	Bias maps.
bpix	Bad-pixel file.
cntr_img	High-resolution image (JPEG and FITS) of the center of the field of view.
dtf	Dead-Time Factor file.
eph1	Ephemeris files (Orbit, Solar, Lunar, and Viewing Angles)
evt1	Level 1 event file.
evt2	Level 2 event file.
flt	Good-Time Intervals for the observation.
fov	Field-of-view file for the observation.
full_img	Low-resolution image (JPEG and FITS) of the field of view.
msk	The detector mask file.
mtl	The mission timeline.
oif	The Observation Index File.
osol	The on-board-computer (OBC) aspect solution files.
pbk	The parameter block file.
pha2	Grating spectra.
soff	Alignment offset files (these are no longer produced, as of DS 8.4).
src2	Imaging source list (these are no longer produced, as of DS 8.4).
stat	The exposure statistics file.
vv	The Verification and Validation files for the observation.

Mirror sites of the Chandra Data Archive

If you have set up, or have access to, a mirror of the Chandra Data Archive (it can be only a partial archive), then you can use the mirror argument to set the location of the mirror.

If an ObsId can not be found on the mirror site then it is skipped; i.e. the routine will not also check the CDA site for the data.

The mirror location should include the URL of the FTP site (the leading ftp:// is required) and the path up to, but not including, the byobsid/ directory. So, for the Chandra Data Archive itself you would use

ftp://cdaftp.cfa.harvard.edu/pub

(although obviously in this case you do not need to use the mirror option). Please see the documentation for the mirror site to find out the correct path to use.

If needed, you can include a username and password in the mirror setting, following RFC3986, for instance

ftp://anonymous:foo@bar.com@cdaftp.cfa.harvard.edu/pub

or with the username and userpass arguments.

Changes in the scripts 4.5.4 (August 2013) release

Support for CDA mirror sites

The mirror, username, and userpass arguments have been added to download_chandra_obsids in this release. Documentation for the ciao_contrib.cda.data 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.