R/intersect_points.R

In fozy81/NBN4R: National Biodiversity Network Atlas (UK and Ireland) Data and Resources in R

#' Intersect environmental or contextual layers at a given a set of points (coordinates)
#' 
#' @references The associated NBN web service: \url{https://api.nbnatlas.org/#ws84}
#' @references Descriptions of the spatial layers: \url{https://layers.nbnatlas.org/layers/}
#'
#' This function allows the user to sample environmental/contextual layers at arbitrary locations. It complements 
#' the \code{\link{occurrences}} function, which allows values of the same set of layers to be downloaded at 
#' species occurrence locations.
#' NOTE: batch requests (multiple points) are currently processed in a *single queue* on the NBN servers. Processing times may be slow if there are many requests in the queue. Note also that the actual processing of batch requests is inherently slow: a large number of points may take quite some time. Be warned.
#' @param pnts numeric: vector of latitude/longitude pairs, or a 2 column data.frame or matrix of lat,lons. NOTE: the number of locations must be less than 1000.
#' @param layers string vector: ids of layers to be intersected. The list of possible layers is available from \code{nbn_fields("layers")}. Names can be passed as full layer names (e.g. "Radiation - lowest period (Bio22)") rather than id ("el871"). Note: if more than one location has been provided in \code{pnts}, the number of layers must be less than 700. 
#' @param SPdata.frame logical: should the output should be returned as a SpatialPointsDataFrame of the sp package or simply as a data.frame?
#' @param use_layer_names logical: if TRUE, layer names will be used as column names in the returned data frame (e.g. "radiationLowestPeriodBio22"). Otherwise, layer id value will be used for column names (e.g. "el871")
#' @param verbose logical: show additional progress information? [default is set by \code{\link{nbn_config}}]
#' @return A SpatialPointsDataFrame containing the intersecting data information. Missing data or incorrectly identified layer id values will result in NA data
#' @seealso \code{\link{nbn_config}}
#' @examples
#' \dontrun{
#'  # single point with multiple layers
#'  # i.e local environmental Records Centre boundaries UK &
#'  # watsonian vice counties:
#'  layers <- c('cl23','cl14')
#'  pnts <- c(51.5074,0.1278)
#'  intersect_points(pnts,layers) 
#'  # equivalent direct web service call:
#'  # https://layers.nbnatlas.org/ws/intersect/cl23,cl14/51.5074/0.1278  
#' 
#'  # multiple points as a grid sampling multiple layers
#'  # i.e ancient woodland & watsonian vice counties:
#'  layers <- c('cl23','cl14')   
#'  pnts <- data.frame(expand.grid(lat=seq(51.5074,52.5074),lon=seq(0.1278,0.1278)))
#'  intersect_points(pnts,layers)
#' }

## Previous limits of 1000 points and 299 layers have been increased here to reflect the increase
## on the service end.The batch version uses POST now to avoid 414 (URL too long) errors. Non-batch
## version does not seem to suffer 414s, even with 300 layers.

#' @export
intersect_points <- function(pnts, layers, SPdata.frame = FALSE, use_layer_names = TRUE,
                             verbose = nbn_config()$verbose) {
  
 ALA4R::intersect_points(pnts, layers, SPdata.frame, use_layer_names,
                         verbose)
  
}