# A function to generate m-surroundings This function obtains the m-surroundings by selecting the *m-1* nearest neighbors of each observation, allowing for a degree of overlap of *r*. ```r m.surround(x, m, r = 1, distance = "Euclidean", control = list()) ``` ## Arguments - `x`: input sf object with points/multipolygons geometry or matrix of spatial coordinates - `m`: dimension of m-surrounding - `r`: maximum overlapping between any two m-surroundings. - `distance`: character. For Cartesian coordinates only: one of Euclidean, Hausdorff or Frechet; for geodetic coordinates, Great Circle distances are computed. (see `sf::st_distance()`). Default = "Euclidean". - `control`: List of additional control arguments. ## Returns A list of class `list` and `m_surr` containing the following components: ||| |:--|:--| |`ms`|a matrix. Each row is a m-surrounding.| |`R`|total number of observations.| |`rowexcl`|index of rows excluded.| |`mdtms`|distances between the observations of each m-surrounding.| |`N`|total number of symbolized observations.| |`m`|length of the m-surroundings.| |`r`|overlapping degree.| |`initobs`|element to start the generation of m-surroundings.| |`distance`|type of distance.| |`m`|length of the m-surroundings.| |`x`|the input "x" as sf-object.| ## Control arguments * `initobs`: Initial observation to begin the m-surrounding process. Default = 1. * `dtmaxabs`: Threshold of distance (in absolute value) to prune the m-surroundings. Any m-surrounding exceeding the threshold is excluded. If `dtmaxabs` = 0 there is no exclusion of m-surroundings. Default = 0. * `dtmaxpc`: Threshold of distance (as a percentage of the maximum distance between observations) to prune the m-surroundings. Any m-surrounding exceeding the threshold is excluded. Example if `dtmaxpc` = 0.1 the m-surrounding exceeding the 10 If `dtmaxpc` = 0 there is no exclusion of m-surroundings. Default = 0. * `dtmaxknn`: Eliminate m-surroundings where some of the elements are not among the closest knn (k-nearest-neighbors). Example, if `dtmaxknn` = 4 exclude m-surroundings where some of the elements are not between the 4 closest. Default `dtmaxknn` = 0 (no exclusion) ## Examples ```r # Example 1: Obtain m-surroundings with degree of overlapping r N <- 100 cx <- runif(N) cy <- runif(N) x <- cbind(cx,cy) m <- 3 r <- 1 msurr_points <- m.surround(x = x, m = m, r = r) plot(msurr_points, type = 1) plot(msurr_points, type = 2) summary(msurr_points) msurr_points <- m.surround(x = x, m = m, r = r, control = list(dtmaxpc = 0.1)) plot(msurr_points, type = 1) plot(msurr_points, type = 2) summary(msurr_points) msurr_points <- m.surround(x = x, m = m, r = r, control = list(dtmaxknn = 20)) plot(msurr_points, type = 1) plot(msurr_points, type = 2) summary(msurr_points) # Example 2: data("FastFood.sf") m <- 3 r <- 1 msurr_points <- m.surround(x = FastFood.sf, m = m, r = r, distance = "Euclidean", control = list(dtmaxpc = .001)) plot(msurr_points, type = 1) plot(msurr_points, type = 2) print(msurr_points) summary(msurr_points) msurr_points <- m.surround(x = FastFood.sf, m = m, r = r, distance = "Euclidean", control = list(dtmaxknn = 20)) plot(msurr_points, type = 1) plot(msurr_points, type = 2) summary(msurr_points) # Example 3: With isolated areas data(provinces_spain) # sf::sf_use_s2(FALSE) plot(sf::st_geometry(provinces_spain)) m <- 3 r <- 1 msurr_points <- m.surround(x = provinces_spain, m = m, r = r, distance = "Euclidean", control = list(dtmaxknn = 8)) plot(msurr_points, type = 1) plot(msurr_points, type = 2) # Example 4: Examples with multipolygons fname <- system.file("shape/nc.shp", package="sf") nc <- sf::st_read(fname) plot(sf::st_geometry(nc)) m <- 3 r <- 1 msurr_polygonsf <- m.surround(x = nc, m = m, r = r, distance = "Great Circle", control=list(dtmaxpc = 0.20)) plot(msurr_polygonsf, type = 1) plot(msurr_polygonsf, type = 2) # Example 5: With regular lattice sfc = sf::st_sfc(sf::st_polygon(list(rbind(c(0,0), c(1,0), c(1,1), c(0,1), c(0,0))))) hexs <- sf::st_make_grid(sfc, cellsize = 0.1, square = FALSE) hexs.sf <- sf::st_sf(hexs) listw <- spdep::poly2nb(as(hexs.sf, "Spatial"), queen = FALSE) m <- 3 r <- 1 msurr_polygonsf <- m.surround(x = hexs.sf, m = m, r = r) plot(msurr_polygonsf, type = 1) plot(msurr_polygonsf, type = 2) summary(msurr_polygonsf) ``` ## References * Ruiz M, López FA, A Páez. (2010). Testing for spatial association of qualitative data using symbolic dynamics. **Journal of Geographical Systems**. 12 (3) 281-309 ## Author(s) ||| |:--|:--| |Fernando López|fernando.lopez@upct.es| |Román Mínguez|roman.minguez@uclm.es| |Antonio Páez|paezha@gmail.com| |Manuel Ruiz|manuel.ruiz@upct.es|

m.surround function