osmgeosample (version 0.1)

osm_random_sample: Spatially random sampling.

Description

This function draws a spatially random sample from a either (1) a discrete set of OSM features defined in the function parameters or (2) a continuous surface defined by a user definted geographical region.

Usage

osm_random_sample(
  bounding_geom = NULL,
  key = NULL,
  value = NULL,
  boundary_or_feature = "boundary",
  feature_geom = NULL,
  data_return = c("osm_polygons", "osm_points", "osm_multipolygons", "multilines",
    "lines"),
  boundary = 0,
  buff_dist = 0,
  buff_epsg = 4326,
  join_type = "within",
  dis_or_cont,
  sample_size,
  join_features_to_osm,
  plotit = TRUE,
  plotit_leaflet = TRUE
)

Arguments

bounding_geom

a sf or sp object (with \(N \geq \code{size}\)) where each line corresponds to one spatial location. It should contain values of 2D coordinates, data and, optionally, covariate(s) value(s) at the locations. This argument must be provided when sampling from a 'discrete' set of points, see 'type' below for details.

key

A feature key as defined in OSM. An example is 'building'.

value

a value for a feature key (key); can be negated with an initial exclamation mark, value = '!this', and can also be a vector, value = c ('this', 'that').

boundary_or_feature

specifies whether the user inputs a boundary or a set of user-inputted features. For example if the user selects "boundary", they can provide a spatial data frame or OSM locality which will query the osm features within that boundary or locality. If the user select "feature" then they can provide a data frame of features that they want to sample

feature_geom

is a user inputted data frame of features that are required to be sampled.

data_return

specifies what data types (as specified in OSM) you want returned. More than one can be selected. The options are 'osm_polygons', 'osm_points', 'osm_multipolygons','osm_multilines','osm_lines'.

boundary

categorical variable to determine whether the exact boundary provided (boundary = 0), the bounding box (boundary = 1) or a buffer around the boundary (boundary = 2) is used for sampling. Default is boundary = 0.

buff_dist

if boundary = 2 then this value determines the size of the buffer by distance. The default is buff_dist is NULL).

buff_epsg

if boundary = 2 then this value determines the local geographic grid reference so that the buffer can be calculated in meters. The default is buff_epsg = 4326 which will use decimal degrees instead of meters. As an example, 27700 relates to the British National Grid.

join_type

a text value to determine how to spatially join all features with the boundary. The options are 'within' or 'intersect'.

dis_or_cont

random sampling, a choice of either 'discrete', from a set of \(N\) potential sampling points or 'continuum' from independent, compeletely random points.

sample_size

a non-negative integer giving the total number of locations to be sampled.

join_features_to_osm

is a TRUE or FALSE variable which allows the user to specify whether they want their feature geom to be spatially joined to OSM features. The output sampling data frame will have an additional column showing the joined OSM id.

plotit

'logical' specifying if graphical output is required. Default is plotit = TRUE.

plotit_leaflet

'logical' specifying if leaflet (html) graphical output is required. This is prioritised over plotit if both are selected. Default is plotit_leaflet = TRUE.

Value

a df object named 'results' of dimension \(n\) by 4 containing the final sampled osm_ids, centroid locations (named x,y) and whether the instance is in the selected sample (named inSample with a value of 0/1), if sampling from a 'discrete' set of points. A df object of dimension \(n\) by 3 containing the serial id and centroid locations for all sample instances,if sampling from a 'continuum'.

References

Rowlingson, B. and Diggle, P. 1993 Splancs: spatial point pattern analysis code in S-Plus. Computers and Geosciences, 19, 627-655 https://wiki.openstreetmap.org/wiki/Map_Features

Examples

# NOT RUN {
library(sp)
bounding_geom<-
SpatialPolygonsDataFrame(
   SpatialPolygons(list(Polygons(list(Polygon(
       cbind(
           c(3.888959,3.888744,3.888585,3.888355,3.887893,3.887504,3.886955,
           3.886565,3.886303,3.886159,3.885650,3.885650,3.885595,3.885404,
           3.885444,3.885897,3.886692,3.887241,3.888068,3.888323,3.888697,
           3.889150,3.889548,3.889890,3.890184,3.890828,3.891258,3.891807,
           3.892061,3.892292,3.892689,3.893294,3.893008,3.893676,3.888959),
           c(7.379483,7.379785,7.380024,7.380294,7.380629,7.380986,
           7.381448,7.381861,7.382243,7.382474,7.383277,7.383468,7.383890,
           7.384263,7.384669,7.385258,7.385313,7.385194,7.384868,7.384900,
           7.385051,7.385067,7.384955,7.384749,7.384526,7.384120,7.384009,
           7.384080,7.384430,7.384478,7.384629,7.384772,7.383269,7.380963,
           7.379483)))), ID=1))),
   data.frame( ID=1))
proj4string(bounding_geom) <- CRS('+proj=longlat +datum=WGS84')

set.seed(15892)
xy.sample <- osm_random_sample(buff_dist=NULL,
                              boundary_or_feature = "boundary",
                              bounding_geom = bounding_geom,
                              key= 'building', value = NULL, boundary = 0,
                              buff_epsg = NULL, join_type = 'intersect',
                              dis_or_cont = 'discrete', sample_size = 70,
                              plotit = TRUE, plotit_leaflet = TRUE,
                              data_return= c('osm_polygons'))
# }
# NOT RUN {
# }