{smcl}
{* 8 Nov 2012}{...}
{hline}
help for {hi:nnipolate}
{hline}
{title:Nearest neighbour interpolation}
{p 8 17 2}{cmd:nnipolate} {it:yvar} {it:xvar}
[{cmd:if} {it:exp}] [{cmd:in} {it:range}]
{cmd:,} {cmdab:g:enerate}{cmd:(}{it:newvar}{cmd:)}
[{cmd:ties(}{it:ties_rule}{cmd:)}]
{p 4 4 2}{cmd:by} {it:...} {cmd::} may be used with {cmd:nnipolate};
see help {help by}.
{title:Description}
{p 4 4 2}
{cmd:nnipolate} creates {it:newvar} by averaging non-missing values of
{it:yvar} and using nearest neighbour interpolation of missing values of
{it:yvar}, given {it:xvar}. That is, provided that {it:xvar} is not
missing,
{p 4 4 2}1. When {it:yvar} is not missing, {it:newvar} is the mean of
{it:yvar} over observations with the same value of {it:xvar}. If a value
of {it:xvar} is unique, then each mean is just the same as the value of
{it:yvar} at that point.
{p 4 4 2}2. When {it:yvar} is missing, {it:newvar} is filled in using
nearest neighbour interpolation. As interpolation is with respect to
{it:xvar}, that means the value of the previous known value of {it:yvar}
or the value of the next known value of {it:yvar}, depending on which is
nearer in terms of {it:xvar}. Previous or next mean with lower or higher
values of {it:xvar}.
{p 4 4 2}3. When previous and next values are equally distant from a known
value, users have a choice of rules that they may wish applied. By default,
{cmd:nnipolate} uses the mean of the two values. The {cmd:ties()} option
provides alternative rules.
{title:Remarks}
{p 4 4 2}This method is presumably most natural or appealing when the
underlying pattern of change is step-functional, so that the series being
interpolated is piecewise constant.
{p 4 4 2}This interpolation method also extrapolates, as unknown values
before the first known value and unknown values after the last known
value are replaced by those respective known values.
{p 4 4 2}The examples are based on the help for {help ipolate} in Stata
10 up. Any Stata 8 or 9 users will need to substitute their own.
{p 4 4 2}'Neighbour' is the standard spelling in (British) English.
'Neighbor' is the standard spelling in American English.
{p 4 4 2}{cmd:nnipolate} does not support interpolation in two or more
dimensions.
{title:Options}
{p 4 8 2}{cmd:generate()} is not optional; it specifies the name of the
new variable to be created.
{p 4 8 2}{cmd:ties()} specifies an alternative to the default rule whereby
previous and next values equally distant from a given point are averaged. The user may
choose one of {cmdab:n:ext} (next value is used), {cmdab:p:revious} (previous
value is used), {cmdab:mi:nimum} (smaller value is used), or {cmdab:ma:ximum} (larger
value is used). As indicated, any unambiguous abbreviation is allowed.
{title:Examples}
{hline}
{pstd}Setup{p_end}
{phang2}{cmd:. webuse ipolxmpl1}
{pstd}List the data{p_end}
{phang2}{cmd:. list, sep(0)}
{pstd}Create {cmd:y1} containing a nearest neighbour interpolation of {cmd:y} on {cmd:x}
for missing values of {cmd:y}{p_end}
{phang2}{cmd:. nnipolate y x, gen(y1)}
{pstd}Use alternative rules for handling ties:{p_end}
{phang2}{cmd:. nnipolate y x, ties(next) gen(ynext)}{p_end}
{phang2}{cmd:. nnipolate y x, ties(prev) gen(yprev)}{p_end}
{phang2}{cmd:. nnipolate y x, ties(max) gen(ymax)}{p_end}
{phang2}{cmd:. nnipolate y x, ties(min) gen(ymin)}
{pstd}List the results{p_end}
{phang2}{cmd:. list, sep(0)}
{hline}
{pstd}Setup{p_end}
{phang2}{cmd:. webuse ipolxmpl2}{p_end}
{pstd}Show years for which the circulation data are missing{p_end}
{phang2}{cmd:. tabulate circ year if circ == ., missing}
{pstd}Create {cmd:csicirc} containing a nearest neighbour interpolation of {cmd:circ} on
{cmd:year} for missing values of {cmd:circ} and perform this calculation
separately for each {cmd:magazine}{p_end}
{phang2}{cmd:. by magazine: nnipolate circ year, gen(csicirc)}{p_end}
{hline}
{title:Author}
{p 4 4 2}Nicholas J. Cox, Durham University, U.K.{break}
n.j.cox@durham.ac.uk
{title:Also see}
{p 4 13 2}Manual: {hi:[D] ipolate}
{p 4 13 2}On-line: help for {help ipolate},
help for {help cipolate} (if installed),
help for {help csipolate} (if installed)