nco_predict: Out-of-sample prediction for Nonparametric Constrained...
In phytomosaic/ngnn: ngnn: Nonlinear Gradient Nearest Neighbors

Description Usage Arguments Details Value References Examples

Calculates new scores for out-of-sample observations in a multivariate NCO gradient space.

nco_predict(obj, method, neighb, maxits, ...)

## S3 method for class 'ncopredict'
plot(obj, type = "points", ocol = 2,
  cexn = NULL, ...)

`obj`	object of class 'nco' from call to `nco`
`method`	distance measure for all ordinations
`neighb`	number of adjacent distances considered in prediction
`maxits`	number of iterations
`...`	additional arguments passed to function
`type`	either 'points' or 'text' for plotting
`ocol`	color value or vector for out-of-sample points
`cexn`	expansion factor for points and text

Combines existing algorithms in multivariate workflow:

NPMR + NMS = NCO[in-sample]
NCO + NCOpredict = NCO[out-of-sample]

The main function is a wrapper for add.points(), written by Dave Roberts, who deserves all credit. The intellectual pedigree of the NMS prediction concept includes Dave Roberts, Peter Minchin, Jari Oksanen, and Bruce McCune, although they each differ in algorithmic approach. McCune et al. (1997a, 1997b) gave its first use in the literature, while McMurray et al. (2015) gave the first results from the R implementation. PC-ORD (McCune and Mefford 2016) seems to be the only other software that offers NMS prediction, and does so with a different algorithm that also flags poorly fit new points.

List of class 'ncopredict' including new out-of-sample predicted scores, and flags indicating which (if any) were beyond the range of original scores. Specifically, the first item nmsp is a list of 5 items describing predicted NCO scores:

scr_both = combined new and old NCO scores
scr_o = new NCO scores only
stress = overall stress of the solution, with new scores
iters = number of iterations performed
cause = ICAUSE from FORTRAN, reason for termination of iterations: 1 = max iterations used, 2 = stress fell below STRMIN, 3 = stress ratio exceeded SRATMX, 4 = scale factor of gradient fell below SFGRMN
R2_enviro = squared correlation of D and Dz
R2_partial = squared correlation of Dz and each predictor
Axis_tau = rank correlation of each axis and predictor

McCune, B., J.P. Dey, J.E. Peck, K. Heiman, and S. Will-Wolf. 1997a. Regional gradients in lichen communities of the southeast United States. Bryologist 100:145-158.

McCune, B., J.P. Dey, J.E. Peck, D. Cassell, K. Heiman, S. Will-Wolf, and P.N. Neitlich. 1997b. Repeatability of community data: species richness versus gradient scores in large-scale lichen studies. Bryologist 100:40-46.

McCune, B., and M. J. Mefford. 2016. PC-ORD. Multivariate Analysis of Ecological Data. Version 7. MjM Software Design, Gleneden Beach, OR.

McMurray, J.A., D.W. Roberts, and L.H. Geiser. 2015. Epiphytic lichen indication of nitrogen deposition and climate in the northern rocky mountains, USA. Ecological Indicators 49:154-161.

Roberts, D.W. 2017. LabDSV: Non-metric Multidimensional Scaling. URL http://ecology.msu.montana.edu/labdsv/R/labs/lab9/lab9.html [original code, as add.points()]

# set up
set.seed(978)
require(vegan)
data(varespec, varechem)
spe <- varespec ; id  <- varechem
i   <- sample(1:nrow(spe), size=floor(0.75*nrow(spe))) # sample
spe <- spe[i, ]          # in-sample species
idi <- id[i, ]           # in-sample predictors
ido <- id[-i, ]          # out-of-sample predictors
nm  <- c('Al', 'K')      # select 1 or 2 gradients of interest

# NPMR
res_npmr <- npmr(spe, idi, ido, nm, nmulti=5)
summary(res_npmr)

# NCO (NMS)
res_nco  <- nco(res_npmr, method='bray', thresh=0.90)
summary(res_nco)

# NCOpredict (NMSpredict)
res_nmsp <- nco_predict(res_nco, method='bray', neighb=5,
                        maxits=999)
summary(res_nmsp)

# plot the NCO gradient space
par(mfrow=c(1,2))
plot(res_nco)       # original in-sample points
plot(res_nmsp)      # add out-of-sample points
par(mfrow=c(1,1))