Ubuntu Manpage: spline - interpolate datasets using splines under tension

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).

BUGS

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