```help rcsgen
-------------------------------------------------------------------------------

Title

rcsgen --       Generate restriced cubic splines and derivatives

Syntax

rcsgen varname [if] [in] [, options]

options                Description
-------------------------------------------------------------------------
Options
gen(stub)            stubname for generated spline variables
dgen(stub)           stubname for generated derivatives of spline
variables
knots(numlist)       location of knots
percentiles(numlist) location of knots using percentiles
df(#)                degrees of freedom for knots
bknots(numlist)      location of boundary knots
orthog               orthogonalize generates spline variables
rmatrix(matname)     use supplied matrix for orthogonalization
if2(string)          use extra condition when generating knots using df
or percentile options
fw(varname)          name of variable containing weights when
generating knots using the df or percentile
options
reverse              derives the spline variables in reversed order
scalar(#)            a single value to calculate the spline basis for

One (and only one) of the knots, percentiles or df options should be
specified. If they are not then only 1 variable is created which is a
copy of varname.

Description

rcsgen generates basis functions for restricted cubic splines and
(optionally) their derivatives. Restriced cubic spline functions assume
linearity beyond the two boundary knots. It is possible to specify knots
on the original scale, as default percentiles or user specified
pecentiles. Orthogonalization can be peformed using Gram-Schmidt
orthogonalization. When orthogonalizing, a matrix is returned, which can
be useful for regenerating the orthogonalized spline variables for out of
sample predictions.

Options

gen(stub) gives a stubname for the generated cubic splines variables. For
example, gen(rcs) will create variable rcs1, rcs2, ....

dgen(stub) gives a stubname for the derivatives of the restricted cubic
splines variables. For example, dgen(drcs) will create variable
drcs1, drcs2, ....

knots(numlist) list of the location of the knots. The boundary knots are
included in the numlist.

percentiles(numlist) list of percentiles for the location of the knots.
The boundary knots are included in the numlist.

df(#) sets the desired degrees of freedom (df). The number of knots is
one less than the df.  Knots are placed at equally spaced centiles of
the distribution of varname.  For example, for df(5) knots are placed
at the 20th, 40th, 60th, 80th centiles of the distribution of
varname.  In addition boundary knots are placed at the maximum and
minimum values of varname or those specified using the bknots()
option.

bknots(numlist) list of boundary knots when using the df() option. By
default these are the minimum and maximum of the varname

orthog will orthogonalize the generated spline variables using
Gram-Schmidt orthogonalization.

rmatrix(matname) will orthogonalize the generated spline variables using
the supplied R matrix. If X is the N*p matrix of untransformed spline
variables and Q is the N*(p+1) matrix of orthogonlized variables plus
a column of ones, then X=QR.

if2(condition) supplies a condition when generating the knots using the
df or percentile options.  For example in survival (time-to-event)
data when using splines for the time scale it is common to calculate
the knot locations based on the distribution of uncensored event
times.

fw(weight) gives the name of the variable containing weights when
generating knots using df or percentile options.

reverse will make the spline variables to be derived in reversed order,
treating the last knot as the first and the first knot as the last.
This can be used to add a constraint to a regression model for a
constant effect after the last knot.

scalar will calculate the spline variables for a single value and store
the results in a series of Stata scalars.  It is useful when
obtaining in or out of sample predictions in large datasets and you
want to predict at a certain value of varname.

Example:
You can specify where to position the knots.

. rcsgen x, knots(10 30 50 70 90) gen(rcs)

Alternatively, you can generate the knots positions according to the
distribution of varname.  In the example below the df(3) option is used
which means that 4 knots are used at 0th 33rd 67th and 100th centiles of
weight.

. sysuse auto, clear
. rcsgen weight, gen(rcs) df(3)
. regress mpg rcs1-rcs3
. predictnl pred = xb(), ci(lci uci)
. twoway (rarea lci uci weight, sort) ///
(scatter mpg weight, sort) ///
(line pred weight, sort lcolor(black)), legend(off)
(click to run)

Authors

This command is based on rcs written by Chris Nelson (cn46@le.ac.uk) that
comes with the strsrcs command available from SSC.

Paul Lambert (paul.lambert@le.ac.uk) added the percentile, rmatrix, if2, fw
and scalar options. He also wrote the mata code for the Gram-Schmidt
orthogonalization (as opposed to using the orthog command).

Mark Rutherford (mjr40@le.ac.uk) added the df and bknots options.