Synopsis
List contents or structure of a file.
Syntax
dmlist infile opt [outfile] [rows] [cells] [verbose]
Description
dmlist dumps the contents or header of a file or block (a block is a subfile or FITS extension) to ASCII in an organized way. It corresponds to the FTOOLS fdump and fstruct programs, but interprets the input file at a higher level. All CXC data model formats are supported (see "ahelp dm" for more information on the CXC Data Model).
dmlist uses a comma-delimited list of options to select which information is displayed. Options indicate both what sections of a file are to be displayed (blocks, keys, comments, cols, subspace, data, header, struct, full) and in what format (array, all, clean, raw). See below for a detailed description of the `opt' paramter.
Selected rows of data may be dumped: rows=min:max
Examples
Example 1
dmlist acis.fits data outfile=acis.ascii
List the data values in the 'most likely block' (since a specific one has not been indicated) of the input FITS binary table file "acis.fits" and write the output to the ascii file "acis.ascii". The 'most likely block' is generally [EVENTS] in a Chandra event list (i.e. equivalent to writing acis.fits[events])
Example 2
dmlist acis.fits full,all | more
List everything dmlist can tell you about the file and display the output using the unix command "more".
Example 3
dmlist "input.txt[time=100:1000,energy=10:20]" data
Filter a text file on time and energy, printing the filtered data to the screen.
Example 4
dmlist acis.fits opt=blocks
See what blocks are in the file "acis.fits". (Since opt is a positional parameter, 'opt=' can be omitted, i.e. `dmlist acis.fits blocks' works as well).
Example 5
dmlist "acis.fits[2]" opt=cols
See what columns are in the second block (note that block count starts at 1).
Example 6
dmlist "acis.fits[events]" opt=header,subspace
Look at the header and the data subspace for the block called "events" in the file. Blocks can be chosen either by name or by number. If a block is not specified, the program guesses the 'most likely block' to be used.
Example 7
dmlist "acis.fits[events][pha=20:30]" opt=data rows=100:104
Look at rows 100 to 104 of the virtual file filtered to show only pulse heights between 20 and 30. Note the row numbers are those passing the filter, not the original row numbers of the underlying file.
Example 8
dmlist "acis_evt2.fits[sky=region(3c273.reg)]" counts
Find the number of counts included in the region defined in 3c273.reg. The same command could also be written with the filter defined on the command line:
dmlist "acis_evt2.fits[sky=rotbox(4148,4044,8,22,44.5)]" counts
Example 9
dmlist "pha2.fits[cols channel,counts]" opt=array rows=3:3
Look at the channel and counts arrays for row 3 of the file, displayed in `array' (vertical) format.
Example 10
dmlist "acis.fits[events]" opt=header,raw verbose=0
Look at the FITS header instead of the DM-level header (the 'raw' option specifies use of the low level interpretation) and generate a minimal, `bare' version of the output (verbose = 0).
Example 11
dmlist "rmf.fits[cols MATRIX]" opt=data rows=1:3 cells=1:3
Look at the values in the first 3 cells of the array column MATRIX for the first 3 rows in the file.
Example 12
dmlist @evt.lis counts
Return the number of rows in each file listed in 'evt.lis'
Parameters
| name | type | ftype | def | min | max | reqd | stacks |
|---|---|---|---|---|---|---|---|
| infile | string | input | yes | yes | |||
| opt | string | data | yes | ||||
| outfile | string | output | no | ||||
| rows | string | no | |||||
| cells | string | no | |||||
| verbose | integer | 0 | 0 | 5 | no |
Detailed Parameter Descriptions
Parameter=infile (string required filetype=input stacks=yes)
The input virtual file specification (see "ahelp dm" for more information and detailed examples).
Parameter=opt (string required default=data)
The list of options, separated by commas.
This required parameter can be one or more of the following:
Blocks - Summarize all the blocks (images or tables) in the file, one line per block.
Keys - List the CXC Data Model (ASCDM) header keys for the selected block. Remember that not all the FITS keywords in a FITS file will be included - the ones like EXTNAME and CRPIX that have a special meaning for the structure of the file don't count as CXC Data Model keys, their values show up in other places (e.g. the output from cols). With this option, the comment and history records are suppressed. To see the low level list of all raw FITS header keywords in a FITS file, use opt=header,raw.
Comments - List the ASCDM comment keys for the block. For a FITS file, these keys are the COMMENT and HISTORY keywords.
Cols - List the ASCDM columns for the selected block. Shows `vector columns' like (X,Y) as pairs. This output shows the names of the variables you can filter a table on and what their valid ranges are. If the block is an image, it gives you one column with the name of the image (images are interpreted as a table with a single row and column).
Subspace - Summarizes the data subspace for the block. This describes the filters that have been applied to the data, either by the user or in processing.
Data - Prints the data segment. The cells parameter controls how much of an array column gets printed. By default, the data is printed in an `ornate' format showing arrays grouped in parentheses etc. If you use "Clean" option as well, the output is in a simpler format suitable for reading by other analysis programs. The output format for image data is currenlty not well supported.
Counts - Returns the number of events in the file. If a filter is applied (row numbers, sky region, etc.), the counts in the filtered region are printed to the screen. If a non-event file is given (e.g. PI spectrum or RMF file), the number of rows in the file is returned.
Header - Equivalent to Keys,Comments. List both DM level header keys and comment/history records. - List the ASCDM header keys for the selected block. Remember that not all the FITS keywords in a FITS file will be included - the ones like EXTNAME and CRPIX that have a special meaning for the structure of the file don't count as ASCDM keys, their values show up in other places (e.g. the output from cols). To see the low level list of raw FITS header keywords in a FITS file, use opt=header,raw.
Struct - Equivalent to 'header,cols,subspace'
Full - Equivalent to 'blocks,header,cols,subspace,data'
Array - Prints the data segment, but with arrays printed vertically. The cells parameter controls how much of an array column gets printed.
All - Print the info selected by the other options for all the blocks in the dataset.
Clean - When used in conjunction with the Array or Data options, produces stripped down output suitable for parsing by other programs.
Raw - Provides a lower level view of the header. 'header,raw' lists the raw FITS header keywords, not just the data model keywords. The old 'data,raw' functionality is now provided by 'data,clean'.
Parameter=outfile (string not required filetype=output)
The output ASCII file to be created, if any.
The output ASCII file to be created; output is sent to the screen if this parameter is blank.
Parameter=rows (string not required default=)
Range of table rows to print (min:max)
rows=30:40 Print row 30 to row 40 rows=40 Print row 1 to 40 rows=40:40 Print only row 40 rows=" " Print all rows (this is the DEFAULT) rows=-1 Print all rows
Parameter=cells (string not required)
Range of array indices to print in array columns and in images.
This parameter allows to select a range of array indices to print in array columns and in images. Examples: cells = 1:8 Print only array elements 1 to 8 of each array cells = all Print all array elements.
Parameter=verbose (integer not required default=0 min=0 max=5)
Controls amount of information to print (0-5).
The verbose parameter provides debugging information; verbose = 0 is usually fine.
Changes in CIAO 4.16
-
Fixed issue when listing contents of a file which contains vector columns of either strings or booleans data type.
Bugs
There are no known bugs for this tool.