naginterfaces.library.smooth.fit_​spline

naginterfaces.library.smooth.fit_spline(mode, x, y, rho, c, comm, wt=None)

fit_spline fits a cubic smoothing spline for a given smoothing parameter.

For full information please refer to the NAG Library document for g10ab

https://support.nag.com/numeric/nl/nagdoc_30/flhtml/g10/g10abf.html

Parameters

modestr, length 1

Indicates in which mode the function is to be used.

$mode=\text{'P'}$

Initialization and fitting is performed. This partial fit can be used in an iterative weighted least squares context where the weights are changing at each call to fit_spline or when the coefficients are not required.

$mode=\text{'Q'}$

Fitting only is performed. Initialization must have been performed previously by a call to fit_spline with $mode=\text{'P'}$. This quick fit may be called repeatedly with different values of $rho$ without re-initialization.

$mode=\text{'F'}$

Initialization and full fitting is performed and the function coefficients are calculated.

xfloat, array-like, shape $\left(n\right)$

The distinct and ordered values $x_{\text{i}}$, for $\text{i}=1,2,\dots ,n$.

yfloat, array-like, shape $\left(n\right)$

The values $y_{\text{i}}$, for $\text{i}=1,2,\dots ,n$.

rhofloat

$\rho$, the smoothing parameter.

cfloat, array-like, shape $(n-1,3)$

If $mode=\text{'Q'}$, $c$ must be unaltered from the previous call to fit_spline with $mode=\text{'P'}$. Otherwise $c$ need not be set.

commdict, communication object, modified in place

Communication structure.

On initial entry: need not be set.

wtNone or float, array-like, shape $\left(n\right)$, optional

If $\text{weight}=\text{'W'}$, $wt$ must contain the $n$ weights. Otherwise $wt$ is not referenced and unit weights are assumed.

Returns

yhatfloat, ndarray, shape $\left(n\right)$

The fitted values, ${\hat{y}}_{\text{i}}$, for $\text{i}=1,2,\dots ,n$.

cfloat, ndarray, shape $(n-1,3)$

If $mode=\text{'F'}$, $c$ contains the spline coefficients. More precisely, the value of the spline at $t$ is given by $(\left(c\right[i-1,2]\times d+c[i-1,1\left]\right)\times d+c[i-1,0\left]\right)\times d+{\hat{y}}_i$, where $x_i\le t<x_{i+1}$ and $d=t-x_i$.

If $mode=\text{'P'}$ or $\text{'Q'}$, $c$ contains information that will be used in a subsequent call to fit_spline with $mode=\text{'Q'}$.

rssfloat

The (weighted) residual sum of squares.

dffloat

The residual degrees of freedom.

resfloat, ndarray, shape $\left(n\right)$

The (weighted) residuals, $r_{\text{i}}$, for $\text{i}=1,2,\dots ,n$.

hfloat, ndarray, shape $\left(n\right)$

The leverages, $h_{\text{i}\text{i}}$, for $\text{i}=1,2,\dots ,n$.

Raises

NagValueError

(errno $1$)

On entry, $mode=⟨value⟩$.

Constraint: $mode=\text{'P'}$, $\text{'Q'}$ or $\text{'F'}$.

(errno $1$)

On entry, $rho=⟨value⟩$.

Constraint: $rho\ge 0.0$.

(errno $1$)

On entry, $n=⟨value⟩$.

Constraint: $n\ge 3$.

(errno $2$)

On entry, at least one element of $wt\le 0.0$.

(errno $3$)

On entry, $x$ is not a strictly ordered array.

Notes

fit_spline fits a cubic smoothing spline to a set of $n$ observations ($x_i$, $y_i$), for $i=1,2,\dots ,n$. The spline provides a flexible smooth function for situations in which a simple polynomial or nonlinear regression model is unsuitable.

Cubic smoothing splines arise as the unique real-valued solution function $f$, with absolutely continuous first derivative and squared-integrable second derivative, which minimizes:

$$\sum _{i=1}^n{w}_i{(y_i-f\left(x_i\right))}^2+\rho {\int }_{-\infty }^{\infty }{\left(f^{\prime \prime }\left(x\right)\right)}^{2}dx\text{,}$$

where $w_i$ is the (optional) weight for the $i$th observation and $\rho$ is the smoothing parameter. This criterion consists of two parts: the first measures the fit of the curve, and the second the smoothness of the curve. The value of the smoothing parameter $\rho$ weights these two aspects; larger values of $\rho$ give a smoother fitted curve but, in general, a poorer fit. For details of how the cubic spline can be estimated see Hutchinson and de Hoog (1985) and Reinsch (1967).

The fitted values, $\hat{y}={({\hat{y}}_1,{\hat{y}}_2,\dots ,{\hat{y}}_n)}^T$, and weighted residuals, $r_i$, can be written as

$$\hat{y}=Hy\text{and}{r}_i=\sqrt{w_i}(y_i-{\hat{y}}_i)$$

for a matrix $H$. The residual degrees of freedom for the spline is $trace(I-H)$ and the diagonal elements of $H$, $h_{ii}$, are the leverages.

The parameter $\rho$ can be chosen in a number of ways. The fit can be inspected for a number of different values of $\rho$. Alternatively the degrees of freedom for the spline, which determines the value of $\rho$, can be specified, or the (generalized) cross-validation can be minimized to give $\rho$; see fit_spline_parest() for further details.

fit_spline requires the $x_i$ to be strictly increasing. If two or more observations have the same $x_i$-value then they should be replaced by a single observation with $y_i$ equal to the (weighted) mean of the $y$ values and weight, $w_i$, equal to the sum of the weights. This operation can be performed by data_order().

The computation is split into three phases.

1. Compute matrices needed to fit spline.

2. Fit spline for a given value of $\rho$.

3. Compute spline coefficients.

When fitting the spline for several different values of $\rho$, phase (1) need only be carried out once and then phase (2) repeated for different values of $\rho$. If the spline is being fitted as part of an iterative weighted least squares procedure phases (1) and (2) have to be repeated for each set of weights. In either case, phase (3) will often only have to be performed after the final fit has been computed.

The algorithm is based on Hutchinson (1986).

References

Hastie, T J and Tibshirani, R J, 1990, Generalized Additive Models, Chapman and Hall

Hutchinson, M F, 1986, Algorithm 642: A fast procedure for calculating minimum cross-validation cubic smoothing splines, ACM Trans. Math. Software (12), 150–153

Hutchinson, M F and de Hoog, F R, 1985, Smoothing noisy data with spline functions, Numer. Math. (47), 99–106

Reinsch, C H, 1967, Smoothing by spline functions, Numer. Math. (10), 177–183