|
|
|
|
|
SynopsisFilter and bin tables and images. Syntaxdmcopy infile outfile [kernel] [option] [verbose] [clobber] Description`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:
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 1dmcopy "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 2dmcopy "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 Example 3dmcopy "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 4dmcopy "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. Example 5dmcopy "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. Example 6dmcopy "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) Example 7dmcopy "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. Parameters
Detailed Parameter DescriptionsParameter=infile (file required filetype=input)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. Parameter=outfile (file required filetype=output)The output filename to be created. Parameter=kernel (string default=default)The output file format type (FITS or IRAF IMH). Defaults to the same as input. Parameter=option (string)option=value (image/all/type)
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. BugsSee the bugs page for this tool on the CIAO website for an up-to-date listing of known bugs. See Also
|
 |
The Chandra X-Ray
Center (CXC) is operated for NASA by the Smithsonian Astrophysical Observatory. 60 Garden Street, Cambridge, MA 02138 USA. Email: cxcweb@head.cfa.harvard.edu Smithsonian Institution, Copyright © 1998-2004. All rights reserved. |
![[CIAO Logo]](../imgs/ciao_logo_navbar.gif){kind=logo}