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.
See Also
- contrib
- cda_search, coords_chandra, coords_format, coords_gratings, coords_utils, identify_name
- tools::download
- download_chandra_obsid, download_obsid_caldb, find_chandra_obsid, obsid_search_csc, search_csc
- tools::utilities
- splitobs