Provided by: plotutils_2.6-10build1_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.