*! version 1.0.0 2023-5-23

stpm3 extended functions

stpm3 allows incorporation of factor variables for both main and time-dependent effects (using the tvc() option).
It also allows various functions for continous variables to be incorporated,
for example, various types of spline functions, polynomials and fractional polynomials,
as well as more general functions.

Using extended functions makes many predictions much simpler. See stpm3_predictions for some examples.

You may type a varlist with factor varibles as follows,

i.varname1 i.varname1

A simple example of an extended function is incorporation of a natural cubic spline function,

i.varname1 @ns(varname2, df(3))

You can include extended functions as interactions with factor variables,

i.varname1 @ns(varname2, df(3)) i.varname1#@ns(varname2, df(3))

The above could also be expressed as,

i.varname1##@ns(varname2, df(3))

You can also have interactions between extended functions.

#@ns(varname1, df(3))#@ns(varname2, df(4))

You can add more general functions as follows,

i.varname1 @fn(expression),stub(name))

For example,

i.varname1 @fn(exp(-0.12*nodes), name(enodes)

The extended functions are

@bs() B-splines

@fp() fractional polynomials

@fn() general function of vaiables(s)

@ns() natural cubic splines

@poly() polynomials

@rcs() restricted cubic splines

These are described in more detail below,

bs() - B-splines

@bs(varname, options)

Options

bknots(numlist) - boundary knots for the B-spline function. By default these are placed
at the minimum and maximum of varname.

center(#) - center the B-spline variables around a single value,
i.e. all spline variables will be equal to zero at this value.

degree(#) - degree of B-spline function - default 3.

df(#) - degrees of freedom, i.e. number of B-splines terms. By default the knots are placed
at evenly distributed centiles of the distribution of varname.

knots(numlist) - list of internal knots for the B-splines. This is to be used when you
do not to use the default knot placments.

winsor(# #, [values]) - will winsorize varname at the specified percentiles before calculating the B-spline variables.
If the value option is used the cutpoints are specified for the actual values of varname rather than percentiles.

Note that one of df() or knots() must be specified.

fp() - fractional polynomial

@fp(varname, options)

Options

powers(numlist) - powers of fractional polynomial, e.g. powers(0 2) includes ln(x) and x^2 in the model.

center(#) - generate FP terms centered on #.

center - generate FP terms centered on the mean of varname. See fp

scale(#a #b) - scale using (varname+#a)/#b. See fp

scale - calculate #a) and #b automatically. See fp

Note that @fp() fits a specific fractional function. It does not search over powers. If you want to do the latter,
then you can use the fp or mfp commands.

fn() - general functions

@fn(expression, options)

Options

stub(numlist) - a name to be added to give a more meaningful name to the function.
For example, @fn(exp(-0.12*nodes)), would give a default variable name of _fn_f1.
However, using @fn(exp(-0.12*nodes), stub(enodes)) would give a variable name, _fn_enodes.

center(#) - center newly created variable on #. Note this centers the output of the function, not the input variable(s).

center - center newly created variable on its mean. Note this centers the output of the function, not the input variable(s).

ns() - natural cubic splines

@ns(varname, options)

Options

bknots(numlist) - boundary knots for the natural cubic spline function.
The function will be linear before the lower boundary knots and after the upper boundary knot.
By default the boundary knots are placed at the minimum and maximum of varname.

center(#) - center the natural cubic spline variables around a single value,
i.e. all spline variables will be equal to zero at this value.

df(#) - degrees of freedom, i.e. number of the natural cubic splines terms

knots(numlist) - list of internal knots for the natural cubic spline function.
This is to be used when you do not to use the default knot placments.

winsor(# #, [values]) - will winsorize varname at the specified percentiles before calculating the natural cubic spline variables.
If the value option is used the cutpoints are specified for the actual values of varname rather than percentiles.

Note that one of df() or knots() must be specified.

poly() - polynomials

@poly(varname, options)

degree(#) - degree of polynomial. This is a compulsory option.

center(#) - generate polynomial terms centered on #.

center - generate polynomial terms centered on the mean of varname.

winsor(# #, [values]) - will winsorize varname at the specified percentiles before calculating the polynomial variables.
If the value option is used the cutpoints are specified for the actual values of varname.

rcs() - restricted cubic splines

@rcs(varname, options)

Options

bknots(numlist) - boundary knots for the restricted cubic spline function.
The function will be linear before the lower boundary knot and after the upper boundary knot.
By default the boundary knots are placed at the minimum and maximum of varname.

center(#) - center the restricted cubic spline variables around a single value,
i.e. all spline variables will be equal to zero at this value.

df(#) - degrees of freedom, i.e. number of restricted cubic splines terms

knots(numlist) - list of internal knots for the restricted cubic spline function.

winsor(# #, [values]) - will winsorize varname at the specified percentiles before calculating the restricted cubic spline variables.
If the value option is used the cutpoints are specified for the actual values of varname rather than percentiles.

Note that one of df() or knots() must be specified. The fitted values when using @ns() or @rcs() will be identical.
The functions differ in the way the spline variables are created.