dmopt

Context: dm

Synopsis

Controlling Data Model internal options

Syntax

[opt type={value}]
[opt null={value}]
[opt mem={value}]
[opt full]
[opt update=no]
[opt scale=no]
[opt kernel={value}]

Description

The "[opt]" qualifier allows the user to supply special options to the Data Model by including them in the filtering syntax. For information on the DM filtering syntax, refer to "ahelp dm".

[opt type={value}]

This option, used when binning a table to an image, forces the output data type. Supported values are i2,i4,r4,r8 for 2 and 4 byte integers and 4 and 8 byte reals. The default value is i2.

[opt null={value}]

An image array is by definition rectangular, but we often want to make an image including only data from, e.g., a circular region. The pixels in the output image outside the circle are not valid.When copying an image through a filter, or binning a table to an image, this option controls the value of pixels which lie outside the filtered area. The default behaviour is to set these pixels to zero; [opt null=...] sets them to a specified value, which of course must be of the same data type as the output image.

The special value "NaN" is supported, but is only valid if the output image is of real data type:

dmcopy "evt.fits[sky=circle(4096,4096,200)][bin sky][opt
null=NaN,type=r4]" nan.img

[opt mem={value}]

Set the maximum memory used for a virtual image, in megabytes. The DM has an internal default limit on the size of a binning operation; this prevents users from accidentally commanding the DM to create a many-gigabyte image on a machine which only has a hundred megs of memory. If you really want to create a big image, you use this option to override the internal default. For example:

dmcopy "evt.fits[bin sky=4][opt mem=100]" big.img

[opt full]

Binning a filtered table to an image will by default select the smallest image size that can contain the filtered data. Thus

dmcopy "evt.fits[sky=circle(4000,4000,100)][bin sky]" circ.img

is equivalent to

dmcopy "evt.fits[sky=circle(4000,4000,100)][bin
x=3900:4100,y=3900:4100]" circ.img

rather than the full field image created by

dmcopy "evt.fits[sky=circle(4000,4000,100)][bin
x=0.5:8192.5,y=0.5:8192.5]" circbig.img

If you explicitly want to retain the full field even though most of it will be empty (with values set by the [opt null=value] command)

dmcopy "evt.fits[sky=circle(4000,4000,100)][bin sky][opt full]"
circbig.img

[opt update=no]

For complicated filters, especially exclude filters, the process of updating the data subspace may be long and not very helpful. The update=no option suppresses recording of the current filter:

dmcopy "evt.fits[sky=region(nasty.reg)][opt update=no]" nasty.fits

[opt scale=no]

The default behavior in the current DM release is to automatically apply internal (BSCALE/TSCAL) scaling for FITS files. This option turns off the scaling, allowing access to the raw values.

When using this option for images, a 4-byte real datatype is returned, even if the original unscaled data is integer. Use (e.g.) [opt scale=no,type=i2] to force the result to the desired type.

[opt kernel={value}]

The CXC datamodel supports most FITS files, including binary and ASCII tables, as well as various types of ASCII files.

The kernel parameter can be used either on input or on output. On input, it can be used to override the automatic detection of different ASCII file formats by explicitying setting the column separator or entire file type. A common example is when working with Tab Separated Value format files:

dmlist "csc_output.tsv[opt kernel=text/tsv]" cols

If part of the output virtual file specification, it is used to force the application to write the output in the specified format, for example:

dmcopy "evt.fits[cols time]" "times.dat[opt kernel=text/simple]"

Will write the TIME column values into an ASCII file using the text/simple format.

The default kernel is "FITS".

Bugs

See the bugs page for the Data Model library on the CIAO website for an up-to-date listing of known bugs.

Refer to the CIAO bug pages for an up-to-date listing of known issues.