-------------------------------------------------------------------------------
help for pchipolate
-------------------------------------------------------------------------------

Piecewise cubic Hermite interpolation

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

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


Description

    pchipolate creates newvar by averaging non-missing values of yvar and
    using piecewise cubic Hermite 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 piecewise cubic
    Hermite interpolation.


Remarks 

    This method is often described informally as "pchip". For a lucid
    account, see Moler (2004, Ch.3). Informally, pchip interpolates using
    piecewise cubics that join smoothly, so that both the interpolated
    function and its first derivative are continuous. In addition, the
    interpolant is shape-preserving in the sense that it cannot overshoot
    locally; sections in which observed yvar is increasing, decreasing or
    constant with xvar remain so after interpolation, and local extremes
    (maxima, maxima) also remain so.

    This interpolation method also extrapolates.

    The first two examples are based on the help for ipolate in Stata 10.


Options

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


Examples

    ---------------------------------------------------------------------------
    Setup
        . webuse ipolxmpl1, clear

    List the data
        . list, sep(0)

    Create y1 containing an interpolation of y on x for missing values of y
        . pchipolate y x, gen(y1)

    Plot the result
        . line y1 x || scatter y x

    List the result
        . list, sep(0)

    ---------------------------------------------------------------------------
    Setup
        . webuse ipolxmpl2, clear

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

    Create pchicirc containing an interpolation of circ on year for missing
    values of circ and perform this calculation separately for each magazine
        . by magazine: pchipolate circ year, gen(pchicirc)

    Plot the result
        . line pchicirc year || scatter circ year, by(magazine) {hline}

    ---------------------------------------------------------------------------
    Moler's example
        . clear
        . set obs 6
        . matrix y = (16, 18, 21, 17, 15, 12)'
        . gen y = y[_n, 1]
        . gen x = _n
        . set obs 61
        . replace x = (_n + 1)/10 in 7/L
        . pchipolate y x, gen(pchip)
        . line pchip x, sort || scatter y x
    ---------------------------------------------------------------------------


Author

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


Acknowledgments 

    Most of the Mata code in this program is a translation of MATLAB code
    given by Moler (2004).


References 

    Moler, C. 2004. Numerical Computing with MATLAB.  Philadelphia: SIAM.
        Chapter 3.  (also available in slightly different form at
        http://www.mathworks.com/moler/interp.pdf)


Also see

    Manual:  [D] ipolate

    On-line:  help for ipolate, help for cipolate (if installed), help for