help for bspline, frencurv and flexcurv (STB-57: sg151; Roger Newson)

B-splines and splines parameterized by their values at reference points

bspline [newvarlist] [if] [in] , xvar(varname)
[ power(#)
knots(numlist) noexknot
generate(prefix) type(type)
labfmt(format)
labprefix(string)
]

frencurv [newvarlist] [if] [in] , xvar(varname)
[ power(#)
refpts(numlist) noexref omit(#) base(#)
knots(numlist) noexknot
generate(prefix) type(type)
labfmt(format)
labprefix(string)
]

flexcurv [newvarlist] [if] [in] , xvar(varname)
[ power(#)
refpts(numlist) omit(#) base(#)
include(numlist) krule(knot_rule)
generate(prefix) type(type)
labfmt(format)
labprefix(string)
]

where knot_rule is

regular | interpolate

Description

The bspline package contains 3 commands, bspline, frencurv and flexcurv.
bspline generates a basis of B-splines in the X-variate based on a list of knots,
for use in the design matrix of a regression model.
frencurv generates a basis of reference splines,
for use in the design matrix of a regression model,
with the property that the parameters fitted will be values of the spline at a list of reference points.
flexcurv is an easy-to-use version of frencurv,
and generates reference splines with regularly-spaced knots,
or with knots interpolated between the reference points.
frencurv and flexcurv have the additional option of generating an incomplete basis of reference splines,
which can be completed by the addition of the standard constant variable used in regression models.
The splines are either given the names in the newvarlist (if present),
or (more usually) generated as a list of numbered variables,
prefixed by the generate() option.
Usually (but not always),
the regression command is called using the noconst option.

Options for use with bspline and frencurv

xvar(varname) specifies the X-variate on which the splines are based.

power(#) (a non-negative integer) specifies the power (or degree) of the splines.
Examples are zero for constant, 1 for linear, 2 for quadratic, 3 for cubic, 4 for quartic or 5 for quintic.
If absent, zero is assumed.

knots(numlist) specifies a list of at least 2 knots,
on which the splines are based.
If knots() is absent,
then bspline will initialize the list to the minimum and maximum of the xvar() variable,
and frencurv will create a list of knots equal to the reference points
(in the case of odd-degree splines such as a linear, cubic or quintic)
or midpoints between reference points (in the case of even-degree splines such as constant, quadratic or quartic).
flexcurv does not have the knots() option,
as it automatically generates a list of knots,
containing the required number of knots "sensibly" spaced on the xvar() scale.

noexknot specifies that the original knot list is not to be extended.
If noexknot is not specified,
then the knot list is extended on the left and right by a number of extra knots on each side specified by power(),
spaced by the distance between the first and last 2 original knots, respectively.
flexcurv does not have the noexknot option,
as it specifies the knots automatically.

generate(prefix) specifies a prefix for the names of the generated splines,
which (if there is no newvarlist)
will be named as prefix1...prefixN where N is the number of splines.

type(type) specifies the storage type of the splines generated
(float or double).
If type() is given as anything else (or not given), then it is set to float.

labfmt(format) specifies the format to be used in the variable labels for the generated splines.
If absent, then it is set to the format of the xvar() variable.

labprefix(string) specifies the prefix to be used
in the variable labels for the generated splines.
If absent, then it is set to "Spline at " for flexcurv and frencurv,
and to "B-spline on " for bspline.

Options for use with frencurv

refpts(numlist) specifies a list of at least 2 reference points,
with the property that, if the splines are used in a regression model,
then the fitted parameters will be values of the spline at those points.
If refpts() is absent, then the list is initialized to a list of two points,
equal to the minimum and maximum of the xvar() variable.
If the omit() option is specified with flexcurv or frencurv,
and the spline corresponding to the omitted reference point
is replaced with a standard constant term in the regression model,
then the fitted parameters will be relative values of the spline (differences or ratios),
compared to the value of the spline at the omitted reference point.

noexref specifies that the original reference list is not to be extended.
If noexref is not specified, then the reference list is extended on the left and right
by a number of extra reference points on each side equal to int(power/2),
where power is the value of the power() option,
spaced by the distance between the first and last 2 original reference points, respectively.
If noexref and noexknot are both specified,
then the number of knots must be equal to the number of reference points plus power+1.
flexcurv does not have the noexref option,
as it automatically chooses the knots and does not extend the reference points.

omit(#) specifies a reference point,
which must be present in the refpts() list (after any extension requested by frencurv),
and whose corresponding reference spline will be omitted from the set of generated splines.
If the user specifies omit(),
then the set of generated splines will not be a complete basis
of the set of splines with the specified power and knots,
but can be completed by the addition of a constant variable,
equal to 1 in all observations.
If the user then uses the generated splines as predictor variables for a regression command,
such as regress or glm,
then the noconst option should usually not be used,
and, if the omitted reference point is in the completeness region of the basis,
then the intercept parameter _cons will be the value of the spline at the omitted reference point,
and the model parameters corresponding to the generated reference splines
will be differences
between the values of the spline at the corresponding reference points
and the value of the spline at the omitted reference point.
If omit() is not specified,
then the generated reference splines form a complete basis
of the set of splines with the specified power and knots.
If the user then uses the generated splines as predictor variables for a regression command,
such as regress or glm,
then the noconst option should be used,
and the fitted model parameters corresponding to the generated splines
will be the values of the spline at the corresponding reference points.

base(#) is an alternative to omit()
for use in Stata Versions 11 or higher.
It specifies a reference point,
which must be present in the refpts() list (after any extension requested by frencurv),
and whose corresponding reference spline will be set to zero.
If the user specifies base(),
then the set of generated splines will not be a complete basis
of the set of splines with the specified power and knots,
but can be completed by the addition of a constant variable,
equal to 1 in all observations.
The generated splines can then be used in the design matrix by an estimation command
in Stata Versions 11 or higher.

Options for use with flexcurv only

Note that flexcurv also uses all the options available to frencurv,
except for knots(), noexknot, and noexref.

include(numlist) specifies a list of additional numbers
to be included within the boundaries of the completeness region of the spline basis,
in addition to the available values of the xvar() variable
and the refpts() values (if provided).
This allows the user to specify a non-default supremum and/or infimum
for the completeness region of the spline basis.
If include() is not provided,
then the completeness region will extend from the minimum to the maximum
of the values either available in the xvar() variable
or specified in the refpts() list.

krule(knot_rule) specifies a rule for generating knots,
based on the reference points,
which may be regular (the default) or interpolate.
If regular is specified,
then the knots are spaced regularly over the completeness region of the spline.
If interpolate is specified,
then the knots are interpolated between the reference points,
in a way that produces the same knots as krule(regular)
if the reference points are regularly spaced.
Whichever krule() option is specified,
any extra knots to the left of the completeness region are regularly spaced
with a spacing equal to that between the first 2 knots of the completeness region,
and any extra knots to the right of the completeness region are regularly spaced
with a spacing equal to that between the last 2 knots of the completeness region.
Therefore, krule(regular) specifies that all knots will be regularly spaced,
whether or not the reference points are regularly spaced,
whereas krule(interpolate) specifies that the knots will be interpolated
between the reference points
in a way that will cause reference splines to be definable,
even if the reference points are not regularly spaced.

Remarks

The splines generated are intended for use in the varlist of an estimation
command (eg regress or glm), typically with a noconst option
(except if the omit() or base() option is specified with frencurv or flexcurv).
The rules look complicated,
but they are designed to give simple defaults for most users
(especially if flexcurv is used),
and also a powerful choice of options for programmers and advanced users.
The principles and definitions of B-splines are given in de Boor (1978) and Ziegler (1969).
frencurv and flexcurv calculate the reference splines by calling bspline
to calculate B-splines based on the reference points, the xvar() variable,
and the include() option (if supplied to flexcurv),
and then invert the matrix of the B-splines for the reference points to generate a transformation matrix,
which is then used to transform the B-splines to reference splines.
The principles and definitions of reference splines are given in detail in
Newson (2012), Newson (2011), Newson (2001) and Newson (2000).

Full documentation of the bspline package (including Methods and Formulas)
is provided in the file bspline.pdf,
which is distributed with the bspline package as an ancillary file
(see help for net).
It can be viewed using the Adobe Acrobat Reader, which can be downloaded from
http://www.adobe.com/products/acrobat/readermain.html.

Examples

These examples demonstrate the fitting of a spline model of mpg with respect to weight
in the auto dataset shipped with official Stata.

Set-up:

. sysuse auto, clear

. describe

The following example demonstrates the use of flexcurv
to define a basis of cubic reference splines in weight,
with regularly-spaced knots and regularly-spaced reference points.
We then use regress, with the noconst option,
to fit a spline regression model,
whose parameters (cs1 to cs5)
are the values of the spline at the reference points,
each equal to the estimated conditional mean of mpg
for cars with weight equal to the corresponding reference point.
Differences between conditional means can then be estimated (with confidence limits),
using lincom.
Finally, we use predict to compute the predicted values of mpg for all cars,
and plot the observed and fitted values of mpg against weight.

. flexcurv, xvar(weight) refpts(1760(770)4840) gen(cs) power(3)

. describe cs*

. regress mpg cs*, robust noconst

. lincom cs3-cs5

. predict mpghat3

. scatter mpg weight, msym(circle_hollow) || line mpghat3 weight, sort ||, xlab(1760(770)4840) ylab(0(5)45) legend(row(1))

The following example demonstrates the use of flexcurv with the omit() option
to fit the same model as the previous example,
generating an incomplete basis of reference splines
by omitting the reference spline for a weight of 1760 US pounds.
We then use regress without the noconst option
to fit the spline model.
The parameters, in this case, are the constant term _cons,
equal to the conditional mean mpg for cars with the omitted weight of 1760 US pounds,
and the cubic spline parameters cs2 to cs5,
equal to the difference, in conditional means of mpg,
between cars with a weight equal to the corresponding reference point
and cars with a weight equal to the omitted reference point of 1760 US pounds.
Again, we can use lincom to estimate differences between means for non-omitted reference points,
and we can use predict to compute the fitted values of weight,
which are the same as in the previous example.

. flexcurv, xvar(weight) refpts(1760(770)4840) omit(1760) gen(ics) power(3)

. describe ics*

. regress mpg ics*, robust

. lincom ics3-ics5

. predict mpghat3a

. scatter mpg weight, msym(circle_hollow) || line mpghat3a weight, sort ||, xlab(1760(770)4840) ylab(0(5)45) legend(row(1))

The following example demonstrates the use of frencurv
to fit the same model again,
this time with reference points equal to the knots
in and around the completeness region of the spline.
This has the consequence that the list of reference points
is extended on the left and on the right
by adding 2 reference points outside the completeness region,
whose corresponding spline parameters represent the behavior of the spline
as it converges back to zero outside its completeness region.
These 2 extra parameters are not easy to explain to non-mathematicians.

. frencurv, xvar(weight) refpts(1760 3300 4840) gen(kcs) power(3)

. describe kcs*

. regress mpg kcs*, robust noconst

. predict mpghat3b

. scatter mpg weight, msym(circle_hollow) || line mpghat3b weight, sort ||, xlab(1760 3300 4840) ylab(0(5)45) legend(row(1))

The following example uses frencurv to fit the same model as the previous example,
using the omit() option to omit the reference
spline corresponding to the reference point (and knot) at 1760 US pounds.
This time, the parameter _cons represents the mileage at 1,760 uS pounds,
the parameters ikcs2 and ikcs3 represents the differences
between the mileages at 3,300 and 4,840 US pounds (respectively)
and the mileage at 1,760 pounds,
and the parameters ikcs1 and ikcs5 represent the behavior of the spline
as it converges back to zero outside its completeness region.

. frencurv, xvar(weight) refpts(1760 3300 4840) omit(1760) gen(ikcs) power(3)

. describe ikcs*

. regress mpg ikcs*, robust

. predict mpghat3c

. scatter mpg weight, msym(circle_hollow) || line mpghat3c weight, sort ||, xlab(1760 3300 4840) ylab(0(5)45) legend(row(1))

The following example demonstrates the use of bspline
to fit the same model as the previous examples,
generating a basis of Schoenberg B-splines.
We then use regress with the noconst option
to fit the spline model.
The parameters, in this case, correspond to the B-splines,
and are again expressed in units of the Y-variable mpg.
They are not easy to interpret in a way that non-mathematicians will understand,
and nor are the differences between parameters that might be estimated using lincom.
However, we can still use predict to compute fitted values for mpg,
which (together with the observed values) can be plotted against weight exactly as before.

. bspline,xvar(weight) knots(1760 3300 4840) gen(bs) power(3)

. describe bs*

. regress mpg bs*, robust noconst

. predict mpghat3d

. scatter mpg weight, msym(circle_hollow) || line mpghat3d weight, sort ||, xlab(1760 3300 4840) ylab(0(5)45) legend(row(1))

Saved results

bspline, frencurv and flexcurv save the following results in r():

Scalars

r(xsup) upper bound of completeness region

r(xinf) lower bound of completeness region

r(nincomp) number of X-values out of completeness region

r(nknot) number of knots

r(nspline) number of splines

r(power) power (or degree) of splines

Macros

r(knots) final list of knots

r(splist) varlist of generated splines

r(labfmt) format used in spline variable labels

r(labprefix) prefix used in spline variable labels

r(type) storage type of splines (float or double)

r(xvar) X-variable specified by xvar() option

Matrices

r(knotv) row vector of knots

frencurv and flexcurv save all of the above results in r(), and also the following:

Scalars

r(omit) omitted reference point specified by omit()

r(base) base reference point specified by base()

Macros

r(refpts) final list of reference points

Matrices

r(refv) row vector of reference points

The result r(nincomp) is the number of values of the xvar() variable
outside the completeness region of the space of splines defined by the reference splines or B-splines.
The number lists r(knots) and r(refpts) are the final lists
after any left and right extensions carried out by bspline, frencurv or flexcurv,
and the vectors r(knotv) and r(refv) contain the same values in double precision
(mainly for programmers).
The scalars r(xinf) and r(xsup) are knots,
such that the completeness region is r(xinf) <= x <= r(xsup) for positive-degree splines
and r(xinf) <= x < r(xsup) for zero-degree splines.

In addition, bspline, frencurv and flexcurv save variable characteristics
for the output spline basis variables.
The characteristic varname[xvar] is set by bspline, frencurv and flexcurv
to be equal to the input X-variable name set by xvar().
The characteristics varname[xinf] and varname[xsup]
are set by bspline to be equal to the infimum and supremum, respectively,
of the interval of X-values for which the B-spline is non-zero.
The characteristic varname[xvalue] is set by frencurv and flexcurv
to be equal to the reference point on the X-axis corresponding to the reference spline.
The characteristic varname[basestat] is set by frencurv and flexcurv
to be 1 if the reference point on the X-axis corresponding to the reference spline
is equal to the base() option,
and to be 0 otherwise.

Author

Roger Newson, King's College London, UK.
Email: roger.newson@kcl.ac.uk

References

de Boor C. 1978.
A Practical Guide to Splines.
New York: Springer Verlag.

Newson R. B. 2012.
Sensible parameters for univariate and multivariate splines.
The Stata Journal 12(3): 479-504.
Download from
http://www.stata-journal.com/article.html?article=sg151_2.

Newson R. B. 2011.
Sensible parameters for polynomials and other splines.
Presented at the 17th UK Stata User Meeting, 15-16 September, 2011.
Download from
http://ideas.repec.org/p/boc/usug11/01.html.

Newson R. 2001.
Splines with parameters that can be explained in words to non-mathematicians.
Presented at the 7th UK Stata User Meeting, 14–15 May, 2001.
Download from
http://ideas.repec.org/p/boc/usug01/11.html.

Newson R. 2000.
sg151: B-splines and splines parameterized by their values at reference points on the X-axis.
Stata Technical Bulletin 57: 20-27.
Reprinted in Stata Technical Bulletin Reprints, vol. 10, pp. 221-230.
Download from
http://www.stata.com/products/stb/journals/stb57.html.

Ziegler Z. 1969.
One-Sided L_1-Approximation by Splines of an Arbitrary Degree.
In: Schoenberg I. J. (ed.) 1969.
Approximations with Special Emphasis on Spline Functions.
New York: Academic Press.

Also see

Manual: [R] mkspline

On-line: help for mkspline

help for spline, spbase, sp_adj if installed