FinanceModels.Spline API Reference

Spline is a module which offers various degree splines used for fitting or bootstraping curves via the fit function.

Available methods:

• Spline.PolynomialSpline(n) where n is the nth order: linear, quadratic, or natural cubic interpolation for orders 1, 2, or 3. Linear is local: each segment depends only on its two end knots. Quadratic and natural cubic splines are global: moving one knot changes every segment. All are fast and thread-safe to evaluate.
• Spline.BSpline(d) where d is the polynomial degree. A degree-d B-spline produces (d-1)th-order-continuous piecewise polynomials. That is, degree 2/3 is very similar to a quadratic/cubic spline respectively. BSplines are global in that a change in one point affects the entire spline (though the spline still passes through the other given points still). Useful as a basis for least-squares fitting, but not thread-safe for concurrent evaluation — see Spline.BSpline.

This object is not a fitted spline itself, rather it is a placeholder object which will be a spline representing the data only after using within fit.

Convenience methods which create a Spline.PolynomialSpline of the appropriate order (fast and safe to evaluate concurrently; Spline.Linear also gives the best key-rate locality):

• Spline.Linear() equals PolynomialSpline(1) (numerically identical to BSpline(1))
• Spline.Quadratic() equals PolynomialSpline(2)
• Spline.Cubic() equals PolynomialSpline(3)

For a global B-spline (e.g. as a basis for smooth least-squares fitting) use Spline.BSpline(d) explicitly, noting its thread-safety caveat.

Knot-based yield curves built from these descriptors extrapolate flat-forward beyond their last knot by default: the instantaneous forward is held at the last discrete forward (the average forward over the last knot interval; Spline.MonotoneConvex() uses its own boundary instantaneous forward instead). Pass extrapolation=:flat_zero, :linear, :extension, or Yield.FlatForwardAt(rate) to Yield.Spline, ZeroRateCurve, or spline fit methods to select a different long-end policy. :extension is unavailable for MonotoneConvex.

Notes on Fitting:

• fit(spline,quotes) will fit entire curve at once, with knots equal to the maturity points of the Quotes
• fit(spline, quotes, Fit.Bootstrap()) solves one knot at a time with Spline.Linear(). Other strategies require full-curve loss fitting because adding a knot changes earlier segments.

Generally, the former will be preferred for performance reasons.

Examples

using FinanceModels
using BenchmarkTools
rates = [0.07, 0.16, 0.35, 0.92, 1.4, 1.74, 2.31, 2.41] ./ 100
mats = [1, 2, 3, 5, 7, 10, 20, 30]

qs = CMTYield.(rates, mats)
c = fit(Spline.Linear(), qs) # will fit entire curve at once, with knots equal to the maturity points of the `Quote`s
c = fit(Spline.Linear(), qs, Fit.Bootstrap()) # will curve one knot at a time, with knots equal to the maturity points of the `Quote`s

Spline.Akima()

Akima (1970) interpolation. Local and resistant to outlier-induced oscillation: each segment depends on a few neighboring points. Produces C1-continuous curves.

Compared to PCHIP, Akima can produce slightly different shapes near inflection points. Both are local; PCHIP additionally preserves monotonicity.

Spline.BSpline(d)

A degree-dglobal B-spline, used primarily as a basis for least-squares curve fitting. A degree-d B-spline produces (d-1)th-order-continuous piecewise polynomials, so degree 2/3 resembles a quadratic/cubic spline. B-splines are global: changing one input point perturbs the entire curve (though it still passes through the other given points).

For interpolating an already-known curve, prefer the convenience constructors (Spline.Cubic() etc.): they build faster and are thread-safe.

d must be at least 1: a degree-0 B-spline is a step function of the zero rate, so discount factors would jump at every knot.

On a short grid the degree is reduced: with k knots, a degree-d B-spline interpolates at degree min(d, k - 1), and with fewer than three knots its knot vector is uniform rather than averaged. One knot gives a flat curve.

Spline.MonotoneConvex()

