-------------------------------------------------------------------------------
help for rcspline
-------------------------------------------------------------------------------

Restricted cubic spline smoothing

        rcspline yvar xvar [if] [in] [weight] [ , mkspline_options stub(stub)
            regressopts(regress_options) generate(newvar)
            scatter(scatter_options) ci[(rarea_options)] level(#) showknots
            mspline_options addplot(plot) ]

    fweights are allowed; see weight.


Description

    rcspline computes and graphs a restricted cubic spline smooth of yvar
    given xvar.


Remarks

    rcspline calls mkspline, cubic to create variables containing a
    restricted cubic spline of xvar.  It then calls regress to regress yvar
    against those new variables, and thus obtains predicted (smoothed) values
    of yvar given xvar.  Finally, it calls graph to plot data and smooth.

    R-square (squared correlation coefficient) and RMSE (root mean square
    error) are provided as goodness of fit indicators.  However, these can
    typically be 'improved' simply by smoothing less, which is often likely
    to be unhelpful. As the resulting predictions come closer to
    interpolating the data, R-square will increase, and RMSE will decrease,
    but scientific usefulness and the possibility of insight will usually
    diminish.

    More generally, the main intended usage of rcspline is for informal
    exploratory analysis in which relationships are checked for linearity or
    nonlinearity and appropriate transformations or link functions are
    considered. More formal uses would require specification of the stub()
    option to save the variables created. Some consideration might need to be
    given to the implications of any data snooping.


Options 

    mkspline_options are options of mkspline, cubic.

        nknots() specifies the number of knots that are to be used for a
        restricted cubic spline.  This number must be between 3 and 7 unless
        the knot locations are specified using knots().  The default number
        of knots is 5.

        knots() specifies the exact location of the knots to be used for a
        restricted cubic spline.  The values of these knots must be given in
        increasing order.  When this option is omitted, the default knot
        values are based on Harrell's recommended percentiles with the
        additional restriction that the smallest knot may not be less than
        the fifth-smallest value of xvar and the largest knot may not be
        greater than the fifth-largest value of xvar.  If both nknots() and
        knots() are given, they must specify the same number of knots.

    stub(stub) specifies that the variables containing the spline be saved in
        variables with prefix stub.  This option is essential if rcspline is
        to be followed by regress.

    regressopts() contains options of regress. It is difficult to know why
        you would want to specify any.

    generate(newvar) specifies that smoothed values be saved in a new
        variable newvar.

    scatter() specifies options allowed by the scatter command.  These should
        be specified to control the rendering of the data points.

    mspline_options are any of the options allowed with twoway mspline.
        These should be specified to control the rendering of the smooth or
        the overall graph.

    showknots specifies that the positions of the knots be shown on the graph
        by vertical lines.

    ci[(rarea_options)] specifies that confidence intervals based on the
        standard error of the linear prediction be shown. ci may be specified
        with options of twoway rarea to tune the display of the confidence
        interval.

    level() specifies a confidence level to use for confidence intervals. See
        help on level.

    addplot(plot) provides a way to add other plots to the generated graph.
        See help on addplot_option.


Examples 

    . rcspline mpg weight

    . rcspline mpg weight, scatter(ms(oh))

    . rcspline mpg weight, generate(Smpg)

    . rcspline mpg weight, ci(color(ltblue)) clw(medthick)

    . rcspline mpg weight, addplot(lowess mpg weight)


Saved results 

    r(N_knots)   number of knots (scalar) 
    r(knots)     knot positions (matrix) 


Author 

    Nicholas J. Cox
    Durham University
    n.j.cox@durham.ac.uk


Acknowledgments 

    A question from José Maria Pacheco de Souza on Statalist led to the
    addition of saved r-class results as above.


Also see

    Online: lowess, lpoly, mvrs (if installed)