# API for interpolation - Incanter1.5.5 (stable)

by Nikita Beloglazov

Full namespace name: incanter.interpolation

## Overview

```Interpolation and approximation of collection of points..
Supported types: linear, polynomial, cubic spline,
cubic hermite spline, B-spline, linear least squares.
Supports 1-dimensional and 2-dimensional interpolations.```

## interpolate

function
```Usage: (interpolate points type & options)
```
```Builds a function that interpolates given collection of points.
http://en.wikipedia.org/wiki/Interpolation
http://en.wikipedia.org/wiki/Linear_least_squares_(mathematics)

Arguments:
points -- collection of points. Each point is a collection [x y].
type -- type of interpolation - :linear, :polynomial, :cubic, :cubic-hermite, :linear-least-squares.
For most cases you should use :cubic or :cubic-hermite - they usually give best results.
Check http://en.wikipedia.org/wiki/Interpolation for brief explanation of each kind.

Options:
:boundaries - valid only for :cubic interpolation. Defines boundary condition for cubic spline.
Possible values - :natural and :closed.
Let's S - spline, a- leftmost point, b- rightmost point.
:natural - S''(a) = S''(b) = 0
:closed - S'(a) = S'(b), S''(a) = S''(b) . This type of boundary conditions may be
useful if you want to get periodic or closed curve.
Default value is :natural

:derivatives - valid only for :cubic-hermite. Defines first derivatives for spline.
If not specified derivatives will be approximated from points.

Options for linear least squares:
:basis - type of basis functions. There are 2 built-in bases: chebushev polynomials and b-splines (:polynomial and :b-spline).
You also can supply your own basis. It should be a function that takes x and returns collection [f1(x) f2(x) ... fn(x)].
Example of custom basis of 2 functions (1 and  x*x): (interpolate :linear-least-squares :basis (fn [x] [1 (* x x)]))
Default value is :chebyshev

:n - number of functions in basis if you use built-in basis.
Note that if n is greater that number of points then you might get singular matrix and exception.
Default value is 4.

:degree - degree of b-spline if you use :b-spline basis.
Default value is 3.

Examples:

(def points [[0 0] [1 5] [2 0] [3 5]])
(def linear (interpolate points :linear))
(linear 0) => 0.0
(linear 1) => 5.0
(linear 1.5) => 2.5

; Specify boundary conditions
(interpolate points :cubic :boundaries :closed)
```

Source

## interpolate-grid

function
```Usage: (interpolate-grid grid type & options)
```
```Interpolates 2-dimensional grid. Returns function f that takes 2 arguments: x and y.
By default function interpolates on [0,1]x[0,1].

Arguments:
grid -- collection of collection of numbers to be interpolated.
If you need to interpolate vectors - interpolate each component by separate interpolator.
type -- type of interpolation. Available: :bilinear, :polynomial, :bicubic, :bicubic-hermite, :b-surface, :linear-least-squares

Common options:
:x-range, :y-range - range of possible x and y.
By default :x-range = [0 1] and :y-range = [0 1]
:b-surface ignores this option and always uses [0, 1] x [0, 1]

:xs, :ys - coordinates of grid points. Size of xs and ys must be consistent with grid size.
If you have grid 4x3 then xs must have size 3 and ys - 4.

Note that (:x-range, :y-range) and (:xs, :ys) both do same job - they specify coordinates of points in grid.
So you should use only one of them or none at all.

Type specific options:
:boundaries - valid only for :cubic interpolation. Defines boundary condition for bicubic spline.
Possible values - :natural and :closed.
Default - :natural. Check documentation of 'interpolate' method for more explanation.

:degree - valid only for :b-spline. Degree of a B-spline. Default 3. Degree will be reduced if there are too few points.

:basis - defines basis for :linear-least-squares. It has 1 predefined basis :polynomial. :polynomial basis
contains functions: (1, x, y, x^2, xy, y^2, x^3, ...)
You can specify how many functions basis contains by using :n option.
You can also specify custom basis. Custom basis is a function that takes 2 arguments - x and y, and returns collection of values.
Example: basis that contains only 2-degree polynomials: (fn [x y] [(* x x) (* x y) (* y y)])

:n - defines how many functions polynomial contains. Example: 1 - basis is (1), 3 - basis is (1, x, y), 5 - basis is (1, x, y, x^2, x*y)

Examples:

(def grid [[0 1 0]
[1 2 1]
[0 1 0]])
(def interpolator (interpolate-grid grid :bilinear))
(interpolator   0   0) => 0
(interpolator 1/2 1/2) => 2
(interpolator 1/2   1) => 1
(interpolator 1/4   0) => 1/2

; Specify x-range and y-range
(def interpolator (interpolate-grid grid :bilinear :x-range [0 10] :y-range [-5 5]))
(interpolator  0  -5) => 0
(interpolator  5   0) => 2
(interpolator 10   5) => 0

; Specify xs and ys
(def interpolator (interpolate-grid grid :bilinear :xs [0 1 2] :ys [0 10 100]))
(interpolator  0   0) => 0
(interpolator  1  10) => 2
(interpolator  2 100) => 0```

Source

## interpolate-parametric

function
```Usage: (interpolate-parametric points type & options)
```
```Builds a parametric function that interpolates given collection of points.
Parametric function represents a curve that go through all points. By default domain is [0, 1].

Arguments:
points -- collection of points. Each point either a single value or collection of values.
type -- type of interpolation - :linear, :polynomial, :cubic, :cubic-hermite, :b-spline, :linear-least-squares.

Options:
:range -- defines range for parameter t.
Default value is [0, 1]. f(0) = points[0], f(1) = points[n].

:boundaries -- valid only for :cubic interpolation.
Defines boundary condition for cubic spline. Possible values - :natural and :closed.
Let's S - spline, a- leftmost point, b- rightmost point.
:natural - S''(a) = S''(b) = 0
:closed - S'(a) = S'(b), S''(a) = S''(b) . This type of boundary conditions may be useful
if you want to get periodic or closed curve

Default value is :natural

:derivatives - valid only for :cubic-hermite. Defines first derivatives for spline.
If not specified derivatives will be approximated from points.

:degree - valid only for :b-spline. Degree of a B-spline. Default 3. Degree will be reduced if there are too few points.

Options for linear least squares:
See documentation for interpolate function.

Examples:

(def points [[0 0]
[0 1]
[1 1]
[3 5]
[2 9]])
(def cubic (interpolate-parametric points :cubic))
(cubic 0) => [0.0 0.0]
(cubic 1) => [2.0 9.0]
(cubic 0.5) => [1.0 1.0]

; Specify custom :range
(def cubic (interpolate-parametric points :cubic :range [-10 10]))
(cubic -10) => [0.0 0.0]
(cubic 0) => [1.0 1.0]
```

Source

Logo & site design by Tom Hickey.
Clojure auto-documentation system by Tom Faulhaber.