build_neighborhood: Nearest Neighbor (NN) data subset given a center
In liGP: Locally Induced Gaussian Process Regression

Description Usage Arguments Details Value Author(s) References Examples

Constructs a neighborhood of points that are a subset of the data for a given center (i.e. predictive) location.

1	build_neighborhood(N, xx = NULL, X = NULL, Y = NULL, reps_list = NULL)

`N`	the positive integer number of Nearest Neighbor (NN) locations used to build a local neighborhood
`xx`	a row matrix of the location of the neighborhood's center. If `NULL`, the center (median) of the data is used
`X`	a `matrix` containing the full (large) design matrix of input locations. If `reps_list` is supplied, this entry is not used.
`Y`	a vector of responses/dependent values with `length(Y)=nrow(X)`. If `reps_list` is supplied, this entry is not used.
`reps_list`	a list from `find_reps` in the `hetGP` package, that includes the entries `X0` and `Z0`. In this case, `X` and `Y` are not used.

This function builds a local neighborhood around the center xx. If X is supplied, the N NN points are found and chosen. If reps_list is supplied, N unique data locations X0 are supplied, along with their averaged responses (Z0) and original responses (Zlist).

The output is a list with the following components:

`xx`	a row `matrix` of the neighborhood's center

If reps_list=NULL,

`Xn`	a `matrix` of the local neighborhood's design points.
`Yn`	a `vector` of the local neighborhood's responses. Only provided when `Y` is provided.

If reps_list is provided,

`Xn0`	a `matrix` of the local neighborhood's unique design locations.
`Yn0`	a `vector` of averages observations at `Xn0`.
`mult`	a vector of the number of replicates at `Xn0`.
`Yn_list`	a `list` where each element corresponds to observations at a design in `Xn0`.

D. Austin Cole austin.cole8@vt.edu

D.A. Cole, R.B. Christianson, and R.B. Gramacy (2021). Locally Induced Gaussian Processes for Large-Scale Simulation Experiments Statistics and Computing, 31(3), 1-21; preprint on arXiv:2008.12857; https://arxiv.org/abs/2008.12857

## "2D Toy Problem"
## Herbie's Tooth function used in Cole et al (2021);
## thanks to Lee, Gramacy, Taddy, and others who have used it before
library(hetGP)

## Build data with replicates
x <- seq(-2, 2, by=0.05)
X <- as.matrix(expand.grid(x, x))
X <- rbind(X, X)
Y <- herbtooth(X) + rnorm(nrow(X), sd = .02)
reps_list <- find_reps(X, Y)
xx <- matrix(c(-0.12, 1.53), nrow=1)

## Build neighborhoods
neighborhood1 <- build_neighborhood(N=100, xx=xx, X=X, Y=Y)
neighborhood2 <- build_neighborhood(N=100, xx=xx, reps_list=reps_list)

## Compare neighborhood sizes
Xn0_range <- apply(neighborhood2$Xn0, 2, range)
plot(X, xlim = Xn0_range[,1] + c(-.15, .15), ylim = Xn0_range[,2] + c(-.1, .25),
     pch=3)
points(neighborhood2$Xn0, pch=16, col='grey')
points(neighborhood1$Xn, col=2, lwd=2)
points(xx, pch=17, col=3, cex=1.5)
legend('topleft', ncol=2, pch=c(3, 17, 16, 1), col=c(1, 3, 'grey', 2),
       legend=c('Design locations', 'Neighborhood center',
                'Xn based on unique locations', 'Xn ignoring unique locations'))