sample_dots: Sample dots from spatial polygons

In mtennekes/oldtmaptools: Old Thematic Map Tools

Description

Sample dots from spatial polygons according to a spatial distribution of a population. The population may consist of classes. The output, an sf object containing spatial points, can be used to create a dot map (see tm_dots), where the dots are colored according to the classes. Note that this function supports sf objects, but still uses sp-based methods (see details).

Usage

sample_dots(shp, vars = NULL, convert2density = FALSE, nrow = NA,
  ncol = NA, N = 250000, npop = NA, n = 10000, w = NA,
  shp.id = NULL, var.name = "class", var.labels = vars,
  target = "metric", randomize = TRUE, output = c("points", "grid"),
  orig = NULL, to = NULL, ...)

Arguments

shp	A shape object, more specifically, a SpatialPolygonsDataFrame or an sf object that can be coerced as such.
vars	Names of one or more variables that are contained in shp. If vars is not provided, the dots are sampled uniformly. If vars consists of one variable name, the dots are sampled according to the distribution of the corresponding variable. If vars consist of more than one variable names, then the dots are sampled according to the distributions of those variables. A categorical variable is added that contains the distrubtion classes (see var.name).
convert2density	Should the variables be converted to density values? Density values are used for the sampling algorithm, so use TRUE when the values are absolute counts.
nrow	Number of grid rows
ncol	Number of grid colums
N	Number of grid points
npop	Population total. If NA, it is recontructed from the data. If density values are specified, the population total is approximated using the polygon areas (see also target, orig and to).
n	Number of sampled dots
w	Number of population units per dot. It is the population total divided by n. If specified, n is calculated accordingly.
shp.id	Name of the variable of shp that contains the polygon identifying numbers or names.
var.name	Name of the variable that will be created to store the classes. The classes are defined by vars, and the labels can be configured with var.labels.
var.labels	Labels of the classes (see var.name).
target	target unit, see approx_areas
randomize	should the order of sampled dots be randomized? The dots are sampled class-wise (specified by vars). If this order is not randomized (so if randomize=FALSE), then the dots from the last class will be drawn on top, which may introduce a perception bias. By default randomize=TRUE, so the sampled dots are randomized to prevent this bias.
output	format of the output: use "points" for spatial points, and "grid" for a spatial grid.
orig	not used anymore as of version 2.0
to	not used anymore as of version 2.0
...	other arguments passed on to calc_densities and approx_areas

Details

This function supports sf objects, but still uses sp-based methods, from the packages sp, rgeos, and/or rgdal. Alternatively, st_sample can be used.

Value

A shape object, in the same format as shp

Examples

## Not run: 
if (require(tmap)) {
    data(World)
    World_dots <- sample_dots(World, vars="pop_est_dens", nrow=200, ncol=400, w=1e6)

    tm_shape(World_dots) + tm_dots(size = .02, jitter=.1) +
    	tm_layout("One dot represents one million people", title.position = c("right", "bottom"))
}

## End(Not run)

mtennekes/oldtmaptools documentation built on May 11, 2019, 8:22 p.m.