Last modified: December 2013

URL: http://cxc.harvard.edu/ciao/ahelp/dmpaste.html
AHELP for CIAO 4.11

dmpaste

Context: tools

Synopsis

Add new columns to a table.

Syntax

dmpaste infile pastefile outfile [clobber] [verbose]

Description

`dmpaste' copies infile to outfile, pasting on extra columns from the pastefile, which may be a single file or a stack of files. Column names in the pastefile cannot duplicate names in the input file. All files must have the same number of rows. Analogous to the unix `paste' command.


Examples

Example 1

dmpaste "data1.fits[EVENTS]" "data2.fits[EVENTS][cols tg_r,tg_d]"
data3.fits

This pastes extra columns tg_r, tg_d from data2.fits onto the columns already present in data1.fits, making a new file data3.fits.

Example 2

dmpaste "data1.fits[EVENTS]" data2.fits data3.fits

This pastes all the columns from data2.fits onto the data1.fits table.

Example 3

dmpaste "data1.fits[EVENTS][cols -pha]" "data2.fits[EVENTS][cols pha]"
data3.fits

Replace the pha column in data1.fits by the one in data2.fits.


Parameters

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

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input)

Input file name

The input file used as the basis for the new file. The output file will contain all columns from the input file and the header from the input file.

Parameter=pastefile (file required filetype=input)

Input paste file list

All the columns in pastefile will be pasted on to infile. If pastefile is a stack, the columns from all the files in the stack will be used.

Parameter=outfile (file required filetype=output)

output file name.

The output file containing a version of infile with the extra columns appended.

Parameter=clobber (boolean default=no)

Clobber exisiting files?

Used to specify whether to clobber output file if it already exists.

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

Amount of diagnostic chatter, 0 (least) to 5 (most).


Bugs

dmpaste creates invalid output file if the pastefile contains the same vector columns as the infile with a different vector name.

If the infile and pastefile contain the same vector columns with different vector names, dmpaste will end up creating an invalid output file. For example

%  dmlist evt.fits cols
...
   5   chip(chipx,chipy)    pixel        Int2           1:1024               Chip coords
...

% dmcopy evt.fits"[cols new=chip]" newchip.fits clob+
% dmpaste evt.fits newchip.fits junk.fits clob+
% dmlist junk.fits cols
...
  17   (chipx,chipy)(chipx,chipy) pixel        Int2           1:1024               Chip coords

Since the vector column name is invalid, the data are inaccessible.

If the vector name is the same then dmpaste errors out

% dmcopy evt.fits"[cols chip]" chip.fits clob+
% dmpaste evt.fits chip.fits junk.fits clob+
# dmpaste (CIAO): Skipping duplicate column name="chip" in files chip.fits.

Workaround:

As a work-around, users must rename the individual vector column names.

% dmcopy evt.fits"[cols new=chip,new_x=chipx,new_y=chipy]" newchip.fits clob+
% dmpaste evt.fits newchip.fits works.fits clob+
% dmlist works.fits cols
...
  17   new(new_x,new_y)     pixel        Int2           1:1024               Chip coords
dmpaste does not handle all vector columns correctly.  (07 Mar 2008)

The tool gets the range for the first component of the vector column (e.g. chipx=1:4096). When creating the output file, it uses this value for the entire chip column range instead of setting the range for each component of the vector separately. Since the chipy range is very different from the chipx range, subsequent filtering selects no events in the range for any filter.

See Also

dm
dmfiltering, dmopt
tools
dmappend, dmgroup, dmgti, dmjoin, dmmerge, dmsort, dmtabfilt, dmtcalc, dmtype2split