```-------------------------------------------------------------------------------
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
```