FILTER1D(1)

NAME
filter1d - Time domain filtering of 1-D time series

SYNOPSIS
filter1d [ infile ] -F<type><width>[mode] [ -Dincrement ] [ -E ] [ -H[nrec] ] [ -Iignore_val ] [ -Llack_width ] [ -Nn_cols/t_col ] [ -Qq_factor ] [ -Ssymmetry_factor ] [ -Tstart/stop/int ] [ -V ] [ -bi[s][n] ] [ -bo[s][n] ] [ -f[i|o]colinfo ]

DESCRIPTION
filter1d is a general time domain filter for multiple column time series data. The user specifies the number of columns of input and which column is the time. (See -N option below). The fastest operation occurs when the input time series are equally spaced and have no gaps or outliers and the special options are not needed. filter1d has options -L, -Q, and -S for unevenly sampled data with gaps.

infile
    Multi-column ASCII (or binary, see -b) file holding data values to be filtered.

-F  Sets the filter type. Choose among convolution and non-convolution filters. Append the filter code followed by the full filter width in same units as time column. Available convolution filters are:
    (b) Boxcar: All weights are equal.
    (c) Cosine Arch: Weights follow a cosine arch curve.
    (g) Gaussian: Weights are given by the Gaussian function.
    (f) Custom: Instead of width give name of a one-column file of your own weight coefficients.
    Non-convolution filters are:
    (m) Median: Returns median value.
    (p) Maximum likelihood probability (a mode estimator): Return modal value. If more than one mode is found we return their average value. Append - or + to the filter width if you rather want to return the smallest or largest of the modal values.
    (l) Lower: Return the minimum of all values.
    (L) Lower: Return minimum of all positive values only.
    (u) Upper: Return maximum of all values.
    (U) Upper: Return maximum or all negative values only.
    Upper case type B, C, G, M, P, F will use robust filter versions: i.e., replace outliers (2.5 L1 scale off median) with median during filtering.
    In the case of L|U it is possible that no data passes the initial sign test; in that case the filter will return 0.0.

OPTIONS

-D  increment is used when series is NOT equidistantly sampled. Then increment will be the abscissae resolution, i.e., all abscissae will be rounded off to a multiple of increment. Alternatively, resample data with sample1d.

-E  Include Ends of time series in output. Default loses half the filter-width of data at each end.

-H  Input file(s) has Header record(s). Number of header records can be changed by editing your .gmtdefaults4 file. If used, GMT default is 1 header record. Use -Hi if only input data should have header records [Default will write out header records if the input data have them].

-I  To ignore values; If an input value equals ignore_val it will be set to NaN.

-L  Checks for Lack of data condition. If input data has a gap exceeding width then no output will be given at that point [Default does not check Lack].

-N  Sets number of columns in input and which column contains the independent variable (time). The left-most column is # 0, the right-most is # (n_cols - 1). [Default is n_cols = 2, t_col = 0; i.e., file has t, f(t) pairs].

-Q  assess Quality of output value by checking mean weight in convolution. Enter q_factor between 0 and 1. If mean weight < q_factor, output is suppressed at this point [Default does not check Quality].

-S  Checks symmetry of data about window center. Enter a factor between 0 and 1. If ( (abs(n_left - n_right)) / (n_left + n_right) ) > factor, then no output will be given at this point [Default does not check Symmetry].

-T  Make evenly spaced timesteps from start to stop by int [Default uses input times].

-V  Selects verbose mode, which will send progress reports to stderr [Default runs "silently"].

-bi Selects binary input. Append s for single precision [Default is double]. Append n for the number of columns in the binary file(s).

-bo Selects binary output. Append s for single precision [Default is double]. Append n for the number of columns in the binary file(s).

-f  Special formatting of input and output columns (time or geographical data) Specify i(nput) or o(utput) [Default is both input and output]. Give one or more columns (or column ranges) separated by commas. Append T (Absolute calendar time), t (time relative to chosen TIME_EPOCH), x (longitude), y (latitude), g (geographic coordinate), or f (floating point) to each column or column range item.

EXAMPLES
To filter the data set in the file cruise.gmtd containing evenly spaced gravity, magnetics, topography, and distance (in m) with a 10 km Gaussian filter, removing outliers, and output a filtered value every 2 km between 0 and 100 km:

filter1d cruise.gmtd -T0/1.0e5/2000 -FG10000 -N4/3 -V > filtered_cruise.gmtd

Data along track often have uneven sampling and gaps which we do not want to interpolate using sample1d. To find the median depth in a 50 km window every 25 km along the track of cruise v3312, stored in v3312.dt, checking for gaps of 10km and asymmetry of 0.3:

filter1d v3312.dt -FM50 -T0/100000/25 -L10 -S0.3 > v3312_filt.dt

SEE ALSO
gmt(1), sample1d(1)