|
|
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 dmsyntax". 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.
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.
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 dmsyntax" 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
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.
dmcopy "bas.fits[stdevt][pha=20:30,grade>4]" tmp1.fits
dmcopy "bas.fits[stdevt][time=1522012:1522320,1522400:1522600]"
tmp2.fits
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.
dmcopy "input.fits[EVENTS][bin x=10:100:1,y=1:100:1]" image1.fits
option=image
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.
dmcopy "input.fits[events][bin pha=1:4096]" phaimage.fits
This bins an event list in input.fits to create a 1D PHA image:
(see the dmextract tool for binning it to an XSPEC compatible
PHA table file)
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.
Input virtual file
The CXC virtual file syntax is filename[qualifier][qualifier]....;
see `ahelp dmsyntax' for details.
Currently FITS and IRAF IMH format 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.
The output filename to be created.
The output file format type (FITS or IRAF IMH). Defaults
to the same as input.
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.
Verbose can be from 0 to 5, generating different
amounts of output.
If outfile already exists, clobber=yes will allow
you to overwrite it.
Support for IRAF QPOE files has been removed from CIAO.
- concept
-
subspace
- dm
-
dm,
dmbinning,
dmcols,
dmfiltering,
dmimages,
dmimfiltering,
dmintro,
dmopt,
dmsyntax
- tools
-
acis_detect_afterglow,
acis_find_hotpix,
acisspec,
destreak,
dmextract,
dmfilth,
dmgroup,
dmgroupreg,
dmimghist,
dmlist,
dmregrid,
dmstat,
fullgarf,
get_sky_limits,
lightcurve,
mkacisrmf,
mkarf,
mkexpmap,
mkgarf,
mkgrmf,
mkinstmap,
mkpsf,
mkrmf,
mkwarf,
tgextract
|
![[CIAO Logo]](../imgs/ciao_logo_navbar.gif){kind=logo}