tmaptools (version 2.0)

sample_dots: Sample dots from spatial polygons

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

Value

A shape object, in the same format as shp

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.

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"))
}
# }