Synopsis
Find, and optionally download, publicly-available Chandra ObsIds from the Chandra archive.
Syntax
find_chandra_obsid arg dec [radius] [download] [instrument] [grating] [detail] [mirror] [verbose]
Description
The find_chandra_obsid tool will find publicly available Chandra data that covers a circular region of sky (a point search can be used by setting the search radius to 0). The download parameter can be used to download the data, or the download_chandra_obsid script can be used.
This tool makes use of the Chandra Footprint Service, which can also be searched using a web browser.
Single argument
When called with a single argument, it is checked to see if it matches an Observation Id (ObsId) value (that is, an integer between 1 and 65535), otherwise it is treated as an object name.
ObsId
If an integer value is given, then the Chandra Data Archive is searched to find the location of the observation, and this is used in the search (which means that the ObsId will be one of the returned values). If the ObsId is unrecognized by the archive then it is treated as an object name.
You can check the coordinates that are returned for the name by setting the verbose parameter to 2.
Object names
The name resolver at the CADC is used to convert names to a position. If the name contains a space then it must be given surrounded by quotes - e.g. "NGC 1333" - to ensure that the script recognizes it as a single argument.
You can check the coordinates that are returned for the name by setting the verbose parameter to 2.
Solar system objects
The name resolver does not support solar-system objects.
Using a position
If two arguments are given then they are taken to be the Right Ascension and Declination to search about (J2000). A range of formats can be used (which may require surrounding the value in quotes or protecting characters depending on the shell you are using):
unix% find_chandra_obsid 12.3 -1.2 unix% find_chandra_obsid 12:14 "-1 15 23" unix% find_chandra_obsid "12h 14m 3.2s" "-0d 5'"
If verbose is set to 2 then the script will display the result of the conversion from the input values into decimal degrees.
Selecting instruments
The default search uses all instruments, but you can restrict the results using the instrument parameter, so
unix% find_chandra_obsid m31 instrument=acis unix% find_chandra_obsid m31 instrument=aciss
searches for all ACIS or just ACIS-S observations of M31.
Selecting gratings
The default search does not filter on the grating; to do so use the grating parameter.
unix% find_chandra_obsid mkn421 grating=letg unix% find_chandra_obsid perseus grating=any
searches for LETG observations of Markarian 421 and any grating observations of Perseus.
Downloading data
When the download parameter is "none" - which is the default - then a table of values for the matching observations are displayed. If set to "all" then the matching ObsIds are downloaded to the working directory; in this case the information on the matching ObsIds is not given. When set to "ask", you are queried whether to download each ObsId and then the download will take place for the chosen observations.
The data is downloaded to the current working directory and uses the same layout as the download_chandra_obsid script. If the file already exists it will not be over-written, unless the file size is larger than on disk; a smaller value is taken to mean a previous download attempt was interrupted, so it will append to the file.
Unlike download_chandra_obsid, there is no way to select a subset of data to download for each ObsId.
Subsetting the data for download
This script provides limited capabilities for filtering the data, by using the instrument and grating parameters. More complicated filtering can be done by taking advantage of the fact that the screen output of the script can be manipulated using the CIAO command-line tools. For example
unix% find_chandra_obsid 350.86 58.81 > matches.dat
unix% dmlist matches.dat counts
115
unix% dmlist "matches.dat[time>20,inst=HRC-I][cols obsid]" data,raw
# obsid
1505.0
unix% download_chandra_obsid 1505
...
shows that ObsId 1505 is the only HRC-I observation with an exposure of 20 ks or higher. The download_chandra_obsid tool is then used to download the matching observation.
Examples
Example 1
unix% find_chandra_obsid 3040
All observations that overlap the aim point of ObsId 3040 are reported.
Setting the verbose value to 2, or higher, displays the coordinates returned by by the name resolver; for instance
unix% find_chandra_obsid 3040 verbose=2
Looking for position of ObsId 3040
ObsId 3040 status=archived RA=12 01 53.70 Dec=-18 52 35.50
Found ra=180.47375 dec=-18.8765277778
= 12h 1m 53.7s -18d 52' 35.5"
...
Example 2
unix% find_chandra_obsid arp244
In this case a name resolver is used to convert the argument into a position, and then all observations which overlap that position are reported. Unfortunately solar system names are not supported.
Setting the verbose value to 2, or higher, displays the coordinates returned by by the name resolver; for instance
unix% find_chandra_obsid arp244 verbose=2
Querying name resolvers for name=arp244
Found ra=180.47208 dec=-18.87694
= 12h 1m 53.2992s -18d 52' 36.984"
...
Example 3
unix% find_chandra_obsid 'ARP 244'
If the object name contains spaces then it must be quoted with single or double quotes.
Example 4
unix% find_chandra_obsid 180.47 -18.88
If two arguments are given then the script interpets these as Right Ascension and Declination. This call will find all the publicly-available Chandra observations that overlap the circle with a center at RA of 180.47 degrees and Declination of -18.88 degrees, and a radius of 1 arcminute.
Example 5
unix% find_chandra_obsid 12:1:54 -18:52:36
The script supports the most common formats for specifying RA and Dec. Values that include spaces will need to be quoted to avoid being interpreted as multiple arguments by the shell - e.g.
unix% find_chandra_obsid "12 1 54" "-18 52 36" unix% find_chandra_obsid "12h 1m 54s" "-18d 52' 36"'"'
Setting the verbose value to 2, or higher, displays the decimal coordinates calculated by the script:
unix% find_chandra_obsid "12h 15m 46s" "-0 0 4" verbose=2 Converting 12h 15m 46s and -0 0 4 to decimal degrees. -> 183.941666667 -0.00111111111111 ...
Example 6
unix% find_chandra_obsid 180.47 -18.88 detail=obsid
Here we list just the ObsId values for each observation. The detail setting can also be changed to all to get more columns (basically the RA and Dec of the aim point for each observation).
Example 7
unix% find_chandra_obsid 180.47 -18.88 download=ask
Instead of listing all the matches, you will be asked whether to download each ObsId; the output will look something like
There were 7 matching observations: 1/7: Obsid=315 Sepn=0.3 Inst=ACIS-S Grat=NONE Exp=73.2 ObsDate=1999-12-01 PI=Murray Target=NGC 4038/NGC 4039 2/7: Obsid=3040 Sepn=0.3 Inst=ACIS-S Grat=NONE Exp=69.9 ObsDate=2001-12-29 PI=Fabbiano Target=NGC 4038/NGC 4039 ... 7/7: Obsid=3718 Sepn=0.3 Inst=ACIS-S Grat=NONE Exp=35.2 ObsDate=2002-07-13 PI=Fabbiano Target=NGC 4038/NGC 4039 Use h to get help on the download options. 1/7: Obsid=315 Sepn=0.3 Inst=ACIS-S Grat=NONE Exp=73.2 ObsDate=1999-12-01 PI=Murray Target=NGC 4038/NGC 4039 Download [y, n, q, a, h]: y ...
The instrument and grating flags can be used to restrict the set of matches, in which case the use of download=all may be appropriate; this downloads all the matching data without asking you for confirmation.
Example 8
unix% find_chandra_obsid 350.86 58.81 instrument=hrc
Here we restrict the search to just HRC observations.
Example 9
unix% find_chandra_obsid 350.86 58.81 radius=0
Here we restrict the search to those observations that overlap the given point, rather than any part of a circle about the point.
Example 10
unix% find_chandra_obsid 'cas a' grating=any
Here we find all the grating observation of Cas A.
Example 11
unix% find_chandra_obsid 12:0 0 radius=60 instrument=hrci grating=letg
The grating and instrument parameters can be combined to restrict, in this case, to HRC-I observations with the LETG, using a search of 1 degree about RA=12:0:0 and a Declination of 0.
Parameters
| name | type | def | min | max | units | reqd |
|---|---|---|---|---|---|---|
| arg | string | yes | ||||
| dec | string | yes | ||||
| radius | real | 1 | 0 | arcmin | ||
| download | string | none | ||||
| instrument | string | all | ||||
| grating | string | all | ||||
| detail | string | basic | ||||
| mirror | string | |||||
| verbose | integer | 1 | 0 | 5 |
Detailed Parameter Descriptions
Parameter=arg (string required)
RA, ObsId, or name of source
The Right Ascension (J2000) or name of the source.
Many common RA formats can be used, as shown below. Values including a space need to be surrounded by quotes.
- 12.3
- 12:14
- "12h 14m 3.2s"
If the Dec argument is empty than the value is taken to be wither be an ObsId (if an integer in the range 1 to 65535), or the name of the source and sent to the CADC name resolver. Set verbose to 2 to see the position that is returned.
Not all names can be resolved; for instance solar system objects.
Parameter=dec (string required)
Dec of source
The declination (J2000) of the source. If not given, or set to "", the first argument is taken to be the name or ObsId of the source.
Many common formats can be used, as shown below. Values including a space need to be surrounded by quotes or protetected in some way, depending on your shell:
- -34.2
- "-34 12"
- "-34d 12' 2.8"'"'
Parameter=radius (real default=1 min=0 units=arcmin)
Radius for search overlap in arcmin
The search radius around the source to look for overlap with any Chandra observation. A value of 0 means that the search location must lie within the "footprint" of a Chandra observation for it to be returned.
Parameter=download (string default=none)
What ObsIDs should be downloaded?
What should be done with matching ObsIDS?
| Value | Description |
|---|---|
| none | No data is downloaded. A list of matching observations is displayed to the screen (the detail parameter controls the level of detail). |
| ask | The user is asked whether each matching ObsID should be downloaded. |
| all | All matching ObsIDs are downloaded. Care should be taken here since this can result in a lot of data being downloaded from the archive. |
Note that there is no way to restrict the data being downloaded. If you only want a subset of files for each ObsID then use the download_chandra_obsid script once you have found the list of matching ObsID values.
Parameter=instrument (string default=all)
Choice of instrument
The search can be restricted to one or more instruments using this parameter:
| Setting | Instrument(s) |
|---|---|
| all | No instrument filter is applied. |
| acis | Only ACIS-I or ACIS-S data is returned. |
| hrc | Only HRC-I or HRC-S data is returned. |
| acisi | Only ACIS-I data is returned. |
| aciss | Only ACIS-S data is returned. |
| hrci | Only HRC-I data is returned. |
| hrcs | Only HRC-S data is returned. |
Parameter=grating (string default=all)
Choice of grating
The search can be restricted to one or more grating settings using this parameter:
| Setting | Grating(s) |
|---|---|
| all | No grating filter is applied. |
| none | Only observations with no grating are returned. |
| letg | Only LETG data is returned. |
| hetg | Only HETG data is returned. |
| any | Search for LETG or HETG observations. |
Parameter=detail (string default=basic)
Columns to display
This parameter controls the number of columns displayed when the download parameter is "none". The options are:
| Setting | Columns |
|---|---|
| basic | obsid, sepn, inst, grat, time, obsdate, piname, target |
| obsid | obsid |
| all | obsid, sepn, inst, grat, time, rastr, decstr, obsdate, piname, target, ra, dec |
and the description of the columns is given below:
| Column | Description |
|---|---|
| obsid | The Observation Id for the observation. |
| sepn | The separation, in arcminutes, between the aim point of the observation and the search location. |
| inst | The instrument used in the observation, one of ACIS-S, ACIS-I, HRC-S, or HRC-I. |
| grat | Thr grating used in the observation, one of NONE, LETG, or HETG. |
| time | The exposure time of the observation, in kiloseconds. |
| rastr | The RA of the aim point of the observation, using h:m:s format (J2000). |
| decstr | The Declination of the aim point of the observation, using d:m:s format (J2000). |
| obsdate | The date of the observation. When the detail level is basic then this contains just the day of the observation; the time is included when the detail level is all. |
| piname | The surname of the Principal Investigator for the observation. |
| target | The target name. |
| ra | The RA of the aim point of the observation, in decimal degrees. |
| dec | The Declination of the aim point of the observation, in decimal degrees. |
Parameter=mirror (string default=)
Use this instead of the CDA HTTPS site
Please contact the CXC HelpDesk if you want to use this functionality.
Parameter=verbose (integer default=1 min=0 max=5)
Verbose level
If set to 0 then there will be no screen output apart from error messages. The default setting of 1 is intended for most users; a value of 2 will display the position found for the name when the dec argument is empty. Higher levels are mainly useful for debugging (e.g. when reporting a problem to to the CXC HelpDesk).
Parameter handling
This script has a default mode setting of "h", rather than the usual "ql", so that you can say:
unix% find_chandra_obsid 234.568 -23.24 unix% find_chandra_obsid "1h 33m 50s" "30d 39' 40" unix% find_chandra_obsid m101
without having to be prompted for an declination (when using just a name), or having to clear out previous values. It does mean that it is an error to call the script without either a position or object name on the command line (i.e. you will not be prompted for these arguments).
Use pset if you wish to permanently set options, for instance to set instrument to acis to exclude HRC observations.
Changes in the scripts 4.15.1 (January 2023) release
Improved handling of non-ASCII PI names.
Changes in the scripts 4.14.1 (February 2022) release
The script is better able to cope with running on a system where the openssl library does not have access to SSL certificates.
Changes in the scripts 4.13.0 (December 2020) release
The script should be more robust to changes made to the Chandra Data Archive web site.
Changes in the scripts 4.11.2 (April 2019) release
Support running on some macOS/openSSL systems by catching CERTIFICATE_VERIFY_FAILED errors and falling through to curl or wget in these cases.
Changes in the scripts 4.10.3 (November 2018) release
Fall through to curl or wget for https access to the Chandra Data Archive.
Changes in the scripts 4.10.2 (May 2018) release
Updated to handle the move of the Chandra Footprint Service to a https URL. Unfortunately not all Python builds in the CIAO 4.10 release can handle SSL requests; in these cases the script will attempt to use curl and then wget to access the data. If you are having problems, run with verbose=3 and send the information to the CXC HelpDesk.
Changes in the scripts 4.9.3 (May 2017) release
Updated to use ftp://cda.cfa.harvard.edu as the default FTP server. Fixed the problem when download=ask is chosen when using Python 3.5.
Changes in the scripts 4.8.1 (December 2015) release
The code has been updated to avoid warning messages from NumPy version 1.9. There is no difference to how the script behaves.
Changes in the scripts 4.7.1 (December 2014) release
Support for searching by ObsId
If a single argument is given and it is an integer in the range 1 to 65535, then it is first checked against the Chandra Data Archive and, if it matches an existing ObsId, then its position is used, otherwise it is passed to the name server.
Changes in the scripts 4.5.4 (August 2013) release
Support for CDA mirror sites
The mirror parameter and support for the CDA_MIRROR_SITE environment variable has been added to allow data access from a mirror of the Chandra Data Archive site.
Screen output
A minor change to the screen output when no matches are found (the search position is now included in the message).
About Contributed Software
This script 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 - such as how to ensure that the parameter file is available.
Bugs
There are no known bugs for this tool.
See Also
- contrib
- cda_data, cda_search
- tools::download
- download_chandra_obsid, download_obsid_caldb, obsid_search_csc, search_csc
- tools::utilities
- splitobs