1SPLINE(1)                   GNU Plotting Utilities                   SPLINE(1)
2
3
4

NAME

6       spline - interpolate datasets using splines under tension
7

SYNOPSIS

9       spline [ options ] [ files ]
10

DESCRIPTION

12       spline  reads  datasets  from standard input or from one or more files,
13       and fits a smooth curve (a "spline") through each dataset.  An interpo‐
14       lated  version  of  each  dataset, consisting of points from the smooth
15       curve, is written to standard output.
16
17       Unless the -a or -A options are used (see below), each  dataset  should
18       be a sequence of values for a vector-valued function of a single scalar
19       variable.  That is, each dataset should be a sequence of  data  points,
20       given  as  alternating t and y values.  t is a scalar independent vari‐
21       able, and y is a vector-valued dependent variable.  The  dimensionality
22       of y is specified with the -d option (the default dimensionality is 1).
23       Between each data point and the next, t should increase.
24
25       An input file may contain more than a single dataset.  If an input file
26       is  in  ASCII format (the default), its datasets should be separated by
27       blank lines.  The t and y values of the data points in each dataset may
28       be  arranged arbitrarily, so long as they are separated by white space.
29       Besides datasets, an input file  may  contain  any  number  of  comment
30       lines,  which  should  begin  with  the comment character `#'.  Comment
31       lines are ignored.  They are not treated as blank, i.e.,  they  do  not
32       interrupt a dataset in progress.
33
34       Options and file names may be interspersed on the command line, but the
35       options are processed before the file names are read.  If --  is  seen,
36       it  is  interpreted  as  the  end of the options.  If no file names are
37       specified, or the file name - is encountered,  the  standard  input  is
38       read.
39
40       The  type  of  interpolation,  and  the  format of the input and output
41       files, may be selected by command-line options.
42

OPTIONS

44   Interpolation-Related Options
45       -f
46       --filter
47              Use a local interpolation  algorithm  (the  cubic  Bessel  algo‐
48              rithm),  so  that spline can be used as a real-time filter.  The
49              slope of the interpolating curve at each point in a dataset will
50              be chosen by fitting a quadratic function through that point and
51              the two adjacent points in the dataset.  If -f is specified then
52              the  -t option, otherwise optional, must be used as well.  Also,
53              if -f is specified then the -k, -p, and -T options  may  not  be
54              used.
55
56              If  -f is not specified, then the default (global) interpolation
57              algorithm will be used.
58
59       -k k
60       --boundary-condition k
61              Set the boundary condition parameter for each constructed spline
62              to  be  k.   (The  default value is 1.0.)  In each of its compo‐
63              nents, the spline  will  satisfy  the  two  boundary  conditions
64              y"[0]=ky"[1] and y"[n]=ky"[n-1].  Here y[0] and y[1] signify the
65              values of a specified component of the  vector-valued  dependent
66              variable  y at the first two points of a dataset, and y[n-1] and
67              y[n] the values at the last two points.  Setting k to zero  will
68              yield  a  "natural" spline, i.e., one that has zero curvature at
69              the two ends of the dataset.  The -k option may not be  used  if
70              -f or -p is specified.
71
72       -n n
73       --number-of-intervals n
74              Subdivide  the  interval  over which interpolation occurs into n
75              subintervals.  The number of data points computed,  and  written
76              to the output, will be n+1.  The default value for n is 100.
77
78       -p
79       --periodic
80              Construct a periodic spline.  If this option is specified, the y
81              values for the first and last points in  each  dataset  must  be
82              equal.   The  -f  and -k options may not be used if -p is speci‐
83              fied.
84
85       -T tension
86       --tension tension
87              Each interpolating curve will be a spline under  tension.   This
88              option sets the tension value (the default is 0.0).
89
90              If  tension  equals  zero,  the  curve will be a piecewise cubic
91              spline.  Increasing the  tension  above  zero  makes  the  curve
92              "tighter",  and  reduces  the  likelihood of spurious inflection
93              points.  That is because between each pair of successive  points
94              in  a dataset, the curve will satisfy the fourth-order differen‐
95              tial equation y""=sgn(tension)*(tension^2)y" in each of its com‐
96              ponents.   As  tension  increases  to positive infinity, it will
97              converge to a polygonal line.  The -T option may not be used  if
98              -f is specified.
99
100       -t tmin tmax [tspacing]
101       --t-spacing tmin tmax [tspacing]
102              For  each  dataset,  set  the  interval over which interpolation
103              occurs to be the interval between tmin and tmax.  If tspacing is
104              not  specified,  the interval will be divided into the number of
105              subintervals specified by the -n option.
106
107              If the -t option is not used, the interval over which interpola‐
108              tion occurs will be the entire range of the independent variable
109              in the dataset.  The -t option must always be  used  if  the  -f
110              option is used to request filter-like behavior (see above).
111
112   Format-Related Options
113       -d dimension
114       --y-dimension dimension
115              Set  the dimensionality of the dependent variable y in the input
116              and output files to be dimension.  The default dimension is 1.
117
118       -I data-format
119       --input-format data-format
120              Set the data format for the input  file(s)  to  be  data-format,
121              which may be one of the following.
122
123              a      ASCII  format  (the default).  Each file is a sequence of
124                     floating point numbers, interpreted as the t and y  coor‐
125                     dinates of the successive data points in a dataset.  If y
126                     is d-dimensional, there will  be  d+1  numbers  for  each
127                     point.   The  t  and  y  coordinates  of a point need not
128                     appear on the same line, and points need  not  appear  on
129                     different  lines.   But if a blank line occurs (i.e., two
130                     newlines in succession are seen), it  is  interpreted  as
131                     the end of a dataset, and the beginning of the next.
132
133              f      Single  precision binary format.  Each file is a sequence
134                     of floating point numbers, interpreted as  the  t  and  y
135                     coordinates  of  the successive data points in a dataset.
136                     If y is d-dimensional, there will be d+1 numbers for each
137                     point.   Successive  datasets  are  separated by a single
138                     occurrence of the quantity FLT_MAX, which is the  largest
139                     possible single precision floating point number.  On most
140                     machines this is approximately 3.4x10^38.
141
142              d      Double precision binary format.  Each file is a  sequence
143                     of  double  precision floating point numbers, interpreted
144                     as the t and y coordinates of the successive data  points
145                     in  a  dataset.  If y is d-dimensional, there will be d+1
146                     numbers for each point.  Successive  datasets  are  sepa‐
147                     rated  by  a  single  occurrence of the quantity DBL_MAX,
148                     which is the largest possible double  precision  floating
149                     point  number.   On  most  machines this is approximately
150                     1.8x10^308.
151
152              i      Integer binary format.  Each file is a sequence of  inte‐
153                     gers,  interpreted as the t and y coordinates of the suc‐
154                     cessive data points in a dataset.  If y is d-dimensional,
155                     there  will  be  d+1  numbers for each point.  Successive
156                     datasets are separated by  a  single  occurrence  of  the
157                     quantity  INT_MAX, which is the largest possible integer.
158                     On most machines this is 2^31-1.
159
160       -a [step_size [lower_limit]]
161       --auto-abscissa [step_size [lower_limit]]
162              Automatically generate values for t,  the  independent  variable
163              (the  default  values  of  step_size and lower_limit are 1.0 and
164              0.0, respectively).
165
166              Irrespective of data format (`a', `f', `d', or `i'), this option
167              specifies  that the values of t are missing from the input file:
168              the dataset(s) to be read contain only values of y,  the  depen‐
169              dent  variable.   So if y is d-dimensional, there will be only d
170              numbers for each point.  The increment from each t value to  the
171              next   will  be  step_size,  and  the  first  t  value  will  be
172              lower_limit.  This option is useful,  e.g.,  when  interpolating
173              curves rather than functions.
174
175       -A
176       --auto-dist-abscissa
177              Automatically  generate  values for t, the independent variable.
178              This is a variant form of the -a  option.   The  increment  from
179              each  t  value to the next will be the distance in d-dimensional
180              space between the corresponding y values, and the first t  value
181              will  be  0.0.   That is, t will be "polygonal arclength".  This
182              option is useful when interpolating  curves  rather  than  func‐
183              tions.
184
185       -O data-format
186       --output-format data-format
187              Set  the data format for the output file to be data-format.  The
188              interpretation of data-format is the same as for the -I  option.
189              The default is `a', i.e., ASCII format.
190
191       -P significant-digits
192       --precision significant-digits
193              Set the numerical precision for the t and y values in the output
194              file to be significant-digits.  This takes effect  only  if  the
195              output  file is written in `a' format, i.e., in ASCII.  signifi‐
196              cant-digits must be a positive integer (the default is 6).
197
198       -s
199       --suppress-abscissa
200              Omit the independent variable t from the output file;  for  each
201              point,  supply  only the dependent variable y.  If y is d-dimen‐
202              sional, there will be only d numbers for each  point,  not  d+1.
203              This  option  is  useful  when  interpolating curves rather than
204              functions.
205
206   Informational Options
207       --help Print a list of command-line options, and exit.
208
209       --version
210              Print the version number of spline and  the  plotting  utilities
211              package, and exit.
212

