find_chandra_obsid

Synopsis

Find, and optionally download, publicly-available Chandra ObsIds from the Chandra archive.

find_chandra_obsid  arg dec [radius] [download] [instrument] [grating]
[detail] [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.

Object names

When called with just one argument, this is taken to be an object name and the name resolver at the CADC is used to convert it 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.

Example 1

unix% find_chandra_obsid 350.86 58.81

Find all the publicly-available Chandra observations that overlap the circle with a center at RA of 350.86 degrees and Declination of 58.81 degrees, and a radius of 1 arcminute.

Example 2

unix% find_chandra_obsid 12:15:46 -2:0:4

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 15 46" "-2 0 4"
unix% find_chandra_obsid "12h 15m 46s" "-2d 0' 4"'"'

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 3

unix% find_chandra_obsid 'cas a'

Object names can be used instead; if the name contains a space then surround the name in single or double quotes. The first argument is taken to be a name if the dec argument is not given or empty.

Setting the verbose value to 2, or higher, displays the coordinates returned by by the name resolver; for instance

unix% find_chandra_obsid 'cas a' verbose=2
Querying name resolvers for name=cas a
Found ra=350.85 dec=58.815
    = 23h 23m 24.0s 58d 48' 54.0"
...

Example 4

unix% find_chandra_obsid 350.86 58.81 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 5

unix% find_chandra_obsid 350.86 58.81 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 115 matching observations:

  1/115: Obsid=114 Sepn=0.5 Inst=ACIS-S Grat=NONE Exp=50.6 ObsDate=2000-01-30
     PI=HOLT Target=CAS A
  2/115: Obsid=171 Sepn=0.3 Inst=HRC-I Grat=NONE Exp=9.1 ObsDate=1999-09-03
     PI=Calibration Target=CAS A [HRC-I, Offsets=0,0,0]
...
115/115: Obsid=5320 Sepn=0.5 Inst=ACIS-S Grat=NONE Exp=55.1 ObsDate=2004-05-05
     PI=Hwang Target=Cassiopeia A

Use h to get help on the download options.

  1/115: Obsid=114 Sepn=0.5 Inst=ACIS-S Grat=NONE Exp=50.6 ObsDate=2000-01-30
     PI=HOLT Target=CAS A

Download [y, n, q, a, h]: n

  2/115: Obsid=171 Sepn=0.3 Inst=HRC-I Grat=NONE Exp=9.1 ObsDate=1999-09-03
     PI=Calibration Target=CAS A [HRC-I, Offsets=0,0,0]

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 6

unix% find_chandra_obsid 350.86 58.81 instrument=hrc

Here we restrict the search to just HRC observations.

Example 7

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 8

unix% find_chandra_obsid 'cas a' grating=any

Here we find all the grating observation of Cas A.

Example 9

unix% find_chandra_obsid 12:0 0 radius=3600 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

Detailed Parameter Descriptions

Parameter=arg (string required)

RA 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 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 of a 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?

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:

Parameter=grating (string default=all)

Choice of grating

The search can be restricted to one or more grating settings using this parameter:

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:

and the description of the columns is given below:

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.

Notes

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 the installation instructions page for help on installing the package.