SPLINE(1)            GNU Plotting Utilities           SPLINE(1)





NAME
       spline  -  interpolate datasets using splines under ten-
       sion

SYNOPSIS
       spline [ options ] [ files ]

DESCRIPTION
       spline reads datasets from standard input or from one or
       more files, and fits a smooth curve (a "spline") through
       each dataset.  An interpolated version of each  dataset,
       consisting  of  points from the smooth curve, is written
       to standard output.

       Unless the -a or -A options are used (see  below),  each
       dataset should be a sequence of values for a vector-val-
       ued function of a single scalar variable.  That is, each
       dataset  should  be  a sequence of data points, given as
       alternating t and y values.  t is a  scalar  independent
       variable,  and  y is a vector-valued dependent variable.
       The dimensionality of y is specified with the -d  option
       (the  default  dimensionality  is 1).  Between each data
       point and the next, t should increase.

       An input file may contain more than  a  single  dataset.
       If  an  input file is in ASCII format (the default), its
       datasets should be separated by blank lines.  The t  and
       y  values  of  the  data  points  in each dataset may be
       arranged arbitrarily, so long as they are  separated  by
       white  space.   Besides datasets, an input file may con-
       tain any number of comment  lines,  which  should  begin
       with  the  comment  character  `#'.   Comment  lines are
       ignored.  They are not treated as blank, i.e.,  they  do
       not interrupt a dataset in progress.

       Options  and  file names may be interspersed on the com-
       mand line, but the options are processed before the file
       names are read.  If -- is seen, it is interpreted as the
       end of the options.  If no file names are specified,  or
       the  file  name  - is encountered, the standard input is
       read.

       The type of interpolation, and the format of  the  input
       and  output  files,  may  be  selected  by  command-line
       options.

OPTIONS
   Interpolation-Related Options
       -f
       --filter
              Use a local interpolation  algorithm  (the  cubic
              Bessel  algorithm), so that spline can be used as
              a real-time filter.  The slope of the interpolat-
              ing curve at each point in a dataset will be cho-
              sen by fitting a quadratic function through  that
              point and the two adjacent points in the dataset.
              If -f is specified then the -t option,  otherwise
              optional,  must  be used as well.  Also, if -f is
              specified then the -k, -p, and -T options may not
              be used.

              If -f is not specified, then the default (global)
              interpolation algorithm will be used.

       -k k
       --boundary-condition k
              Set the boundary  condition  parameter  for  each
              constructed  spline  to be k.  (The default value
              is 1.0.)  In each of its components,  the  spline
              will   satisfy   the   two   boundary  conditions
              y"[0]=ky"[1] and y"[n]=ky"[n-1].  Here  y[0]  and
              y[1]  signify the values of a specified component
              of the vector-valued dependent variable y at  the
              first  two  points  of  a dataset, and y[n-1] and
              y[n] the values at the last two points.   Setting
              k  to  zero  will yield a "natural" spline, i.e.,
              one that has zero curvature at the  two  ends  of
              the dataset.  The -k option may not be used if -f
              or -p is specified.

       -n n
       --number-of-intervals n
              Subdivide the interval over  which  interpolation
              occurs  into  n subintervals.  The number of data
              points computed, and written to the output,  will
              be n+1.  The default value for n is 100.

       -p
       --periodic
              Construct  a  periodic spline.  If this option is
              specified, the y values for the  first  and  last
              points in each dataset must be equal.  The -f and
              -k options may not be used if -p is specified.

       -T tension
       --tension tension
              Each interpolating curve will be a  spline  under
              tension.  This option sets the tension value (the
              default is 0.0).

              If tension equals  zero,  the  curve  will  be  a
              piecewise  cubic  spline.  Increasing the tension
              above zero makes the curve "tighter", and reduces
              the  likelihood  of  spurious  inflection points.
              That is because between each pair  of  successive
              points  in  a dataset, the curve will satisfy the
              fourth-order differential  equation  y""=sgn(ten-
              sion)*(tension^2)y"  in  each  of its components.
              As tension increases  to  positive  infinity,  it
              will converge to a polygonal line.  The -T option
              may not be used if -f is specified.

       -t tmin tmax [tspacing]
       --t-spacing tmin tmax [tspacing]
              For each dataset, set  the  interval  over  which
              interpolation  occurs  to be the interval between
              tmin and tmax.  If tspacing is not specified, the
              interval  will  be  divided  into  the  number of
              subintervals specified by the -n option.

              If the -t option is not used, the  interval  over
              which  interpolation  occurs  will  be the entire
              range of the independent variable in the dataset.
              The  -t  option  must  always  be  used if the -f
              option is used to  request  filter-like  behavior
              (see above).

   Format-Related Options
       -d dimension
       --y-dimension dimension
              Set  the dimensionality of the dependent variable
              y in the input and output files to be  dimension.
              The default dimension is 1.

       -I data-format
       --input-format data-format
              Set  the  data format for the input file(s) to be
              data-format, which may be one of the following.

              a      ASCII format (the default).  Each file  is
                     a  sequence  of  floating  point  numbers,
                     interpreted as the t and y coordinates  of
                     the  successive  data points in a dataset.
                     If y is d-dimensional, there will  be  d+1
                     numbers for each point.  The t and y coor-
                     dinates of a point need not appear on  the
                     same  line,  and points need not appear on
                     different lines.   But  if  a  blank  line
                     occurs  (i.e.,  two newlines in succession
                     are seen), it is interpreted as the end of
                     a  dataset, and the beginning of the next.

              f      Single precision binary format.  Each file
                     is  a  sequence of floating point numbers,
                     interpreted as the t and y coordinates  of
                     the  successive  data points in a dataset.
                     If y is d-dimensional, there will  be  d+1
                     numbers   for   each   point.   Successive
                     datasets are separated by a single  occur-
                     rence  of  the  quantity FLT_MAX, which is
                     the  largest  possible  single   precision
                     floating  point  number.  On most machines
                     this is approximately 3.4x10^38.

              d      Double precision binary format.  Each file
                     is a sequence of double precision floating
                     point numbers, interpreted as the t and  y
                     coordinates  of the successive data points
                     in a  dataset.   If  y  is  d-dimensional,
                     there  will be d+1 numbers for each point.
                     Successive datasets  are  separated  by  a
                     single occurrence of the quantity DBL_MAX,
                     which is the largest possible double  pre-
                     cision  floating  point  number.   On most
                     machines this is approximately 1.8x10^308.

              i      Integer  binary  format.   Each  file is a
                     sequence of integers, interpreted as the t
                     and  y  coordinates of the successive data
                     points in a dataset.   If  y  is  d-dimen-
                     sional, there will be d+1 numbers for each
                     point.  Successive datasets are  separated
                     by  a  single  occurrence  of the quantity
                     INT_MAX, which  is  the  largest  possible
                     integer.  On most machines this is 2^31-1.

       -a [step_size [lower_limit]]
       --auto-abscissa [step_size [lower_limit]]
              Automatically generate values for t, the indepen-
              dent  variable  (the  default values of step_size
              and lower_limit are 1.0 and 0.0, respectively).

              Irrespective of data format (`a',  `f',  `d',  or
              `i'),  this option specifies that the values of t
              are missing from the input file:  the  dataset(s)
              to  be  read contain only values of y, the depen-
              dent variable.  So if y is  d-dimensional,  there
              will  be  only  d  numbers  for  each point.  The
              increment from each t value to the next  will  be
              step_size,   and   the  first  t  value  will  be
              lower_limit.  This option is useful,  e.g.,  when
              interpolating curves rather than functions.

       -A
       --auto-dist-abscissa
              Automatically generate values for t, the indepen-
              dent variable.  This is a variant form of the  -a
              option.   The  increment from each t value to the
              next will be the distance in d-dimensional  space
              between the corresponding y values, and the first
              t value will be 0.0.  That is, t will be "polygo-
              nal  arclength".   This  option  is  useful  when
              interpolating curves rather than functions.

       -O data-format
       --output-format data-format
              Set the data format for the  output  file  to  be
              data-format.   The  interpretation of data-format
              is the same as for the -I option.  The default is
              `a', i.e., ASCII format.

       -P significant-digits
       --precision significant-digits
              Set  the numerical precision for the t and y val-
              ues in the output file to be  significant-digits.
              This  takes  effect  only  if  the output file is
              written in `a' format, i.e., in ASCII.   signifi-
              cant-digits  must  be  a  positive  integer  (the
              default is 6).

       -s
       --suppress-abscissa
              Omit the independent variable t from  the  output
              file;  for  each point, supply only the dependent
              variable y.  If y is d-dimensional, there will be
              only  d  numbers  for  each point, not d+1.  This
              option is useful when interpolating curves rather
              than functions.

   Informational Options
       --help Print a list of command-line options, and exit.

       --version
              Print  the version number of spline and the plot-
              ting utilities package, and exit.