Hagan-West (2006) monotone convex interpolation. With the default :flat_forward extrapolation, it guarantees positive continuous forward rates when input rates imply positive discrete forwards, and matches discrete forward rates at knot points. Produces the best KRD locality among smooth methods.

Other extrapolation policies change only the tail beyond the last knot. They can introduce a forward jump at that knot or negative forwards in the tail; the interior guarantees remain.

Unlike other SplineCurve types that wrap DataInterpolations, this dispatches to Yield.MonotoneConvex which implements the Hagan-West sector-based polynomial construction. Loss-fitting this descriptor returns that native curve for every supported extrapolation policy; Fit.Bootstrap() rejects it.

References

• Hagan & West, "Interpolation Methods for Curve Construction", Applied Mathematical Finance (2006)

Spline.PCHIP()

Piecewise Cubic Hermite Interpolating Polynomial (PCHIP). Local and monotonicity-preserving: each segment depends only on its immediate neighbors, so bumping one rate has bounded effect. Produces C1-continuous curves (continuous first derivative), giving smooth forward rates without the non-local coupling of cubic splines.

The default interpolation for ZeroRateCurve is Spline.MonotoneConvex; PCHIP is a good local, monotonicity-preserving alternative.

Spline.PolynomialSpline(order)

A polynomial interpolating spline of the given order, backed by DataInterpolations (order 1 → LinearInterpolation, 2 → QuadraticSpline, 3 → natural CubicSpline). Order 1 is local: each segment depends only on its two end knots, so bumping one knot moves only the adjacent segments. Orders 2 and 3 are global: bumping one knot moves every segment. All orders are thread-safe to evaluate concurrently.

The convenience constructors Spline.Linear, Spline.Quadratic, and Spline.Cubic return PolynomialSpline(1/2/3). Any other order throws an ArgumentError.

On a short grid the order is reduced: with k knots, an order-n spline interpolates at order min(n, k - 1), so a cubic spline through two knots is linear and one knot gives a flat curve. A fit places one knot per quote, so fit(Spline.Cubic(), quotes) with two quotes returns a linear curve.

Spline.Cubic()

Create a natural cubic spline (returns PolynomialSpline(3), backed by the global DataInterpolations.CubicSpline). This object is not a fitted spline itself, rather it is a placeholder which becomes a spline only after use within fit, or when passed to ZeroRateCurve.

Differs numerically from BSpline(3) (a global cubic B-spline); use Spline.BSpline(3) to recover the previous behavior. This form builds faster and is thread-safe. Its coefficients depend on the whole knot grid, so bumping one knot can affect other intervals. With three knots it is quadratic, with two linear, and with one flat (see Spline.PolynomialSpline).

Returns

• A PolynomialSpline object representing a cubic spline.

Examples

julia> Spline.Cubic()
PolynomialSpline(3)

Spline.Linear()

Create a local linear spline (returns PolynomialSpline(1), backed by DataInterpolations.LinearInterpolation). This object is not a fitted spline itself, rather it is a placeholder which becomes a spline only after use within fit, or when passed to ZeroRateCurve.

Numerically identical to BSpline(1), with local knot-rate sensitivities within the knot grid and thread-safe evaluation (Spline.BSpline carries a thread-safety caveat for concurrent evaluation).

Returns

• A PolynomialSpline object representing a linear spline.

Examples

julia> Spline.Linear()
PolynomialSpline(1)

Spline.Quadratic()

Create a quadratic spline (returns PolynomialSpline(2), backed by the global DataInterpolations.QuadraticSpline). This object is not a fitted spline itself, rather it is a placeholder which becomes a spline only after use within fit, or when passed to ZeroRateCurve.

Differs numerically from BSpline(2) (a global quadratic B-spline); use Spline.BSpline(2) to recover the previous behavior. This piecewise polynomial form is thread-safe. With two knots it is linear, and with one it is flat (see Spline.PolynomialSpline).

Returns

• A PolynomialSpline object representing a quadratic spline.

Examples

julia> Spline.Quadratic()
PolynomialSpline(2)