download_chandra_obsid

Context: tools

Synopsis

Download public data by ObsId from the Chandra archive.

Syntax

download_chandra_obsid obsid
download_chandra_obsid obsid1,..,obsidN
download_chandra_obsid obsid filetype
download_chandra_obsid obsid1,..,obsidN filetype1,..,filetypeN

The supported file types are:
aoff aqual asol bias bpix cntr_img dtf eph0 eph1 evt1 evt2 flt fov
full_img msk mtl oif osol pbk pha2 plt soff src2 src_img stat sum vv

The -q or --quiet flags can be used to turn off screen output.

The download_chandra_obsid tool will download the data for the given Chandra Observation Id (ObsId) from the public archive. It can not be used to download proprietary data. Multiple ObsIds can be given as a comma-separated list or as a stack (see 'ahelp stack' for more information).

Where are the files placed?

The files are stored in the current working directory, using the Observation Id as a directory name: so the data for ObsId 1843 would be placed in the directory 1843/. Within this directory the files are placed as they are in the archive, namely a top-level directory containing the oif.fits and V&V report, with the remaining data in the primary/ and secondary/ sub-directories.

How do I download a specific file?

The optional second argument to download_chandra_obsid allows you to restrict the download to one or more files. A comman-separated list (or stack) of file types can be given, so

unix% download_chandra_obsid 1843 evt2,asol,bpix,fov

will just download the evt2, asol, bpix, and fov files for ObsId 1843.

What happens when files already exist?

The tool will skip downloading any files that already exist on disk as long as they are the correct size. If the on-disk version is smaller than the archive version, then download will be resumed rather than started again. A warning message will be displayed if the on-disk version is larger than the archive version.

The behavior described above means that you can interrupt a download and re-start it and will not have to re-download existing data.

Screen output

Unless the -q or --quiet flag was used, each file that is downloaded will be displayed on screen, giving the "type", format, file type before a progress bar of # marks (each # mark indicates 10% of the file). Once the file has been downloaded an average rate is displayed for the download. Examples of the output for two files are shown below:

Type     Format      Size  0........H.........1  Download Time Average Rate
---------------------------------------------------------------------------
vv       pdf        78 Kb  ####################          < 1 s  843.1 kb/s
evt2     fits       17 Mb  ####################            2 s  7170.3 kb/s

If a file has already been downloaded then the message "already downloaded" will be displayed instead of the progress bar.

Example 1

unix% download_chandra_obsid 1843

This will download all the data files for ObsId 1843 to the directory 1843/. The screen output for the run will look something like the following (where many lines have been excluded, indicated by the "..." lines):

Downloading files for ObsId 1843, total size is 67 Mb.

Type     Format      Size  0........H.........1  Download Time Average Rate
---------------------------------------------------------------------------
vv       pdf        78 Kb  ####################          < 1 s  3088.6 kb/s
oif      fits       23 Kb  ####################          < 1 s  858.4 kb/s
...
evt2     fits       17 Mb  ####################            4 s  4740.2 kb/s
...
bpix     fits       11 Kb  ####################          < 1 s  569.1 kb/s
fov      fits        6 Kb  ####################          < 1 s  12.0 kb/s
eph1     fits      281 Kb  ####################          < 1 s  2527.8 kb/s
asol     fits        2 Mb  ####################          < 1 s  2982.5 kb/s
aoff     fits     1005 Kb  ####################          < 1 s  6957.8 kb/s
evt1     fits       35 Mb  ####################            7 s  5413.4 kb/s
...
osol     fits      356 Kb  ####################          < 1 s  3519.9 kb/s

    Total download size for ObsId 1843 = 67 Mb
    Total download time for ObsId 1843 = 19 s

Example 2

unix% download_chandra_obsid 1843 evt1,bpix,pbk,asol,fov

Here we restrict the download to just the evt1, bpix, pbk, asol, and fov files from ObsId 1843.

Example 3

unix% download_chandra_obsid 1842,1843

This will download the data for ObsIds 1842 and 1843 to the directories 1842/ and 1843/ respectively.

Example 4

unix% cat obsids
1842
1843
unix% download_chandra_obsid @obsids

Here we use the support for stacks (see 'ahelp stack' for more information) to download the data for the ObsIds listed in the file obsids, in this case 1842 and 1843.

Example 5

unix% download_chandra_obsid 1842,1843 evt1,asol -q

Here we download only the evt1 and asol files from the two ObsIds and use the -q flag to turn off the screen output.

unix% cat obsids.txt
50
51
1249
unix% download_chandra_obsid @obsids.txt

and the script will download ObsId numbers 50, 51, and 1249.

Bugs

There are no known bugs for this tool.