EXAMPLES
       Typing

              echo 0 0 1 1 2 0 | spline

       will produce on standard output an interpolated  dataset
       consisting  of 101 data points.  If graphed, this inter-
       polated dataset will yield a parabola.

       It is sometimes useful to interpolate between a sequence
       of  arbitrarily  placed  points  in d-dimensional space,
       i.e., to "spline a curve" rather than a  function.   The
       -a and -s options are used for this.  For example,

              echo 0 0 1 0 1 1 0 1 | spline -d 2 -a -s

       will produce on standard output a 101-point dataset that
       interpolates  between  the  four  points  (0,0),  (1,0),
       (1,1),  and  (0,1).   The -d 2 option specifies that the
       dependent variable y is two-dimensional.  The -a  option
       specifies  that  the t values are missing from the input
       and should be automatically generated.   The  -s  option
       specifies  that the t values should be stripped from the
       output.

AUTHORS
       spline was written by  Robert  S.  Maier  (rsm@math.ari-
       zona.edu),  starting  with  an  earlier  version by Rich
       Murphey (rich@freebsd.org).   The  algorithms  for  con-
       structing  splines  under  tension  are similar to those
       used in the FITPACK subroutine library,  and  are  ulti-
       mately due to Alan K. Cline (cline@cs.utexas.edu).

SEE ALSO
       "The GNU Plotting Utilities Manual".

BUGS
       Email bug reports to bug-gnu-utils@gnu.org.



FSF                         Dec 1998                  SPLINE(1)
