SPLINE(1)						      GNU Plotting Utilities							 SPLINE(1)

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 inter-
       polated 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 indepen-
       dent variable, and y is a vector-valued dependent variable.  The dimensionality of y is specified with the -d option  (the  default  dimen-
       sionality 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 `#'.  Com-
       ment 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 coordi-
		     nates 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 float-
		     ing 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 preci-
		     sion 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  out-
	      put 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.

FSF
								     Dec 1998								 SPLINE(1)