Table of Contents
spline - interpolate datasets using splines under tension
spline
[ options ] [ files ]
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.
- -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
- --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(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).
- -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.
- --help
- Print a list of command-line options, and exit.
- --version
- Print the version
number of spline and the plotting utilities package, and exit.
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.
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).
"The GNU Plotting Utilities Manual".
Email bug reports to bug-gnu-utils@gnu.org.
Table of Contents