help for polyspline(Roger Newson)

Generate sensible bases for polynomials and other splines

polyspline varname [if] [in] , generate(prefix)
[ refpts(numlist) power(#)
omit(#) base(#)
include(numlist)
type(type)
labfmt(format)
labprefix(string)
]

Description

The polyspline package inputs an X-variable
and a list of reference points on the X-axis,
and generates a basis of reference splines (one per reference point)
for a polynomial or other unrestricted spline.
This basis can be included in the list of covariates of a regression model.
The estimated parameters will then be values of the spline at the reference points,
or differences between values of the spline at the reference points
and the value of the spline at a base reference point.
polyspline is an easy-to-use front end for the SSC package bspline,
which must be installed for polyspline to work.

Options for polyspline

generate(prefix) must be specified.
It specifies a prefix for the names of the generated splines,
which will be named as prefix1...prefixN,
where N is the number of reference points.

refpts(numlist) specifies a list of at least 2 reference points.
If the generated splines are used in a regression model,
then the fitted parameters will be values of the spline at those points,
or differences between those values and the value of the spline at a base reference point
specified by the base() option or the omit() option.
If refpts() is absent, then the list is initialized to a list of two points,
equal to the minimum and maximum of the completeness range,
which is the range of X-values
for which the spline basis is valid.

power(#) (a positive integer)
specifies the power (or degree) preferred for the generated splines.
Examples are 1 for linear, 2 for quadratic, 3 for cubic, 4 for quartic or 5 for quintic.
If absent, power() is set to q-1, where q is the number of reference points,
implying that the spline in the regression model will simply be a polynomial.
If power() is specified as being equal to, or greater than,
the number of reference points,
then it is revised downwards to be one less than the number of reference points,
because the number of reference points is then too small to define a polyomial
of the power originally requested.

base(#) is used in Stata Versions 11 or higher.
It specifies a reference point,
which must be present in the refpts() list,
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,
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 list of covariates for an estimation command
in Stata Version 11 or higher,
without the nocoonst option.
The correspondiing parameters will then be differences
between the values of the spline at the reference points
and the value of the spline at the base() reference point.
If the user does not specify a base() or omit() option,
then the regression command should usually have a noconst option.
The corresponding parameters will then simply be values
of the spline at the reference points.

omit(#) is an alternative to the base() option,
for use in Stata Version 10.
It specifies a reference point,
which must be present in the refpts() list,
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,
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 list of covariates for an estimation command
in Stata Version 10,
without the nocoonst option.
The correspondiing parameters will then be differences
between the values of the spline at the reference points
and the value of the spline at the omit() reference point.
If the user does not specify a base() or omit() option,
then the regression command should usually have a noconst option.
The corresponding parameters will then simply be values
of the spline at the reference points.

include(numlist) specifies a list of additional numbers
to be included within the boundaries of the completeness region of the spline basis,
which is the interval on the X-axis in which the generated splines are valid.
This completeness region will always include the available values of the input X-variable,
and also the refpts() values.
The include() option allows the user to specify a non-default minimum and/or maximum
for the completeness region.

type(type) specifies the storage type of the generated splines
(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 reference splines.
If absent, then it is set to the format of the input X-variable.

labprefix(string) specifies the prefix to be used
in the variable labels for the generated reference splines.
If absent, then it is set to "Spline at ".

Remarks

polyspline is described in Newson (2014).
The splines generated are intended for use in the varlist of an estimation
command (eg regress or glm).
The model whose parameters are estimated
will then be a polynomial
(if the power() option is unspecified or equal to the number of reference points minus one),
or an unrestricted spline of degree specified by the power() option,
with knots interpolated between the reference points
(if the power() option is less than the number of reference points minus one).

If polyspline has no base() or omit() option
and the estimation command has a noconst option,
then the estimated model parameters corresponding to the generated splines
will be values of the polynomial or spline at the reference points.
If polyspline has a base() or omit() option
and the estimation command has no noconst option,
then the estimated parameters corresponding to the generated splines
will be differences between the values of the spline at the reference points
and the value of the spline at the base reference point.
These parameters will be easier to understand
than the usual parameters for a polynomial
(expressed in Y-axis units per power-raised X-axis unit),
and will be much easier to understand
than the usual parameters for other unrestricted splines
(usually expressed in even more alien units).

polyspline works by calling the flexcurv module of the bspline package,
which can be downloaded from SSC.
The principles and definitions of reference splines, and of the bspline package,
are given in detail in Newson (2012) and Newson (2011).

Technical note

polyspline works by calling flexcurv, using a command of form

flexcurv [if] [in] , xvar(varname) refpts(refpts) power(power)
krule(interpolate)
include(include) omit(omit) base(base)
generate(generate) type(type) labfmt(labfmt) labprefix(labprefix)

where varname is the input X-variable name,
the option value refpts is the value of the refpts() option of polyspline,
the option value power is the value of the power() option of polyspline if supplied
and the number of reference points minus one otherwise,
and the option values include, omit, base,
generate, type, labfmt and labprefix
are the option values passed to the polyspline options of the same names.

Examples

These examples demonstrate the fitting of polynomial and other spline models
of mpg with respect to weight
in the auto dataset supplied with official Stata.

Set-up:

. sysuse auto, clear

. describe

The following example generates a bass for a quadratic model,
with parameters equal to the values of the quadratic
at weights of 1500, 3000 and 5000 US pounds.
We then fit the model,
using regress with the noconst option.

. polyspline weight, gene(qs_) refpts(1500 3000 5000)

. describe qs_*

. regress mpg qs_*, noconst

The following example generates an alternative incomplete basis for the same quadratic model,
using the base() option to specify a base reference weight of 1500 US pounds.
This time, we fit the model using regress without the noconst option.
The parameter for the reference spline at 1500 US pounds is omitted,
because that reference spline is zero in all observations.
The parameter _cons is now the bseline value of mpg,
predicted for cars with a weight of 1500 US pounds.
The parameters for the other reference splines are differences between predicted values of mpg
for cars with the corresponding reference weight
and the predicted value of mpg
for cars with the base reference weight.

. polyspline weight, gene(bqs_) refpts(1500 3000 5000) base(1500)

. describe bqs_*

. regress mpg bqs_*

The following example generates another alternative incomplete basis for the same quadratic model,
using the omit() option to specify a base reference weight of 1500 US pounds.
This time, we fit the model using regress, again without the noconst option.
However, this time, there is no spline for the omitted base reference weight.
The parameter _cons, and the parameters for the other reference splines,
are interpreted as in the previous example.

. polyspline weight, gene(oqs_) refpts(1500 3000 5000) omit(1500)

. describe oqs_*

. regress mpg oqs_*

The following example generates a basis for a quartic model (degree 4),
with reference points at 1000, 2000, 3000, 4000 and 5000 US pounds,
and a base reference weight of 1000 US pounds.
This time, the parameter _cons is a base value of mpg
for cars weighing 1000 US pounds,
and the parameters for the reference splines are differences in mpg
between cars with the other reference weights
and cars with the base reference weight.

. polyspline weight, gene(o4s_) refpts(1000(1000)5000) base(1000)

. describe o4s_*

. regress mpg o4s_*

The following example uses the same 5 reference weights,
and uses the power() option
to specify a linear spline (degree 1),
instead of a quartic spline (degree 4).
The parameters estimated by regress
are interpreted as in the previous example.
However, predicted values are interpolated linearly,
instead of being interpolated quartically.

. polyspline weight, gene(ols_) refpts(1000(1000)5000) base(1000) power(1)

. describe ols_*

. regress mpg ols_*

Saved results

polyspline saves 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

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

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

Macros

r(knots) final list of knots

r(refpts) final list of reference points

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) input X-variable

Matrices

r(knotv) row vector of knots

r(refv) row vector of reference points

The result r(nincomp) is the number of values of the xvar() variable
outside the completeness region,
and should always be zero.
The number lists r(knots) and r(refpts) are the lists of knots and reference points.
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).

In addition, polyspline saves variable characteristics
for the output spline basis variables.
The characteristic varname[xvar] is set
to be equal to the input X-variable name.
The characteristics varname[xinf] and varname[xsup]
are set to be equal to the infimum and supremum, respectively,
of the completeness region.
The characteristic varname[xvalue] is set
to be equal to the reference point on the X-axis corresponding to the reference spline.
The characteristic varname[basestat] is set by polyspline
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

Newson, R. B. 2014.
Easy-to-use packages for estimating rank and spline parameters.
Presented at the 20th UK Stata User Meeting, 11–12 September, 2014.

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.

Also see

Manual: [R] mkspline

On-line: help for mkspline

help for bspline, frencurv, flexcurv if installed