Last modified: December 2022

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

dmjoin

Context: Tools::Table

Synopsis

Join two files whose sampling is different.

Syntax

dmjoin infile joinfile outfile join [interpolate] [verbose] [clobber]

Description

The dmjoin program allows you to perform interpolations on tables which have a common column.

Suppose you have a file asol.fits which gives the aspect solution as a function of time, sampled on a specific time interval, and a set of photon events whose times are arbitrary. dmjoin allows you to generate a version of the aspect solution with one record per photon, interpolated to the times of those photons.

Another example would be a table linking photometric color BV_COL to stellar effective temperature TE, together with a star catalog containing values of BV_COL for each star. The program will generate the corresponding TE values for each star.

NB: Interpolating has been generalized to offer more options than a simple linear interpolation. These other options are selected by setting the parameter 'interpolate' to a non-default value (see the parameter section).


Examples

Example 1

dmjoin evt.fits "asol.fits[cols ra,dec,roll,time]" evt_join.fits
join=time

The column "time" is present in both evt.fits and the virtual file "asol.fits[cols ra,dec,roll,time]". In the latter, time is monotonic, so we can interpolate. The output file evt_join.fits will be a copy of evt.fits with the columns ra,dec,roll added to it. The values of ra,dec,roll in the output file will be determined by using the value of time in evt.fits and interpolating in the asol.fits file to calculate the values of ra,dec and roll.

Example 2

dmjoin "evt.fits[cols time]" asol.fits asol_join.fits join=TIME

Makes a version of the aspect file evaluated only at the times of photons in the event file. Since the (virtual) event file has only one column, time, and this is the join column, the output has exactly the same column structure as the asol.fits file - except that the TIME column will be the first one in the file.

Example 3

dmjoin "catalog.fits" "color_table.fits[cols BV_COL,TE]" join=BV_COL
outfile=catalog_with_te.fits

Make a version of the catalog with a derived column TE generated from the lookup table color_table.fits which gives the function TE(BV_COL).


Parameters

name type ftype def min max reqd
infile file input       yes
joinfile file input        
outfile file output       yes
join string          
interpolate string   linear      
verbose integer   0 0 5  
clobber boolean   no      

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input)

Input virtual file

Input virtual file used as a basis for the output file. Must contain the join column; need not be sorted.

Parameter=joinfile (file filetype=input)

Input virtual join file or stack of files.

Must contain the join column and at least one other column. Must be monotonically sorted on the join column.

Parameter=outfile (file required filetype=output)

The output file, with the interpolated column. The output file is a copy of the input virtual file, but with the columns from the join file appended and interpolated.

Parameter=join (string)

Name of join column.

The name of the common column in the join file and input file.

Parameter=interpolate (string default=linear)

Interpolation method

There are several methods of selecting values of the entries in the new column(s), based on the relevent values in the join column.

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

Controls screen output information, value is 0 (no info) to 5 (most info).

Parameter=clobber (boolean default=no)

Clobber output if it exists? (yes/no)


Bugs

There are no known bugs for this tool.

See Also

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