Skip to the navigation links
Last modified: December 2009

AHELP for CIAO 4.2


Context: tools


Filter and bin tables and images.


dmcopy  infile outfile [kernel] [option] [verbose] [clobber]


dmcopy is a very general program which copies a `virtual file' (a table or image with a filter specification) to a physical disk file. For details of the virtual file syntax, see "ahelp dm". Some uses are:

  • Filtering tables. dmcopy selects rows and columns from a table, making an output file consisting of the filtered table.
  • Binning tables to an image. Select any n columns from a table, and make an n-dimensional binned image from them.
  • Filtering images, selecting subsets (spatial, temporal, energy, etc.) of an image.

When do you get a table as output and when do you get an image? If the input to dmcopy is an image, the output will be an image. If the input is a table and you use the "bin" or "opt image" commands or the "option=image" dmcopy parameter setting, you'll get an image as output. Otherwise, you'll get a table.

Example 1

dmcopy "bas.fits[stdevt]" out.fits

This copies the table STDEVT in dataset "bas.fits" to "out.fits". Note that use of the Unix command line requires quotes when the string has characters such as "[]" or "()" in it. In the Data Model (DM) paradigm, any GTI (Good Time Interval) table in bas.fits is also copied, as it contains information that's considered to be "part of" the event table.

Example 2

dmcopy "bas.fits[stdevt][time=5000:5200]" out.fits

This copies the table STDEVT in dataset "bas.fits" to "out.fits", including only those rows with times between 5000 and 5200. This assumes that STDEVT contains a column called TIME. We also copy along the Good Time Intervals table, if present, and update it by intersecting with our time filter. If present, ONTIME, LIVETIME and EXPOSURE keywords are also updated.

Note that if the STDEVT table (or "block") was the "first interesting block" in the file - see "ahelp dm" for more information on what "interesting" means to the Data Model - then the example could have been written as:

dmcopy "bas.fits[time=5000:5200]" out.fits

Example 3

dmcopy "bas.fits[stdevt][time=5000:5200]" out.fits option=all

The use of the "option=all" command in dmcopy forces any other tables or images in the bas.fits dataset to be copied over along with the table you are filtering. For instance, a ROSAT FITS event file may have a STDQLM table, among others. The default behaviour of dmcopy is to drop such extra tables during a copy, but option=all ensures they are carried along.

Example 4

dmcopy input.fits "output.txt[opt kernel=text/simple]"

Copying a FITS file to a simple text output file that may be used by other code; see "ahelp dmascii" for more information on working with ASCII files.

Example 5

dmcopy input.txt output.fits

Create a FITS file from a text file; see "ahelp dmascii" for more information on working with ASCII files.

Example 6

dmcopy "data.txt[time=100:200][opt sep=@]" "filtered.out[opt

Copy the filtered input data to the output file, changing the separator character from "@" to "&". The output could then be used to create a table in LaTeX. See "ahelp dmascii" for more information on working with ASCII files.

Example 7

dmcopy "bas.fits[stdevt][pha=20:30,grade>4]" tmp1.fits
dmcopy "bas.fits[stdevt][time=1522012:1522320,1522400:1522600]"
dmcopy "bas.fits[stdevt][(x,y)=circle(3001.2,4982.3,14.5)]" tmp3.fits
dmcopy "bas.fits[stdevt][sky=circle(3001.2,4982.3,14.5)]" tmp3.fits
dmcopy "evt.fits[events][#row=10:13]" evt_row10-13.fits
dmcopy "acis.fits[events][status=10x1x10]" tmp3.fits
dmcopy "region.fits[2][shape=point]" tmp3.fits

These examples filter the same table selecting only some events. (You can use the dmlist tool to find out what columns are available for filtering). Filtering by row number is done as shown in the fifth example. Filtering on bit type columns is also allowed (using a bit string of ones and zeros with 'x' used as a wild card) and on string type columns - see the last two examples above.

Example 8

dmcopy "input.fits[EVENTS][bin x=10:100:1,y=1:100:1]" image1.fits

This bins an event list in input.fits to create an image in "image1.fits". The qualifier [bin x=10:100:1, y=1:100:1] selects a subset of the image with no blocking. To "block" the image, use e.g. [bin x=10:100:2,y=1:100:2], giving an image each of whose pixels corresponds to 4 pixels in the original image.

Example 9

dmcopy "image.fits[200:512,128:500]" image3.fits

This copies only that part of the image for which the first axis pixel number lies between 200 and 512 and the second axis pixel number is between 128 and 500.


name type ftype def min max reqd
infile file input       yes
outfile file output       yes
kernel string   default      
option string          
verbose integer   0 0 5  
clobber boolean   no      

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input)

Input virtual file

The CXC virtual file syntax is filename[qualifier][qualifier]....; see "ahelp dm" for details.

FITS table and image files are supported. If the virtual file is not well defined, the program gives an error message and exits. Qualifiers that can be used to filter the input file are:

[block]: the block part of the syntax is the table/image name (for FITS, HDU name or 1-based HDU number). You can omit the [block], in which case the first `interesting' block is used: in the case of FITS, null primary headers and good time intervals are ignored.

filter - is a list specifying ranges of column values to accept, filtering out rows of a table or portions of an image. In the case of an image, where the axes may be unnamed, the 'name=' can be omitted and the ranges are assumed to be in order of the axes.

cols - specifies the names of columns to include, when selecting from a table.

bin - is a sequence defining table columns to bin to create an image file.

newblock - is a name for the resulting block; if omitted, the name of the input block is used.

Parameter=outfile (file required filetype=output)

The output filename to be created.

Parameter=kernel (string default=default)

The output file format type. Defaults to the same as input.

Parameter=option (string)

option=value (image/all/type)

  • option = all, Copies all blocks in the input file, not just the one you are filtering. The other blocks are copied without change. However, GTIs are treated specially.
  • option = image, Forces the virtual file to be interpreted as an image, even if the input is a table and there is no [bin] element in the specification.
  • option = "type=i4", used with binning tables to images. Forces the type of the resulting image to be 4-byte integer. "type=i2" (2-byte integer, which is the default anyway) and "type=r4" (4-byte real) are also supported. This option is now supported within the virtual file syntax itself, e.g. dmcopy "file.fits[bin sky=4][option type=i4]", and is provided here for back compatibility. Note that this option does not work when copying images to images, and so cannot be used to change the type of an existing image.

Parameter=verbose (integer default=0 min=0 max=5)

Verbose can be from 0 to 5, generating different amounts of output.

Parameter=clobber (boolean default=no)

If outfile already exists, clobber=yes will allow you to overwrite it.


See the bugs page for this tool on the CIAO website for an up-to-date listing of known bugs.

See Also

dm, dmascii, dmbinning, dmfiltering, dmopt
lc_clean, lc_sigma_clip, lightcurves
lc_clean, lc_sigma_clip, lightcurves
acis_detect_afterglow, acis_find_hotpix, acis_streak_map, acisreadcorr, deflare, destreak, dmcoords, dmextract, dmfilth, dmgroup, dmimghist, dmlist, dmregrid, dmstat, get_sky_limits, tgextract, tgextract2

Last modified: December 2009