## 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-convolu-
                  tion filters. Append the filter code followed by the full filter
                  width in same units as time column. Available  convolution  fil-
                  ters 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 ver-
                  sions: 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 ini-
                  tial 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. Alter-
                  natively, 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 convo-
                  lution.  Enter q_factor between 0 and 1. If mean weight < q_fac-
                  tor, 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  geo-
                  graphical  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 Gaus-
           sian 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  >  fil-
           tered_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(l), sample1d(l)

    GMT4.0                            1 Oct 2004                       FILTER1D(l)