Last modified: December 2023

URL: https://cxc.cfa.harvard.edu/ciao/ahelp/dmtabfilt.html
AHELP for CIAO 4.16

dmtabfilt

Context: Tools::Table

Synopsis

Apply non-linear filters to columns in table

Syntax

dmtabfilt  infile colname outfile function mask [clobber] [verbose]

Description

`dmtabfilt' applies one of several different mask-based non-linear filters to the column values in a table. The filters allow for tasks such as median filtering and determining the range of values.

The list of available filters can be found in ahelp dmimgfilt. However, the following filters are not supported for tables: locheq, kuwahara, and mcv.

The mask selects which rows to include in the filter. It is a simple string which represents the rows adjacent to the current row as data are being processed. For example mask="111" will use the value at the current row, the row before and the row after it; where mask="011" will only use data in the current and next rows. The mask can be arbitrarily long.

NULL values and NaN values are always excluded from the filters.


Examples

Example 1

dmtabfilt infile=table.fits colname=rate outfile=filtered.fits
func=mean mask="111"

The output file, filtered.fits, will be a copy of the input file with a 'rate_mean' column added. The rate_mean will be the mean of three values - the current, previous, and next rows - i.e. a "running" or "moving" average.

Example 2

dmtabfilt infile=table.fits colname=rate outfile=filtered.fits
func=median mask="111"

The previous example repeated with func=median. The newly-created output column will be called 'rate_median' column and will contain the median of the three values.

Example 3

dmtabfilt infile=table.fits colname=rate outfile=filtered.fits
func=peak mask="11111"

Look for peaks, e.g. in a lightcurve, using a five-row window (-2 to +2). If the current row is the maximum of the values, then it is unchanged; otherwise the "rate_peak" value is NaN.

Example 4

dmtabfilt infile=table.fits colname=rate outfile=filtered.fits func=max
mask="1110000"

Look for the maximum value from the previous three rows, not including the current row.


Parameters

name type ftype def min max reqd stacks
infile file input       yes no
colname string         yes  
outfile file output       yes no
function string         yes  
mask string         yes  
clobber boolean   no        
verbose integer   0 0 5    

Detailed Parameter Descriptions

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

Input filename

Parameter=colname (string required)

The column name to filter

The output file will have a new column added that is $colname_$function

Parameter=outfile (file required filetype=output stacks=no)

The input block is copied to the output file. A new column, $colname_$function, is added.

Parameter=function (string required)

Filter function

The list of available filters can be found in ahelp dmimgfilt. However, the following filters are not supported for tables: locheq, kuwahara, and mcv.

Parameter=mask (string required)

A string of 1's and 0's to indicate which rows adjacent to the current row should be included in the filter. The middle of the string is always taken to the current row. Even-length strings generate a warning since filters are often (though not required to be) symmetrical.

Parameter=clobber (boolean default=no)

Remove output if it exists?

If clobber=yes and a file exists that has the same name as the name of the output file, then the existing file is overwritten.

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

Tool verbosity level

Verbose can be from 0 to 5, which determines the amount of screen output that is generated.


Bugs

There are no known bugs for this tool.

See Also

dm
dmfiltering, dmopt
tools::core
dmappend
tools::table
dmgroup, dmjoin, dmmerge, dmpaste, dmsort, dmtcalc, dmtype2split
tools::timing
dmgti