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)

Man(1) output converted with man2html