Chandra X-Ray Observatory
Skip to the navigation links
Last modified: October 2013

AHELP for CIAO 4.9


Context: tools


List the LaTeX dataset identifier macros for a set of files.


list_datasetid [--detail=level] file1 file2 ...
list_datasetid [-dlevel] file1 file2 ...


list_datasetid will examine the headers of a set of files and will provide a list of LaTeX dataset identifier macros.

The CXC encourages users to make use of Dataset Identifiers when publishing in AAS-managed publications. This allows the publisher, through agreement with the Chandra Data Archive as well as other archives, to provide links to the actual datasets within their document. This makes it easier for ones colleagues and peers to locate the data being reported on in the manuscript.

Chandra data products, including those produced for the Chandra Source Catalog, include the standard DS_IDENT keyword that identifies the dataset. The list_datasetid script will search through all the extensions of the input files for this keyword. If the keyword is not found and the data is a Chandra dataset, it will try to locate the OBS_ID to construct the DS_IDENT value. Otherwise, the file is simply skipped.

The file names listed may also be CIAO stacks (See ahelp stack). Also normal file system wild cards are accepted. Directories are simply skipped.

The macro includes two parts: the dataset identifier and an optional anchor text. Depending on the detail level selected, the anchor text will contain information about the observation such as the instrument, gratings, observation ID, exposure time, and observation date. The --detail flag (-d) can be used to control the amount of detail that is returned.

Example 1

unix% list_datasetid *.fits

This will examine the headers of all the files whose name ends in ".fits" in the current directory. In a directory where there are multiple data products (in this example data for NGC 4649), the output will look something like:

The following dataset identifiers were found:
  \dataset[ADS/Sa.CXO#obs/00785]{Chandra ACIS ObsId 785}
  \dataset[ADS/Sa.CXO#obs/08046]{Chandra ACIS ObsId 8046}
  \dataset[ADS/Sa.CXO#obs/08182]{Chandra ACIS ObsId 8182}
  \dataset[ADS/Sa.CXO#obs/08507]{Chandra ACIS ObsId 8507}
  \dataset[ADS/Sa.CXO#obs/12975]{Chandra ACIS ObsId 12975}
  \dataset[ADS/Sa.CXO#obs/12976]{Chandra ACIS ObsId 12976}
  \dataset[ADS/Sa.CXO#obs/14328]{Chandra ACIS ObsId 14328}

The output is printed to the screen and includes 1 row for each unique dataset identifier. The default anchor text includes the detector and grating (if one was used) along with the the observation ID.

Example 2

unix% list_datasetid --detail=0 *evt2.fits

In this example we have restricted our search to just the event file and changed the level of detail to 0. Now the output looks like

The following dataset identifiers were found:

Example 3

unix% /bin/ls *evt2.fits > evt.lis
unix% list_datasetid -d3 @evt.lis

In this example we make use of CIAO stacks to store the list of file names we wish to examine. We also change the detail level to '3' which provides a verbose summary of the observations:

The following dataset identifiers were found:
 \dataset[ADS/Sa.CXO#obs/00785]{Chandra ACIS observation number 785 of NGC 4649 taken in VFAINT/TIMED/FULLFRAME mode on 2000-04-20 for 38.6 ksec by PI Dr. Craig Sarazin}
  \dataset[ADS/Sa.CXO#obs/08046]{Chandra ACIS observation number 8046 of 1938 taken in FAINT/TIMED/FULLFRAME mode on 2008-02-29 for 5.7 ksec by PI Prof Tommaso Treu}
  \dataset[ADS/Sa.CXO#obs/08182]{Chandra ACIS observation number 8182 of NGC 4649 taken in VFAINT/TIMED/FULLFRAME mode on 2007-01-30 for 52.8 ksec by PI Dr Philip Humphrey}
  \dataset[ADS/Sa.CXO#obs/08507]{Chandra ACIS observation number 8507 of NGC 4649 taken in VFAINT/TIMED/FULLFRAME mode on 2007-02-01 for 18.0 ksec by PI Dr Philip Humphrey}
  \dataset[ADS/Sa.CXO#obs/12975]{Chandra ACIS observation number 12975 of NGC 4649 taken in VFAINT/TIMED/FULLFRAME mode on 2011-08-08 for 85.4 ksec by PI Dr Giuseppina Fabbiano}
  \dataset[ADS/Sa.CXO#obs/12976]{Chandra ACIS observation number 12976 of NGC 4649 taken in VFAINT/TIMED/FULLFRAME mode on 2011-02-24 for 101.5 ksec by PI Dr Giuseppina Fabbiano}
  \dataset[ADS/Sa.CXO#obs/14328]{Chandra ACIS observation number 14328 of NGC 4649 taken in VFAINT/TIMED/FULLFRAME mode on 2011-08-12 for 14.4 ksec by PI Dr Giuseppina Fabbiano}


name type ftype def min max reqd stacks
file file input       yes yes
detail integer   1 0 3 no  

Detailed Parameter Descriptions

Parameter=file (file required filetype=input stacks=yes)

Input file names to search for dataset information

The list of file names to check for dataset identifiers. This may be a list of individual file names, a UNIX wild-card type expression, or a CIAO stack. Examples include:

my1_evt.fits my2_evt.fits my3_evt.fits
*.fits *pha 
@myevt.lis @myrmf.lis *arf.fits

If no file name is specified, the tool will look for *.fits *.fits.gz.

For FITS files, each extension is searched for the DS_IDENT or DS_ID[0-9][0-9][0-9] keywords. If the keyword cannot be found, and it is a Chandra dataset with a valid OBS_ID value, then the DS_IDENT value is constructed.

Only unique dataset identifier macros are reported. When the same DS_IDENT value is found (or constructed) it will only be reported once.

Non Chandra Data

The list_datasetid tool will attempt to look for the DS_IDENT keyword (and all the related DS_IDxxx variants) regardless of its origin. However, when reporting on the details (see below) the information collected from the header to construct the anchor text may not be available from other missions, so the anchor text may be sparsely populated (if at all).

Parameter=detail (integer not required default=1 min=0 max=3)

Amount of detail to include in the AnchorText

Level Information
0 None
2 Detector[/Grating] OBS_ID
3 Telescope/Detector/Grating ObsId/Obi/Cycle Object Readmode/Datamode/Subarray Date/ExpTime Observer

Special Characters in LaTeX

The macros automatically generated by list_datasetid could possibly include characters that LaTeX may require to be escaped or have special formatting rules applied. Users should consult their LaTeX manual if they include one of these macros and it causes a formatting error.


There are no known bugs for this tool.

See Also

cda_data, cda_search
download_chandra_obsid, download_obsid_caldb, find_chandra_obsid, obsid_search_csc, search_csc, splitobs

Last modified: October 2013
Smithsonian Institute Smithsonian Institute

The Chandra X-Ray Center (CXC) is operated for NASA by the Smithsonian Astrophysical Observatory. 60 Garden Street, Cambridge, MA 02138 USA.   Email: Smithsonian Institution, Copyright © 1998-2017. All rights reserved.