Description

The data model (DM) is a library which lets our software access a variety of file formats and to describe filtered subsections of those files. For the user, the most obvious interaction with the DM is the virtual-file syntax which allows you to filter and bin the files.

All of the CXC tools support the DM virtual file syntax. This means that whenever you are prompted for a filename, you can instead enter a filename qualified by a set of restrictions that implicitly define a filtered table or image.

All of the qualifiers are optional.

• "dataset" is the filename (for the IRAF kernel, it may also be a directory containing multiple imh files; for the FITS kernel, it is any file or pseudo-file handled by CFITSIO).
• [block] is the name of the image or table. For FITS files, the block corresponds to an HDU and may be identified by name or number. The block name is created by concatenating the EXTNAME and EXTVER keywords (if EXTVER is other than 1). If omitted, the `first interesting block' is picked; in the case of an event file, this is usually the events block. If you're not sure what the block name or number is, use the "dmlist filename blocks" command to list the blocks in the file. Note that blocks are numbered from 1 to N (as in CFITSIO's subroutine API, but different from the FTOOLS user level convention of counting from 0).
• [filter-command] defines which rows of the table, or portions of an image, to accept. For a table, a simple filter command is [filter name=min:max,min:max,min:max....] giving a set of ranges for a particular column. See `ahelp dmfiltering' and `ahelp dmimfiltering' for the full syntax.
• [bin] is a sequence (eg [bin name=min:max:step,name=min:max:step,..] or [bin name=step,...]) defining table columns to bin to create an image file. See `ahelp dmbinning' for the full syntax.
• [cols-command] is a sequence (eg [cols name,name,name]) where the names are names of columns to include. Alternatively, [cols -name,-name] excludes a set of columns. See `ahelp dmcols' for the full syntax.
• [opt-command] is a sequence (eg [opt option-list]) describing special options for the DM library. See 'ahelp dmopt'.
• [rename] is a name for the new block. If omitted, the default name of the output block is just the name of the original block, except if you are binning a table to an image when the string _IMAGE is appended. Example: "evt1.fits[events][energy=1000:2000][bin x=1:1024:2,y=1:1024:2]" creates an image block called EVENTS_IMAGE, but "evt1.fits[events][energy=1000:2000][bin x=1:1024:2,y=1:1024:2][softimg]" creates an image block called SOFTIMG.