Provided by: plotutils_2.6-10_amd64 bug

NAME

       spline - interpolate datasets using splines under tension

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-valued 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 contain 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 command 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 interpolating  curve  at  each
              point  in  a  dataset  will  be chosen 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
       --no-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(tension)*(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 coordinates 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 occurrence 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
                     precision 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-dimensional,  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 independent 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 dependent 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 independent 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  "polygonal  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 values 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.  significant-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 plotting 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 interpolated 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.arizona.edu),  starting  with  an  earlier
       version by Rich Murphey (rich@freebsd.org).  The algorithms for constructing splines under
       tension are similar to those used in the FITPACK subroutine library,  and  are  ultimately
       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.