-------------------------------------------------------------------------------
help for csipolate
-------------------------------------------------------------------------------

Cubic spline interpolation

        csipolate yvar xvar [if exp] [in range] , generate(newvar)

    by ... : may be used with csipolate; see help by.


Description

    csipolate creates newvar by averaging non-missing values of yvar and
    using natural cubic spline interpolation of missing values of yvar, given
    xvar. That is, provided that xvar is not missing,

    1. When yvar is not missing, newvar is the mean of yvar over observations
    with the same value of xvar. If a value of xvar is unique, then each mean
    is just the same as the value of yvar at that point.

    2. When yvar is missing, newvar is filled in using natural cubic spline
    interpolation.


Remarks 

    Extrapolation is not provided. Some users may wish to extrapolate any
    remaining missing values linearly using ipolate.

    csipolate is a wrapper using Mata functions spline3() and spline3eval().
    If desired see help and in turn Mata source code here. That code is a
    translation of code originally given by Herriot and Reinsch (1973).

    The examples are based on the help for ipolate in Stata 10.  Stata 9
    users will need to substitute their own.


Options

    generate() is not optional; it specifies the name of the new variable to
        be created.


Examples

    ---------------------------------------------------------------------------
    Setup
        . webuse ipolxmpl1

    List the data
        . list, sep(0)

    Create y1 containing a natural cubic spline interpolation of y on x for
    missing values of y
        . csipolate y x, gen(y1)

    List the result
        . list, sep(0)

    ---------------------------------------------------------------------------
    Setup
        . webuse ipolxmpl2

    Show years for which the circulation data are missing
        . tabulate circ year if circ == ., missing

    Create csicirc containing a natural cubic spline interpolation of circ on
    year for missing values of circ and perform this calculation separately
    for each magazine
        . by magazine: csipolate circ year, gen(csicirc)
    ---------------------------------------------------------------------------


Author

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


Acknowledgments

    Ben Ammar reported an example which underlined that there is point in
    asking for interpolation of singleton values. If that value is known,
    there is nothing to interpolate. If that value is unknown, there is
    nothing to do it with.


References

    Hamming, R.W. 1973.  Numerical methods for scientists and engineers.  New
        York: McGraw-Hill. See pp.349-356.

    Herriot, J.G. and C.H. Reinsch. 1973.  Algorithm 472: procedures for
        natural spline interpolation.  Communications of the Association for
        Computing Machinery 16: 763-768.

    Lancaster, P. and K. Salkauskas. 1986.  Curve and surface fitting: an
        introduction.  London: Academic Press. [capital S of Salkauskas
        should bear caron or wedge diacritic]

    Press, W.H., S.A. Teukolsky, W.T. Vetterling, B.P. Flannery. 2007.
        Numerical recipes: the art of scientific computing.  Cambridge:
        Cambridge University Press. See pp.120-124.


Also see

    Manual:  [D] ipolate