Last modified: December 2022

URL: https://cxc.cfa.harvard.edu/ciao/ahelp/dmappend.html
AHELP for CIAO 4.15

dmappend

Context: Tools::Core

Synopsis

Append multiple blocks/extensions to an existing output file.

Syntax

dmappend infile outfile [verbose]

Description

The dmappend tool is a simple tool to append several related blocks/extensions to an existing output file.

Duplicate Block Names

A block cannot be appended if it has the same name as a block already in the file. To see block names, use 'dmlist filename blocks'. To workaround this limitation, rename the block before appending. The data model (DM) syntax can be used to rename the block "on the fly"; see "ahelp dm" for details.

GTIs from the Input File

When appending a block from one FITS file to another FITS file, the GTIs from the input file are applied to the output. To avoid this, e.g. if you are only appending a REGION block, use a subspace filter to ignore the input GTIs:

unix% dmcopy "evt2_repro.fits[@gti.fits]" evt2_new_gti.fits
unix% dmappend "evt2_repro.fits[region][subspace -time]" evt2_new_gti.fits

Examples

Example 1

dmappend "tmp.fits[region]" evt1a.fits

Takes the block called "region" in file tmp.fits and appends it to evt1a.fits. evt1a.fits must already exist.

Example 2

dmappend "acis*.fits" output.fits

Will find all files in the current directory with names that start with "acis" and end in ".fits" and will append the first `interesting' block (see the DM documentation) from each to separate blocks in the existing output.fits file. The block names of all input files and the initial output file should be all different.

Example 3

dmappend @data.lis output.fits

Will open the text file "data.lis" and append the blocks listed in the file to the existing output file, output.fits. If "data.lis" has two lines containing dmcontreg.fits and acisf01712N002_cntr_img2.fits, and output.fits is '273_109cnts_evt2.fits'; then this event file which originally had the GTI extensions and the event list will now contain also a region file and an image extension.


Parameters

name type ftype def min max reqd stacks
infile file input       yes yes
outfile file output       yes  
verbose integer   0 0 5    

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input stacks=yes)

Input file name(s).

CIAO stacks may be a single filename, a comma-delimited list of names, or '@' followed by the name of a text file containing one filename on each line. Each filename may use the full CIAO DM virtual file syntax.

For one or multiple input files, there should be only one single output file.

Parameter=outfile (file required filetype=output)

The output file name (must exist).

The output file name that must already exist. The input tables/images will be converted to format of the output file. Each input file will be appended as a separate extension/block.

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

display level(0-5)


Bugs

Caveats

Appending a region block may affect the output file GTIs  (28 Feb 2011)

When appending a region block from one FITS file to another FITS file, the GTIs from the input file are applied to the output. To avoid this, use a subspace filter to ignore the input GTIs:

unix% dmcopy "evt2_repro.fits[@gti.fits]" evt2_new_gti.fits
unix% dmappend "evt2_repro.fits[region][subspace -time]"  evt2_new_gti.fits

The output file, evt2_new_gti.fits, will contain the GTIs applied from the file gti.fits. The GTIs (time subspace) of the evt2_repro.fits file are ignored.

See Also

dm
dmfiltering, dmopt
tools
dmappend, dmcontour, dmellipse, dmfilth, dmgroup, dmgti, dmimg2jpg, dmimgadapt, dmimgblob, dmimgcalc, dmimgdist, dmimgfilt, dmimghist, dmimghull, dmimglasso, dmimgpick, dmimgpm, dmimgproject, dmimgreproject, dmimgthresh, dmjoin, dmmaskbin, dmmaskfill, dmmerge, dmnautilus, dmpaste, dmregrid, dmregrid2, dmsort, dmstat, dmtabfilt, dmtcalc, dmtype2split, evalpos, imgmoment, mean_energy_map, pileup_map