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)

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 csipolate (if installed),
help for nnipolate (if installed)