EXAMPLES

214       Typing
215
216              echo 0 0 1 1 2 0 | spline
217
218       will  produce  on standard output an interpolated dataset consisting of
219       101 data points.  If graphed, this interpolated dataset  will  yield  a
220       parabola.
221
222       It is sometimes useful to interpolate between a sequence of arbitrarily
223       placed points in d-dimensional space, i.e., to "spline a curve"  rather
224       than  a  function.  The -a and -s options are used for this.  For exam‐
225       ple,
226
227              echo 0 0 1 0 1 1 0 1 | spline -d 2 -a -s
228
229       will produce on standard output a 101-point dataset  that  interpolates
230       between  the  four  points  (0,0),  (1,0),  (1,1), and (0,1).  The -d 2
231       option specifies that the dependent variable y is two-dimensional.  The
232       -a  option  specifies  that the t values are missing from the input and
233       should be automatically generated.  The -s option specifies that the  t
234       values should be stripped from the output.
235

AUTHORS

237       spline  was written by Robert S. Maier (rsm@math.arizona.edu), starting
238       with an earlier version by Rich Murphey (rich@freebsd.org).  The  algo‐
239       rithms for constructing splines under tension are similar to those used
240       in the FITPACK subroutine library, and are ultimately due  to  Alan  K.
241       Cline (cline@cs.utexas.edu).
242

SEE ALSO

244       "The GNU Plotting Utilities Manual".
245

BUGS

247       Email bug reports to bug-gnu-utils@gnu.org.
248
249
250
251FSF                                Dec 1998                          SPLINE(1)
Impressum