tmap (version 1.6)

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, a SpatialPointsDataFrame, can be used to create a dot map (see tm_dots), where the dots are colored according to the classes.

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, unit = "km", unit.size = 1000, randomize = TRUE, output = c("points", "grid"), ...)

Arguments

shp

A shape object, more specifically, a SpatialPolygonsDataFrame.

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 unit and unit.size).

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).

unit

Unit, see calc_densities. Needed to relate npop to w, if they are not both specified.

unit.size

Unit size, see calc_densities. Needed to relate npop to w, if they are not both specified.

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.

...

other arguments passed on to calc_densities and approx_areas

Details

The sampling algoritm is the following: TO DO

Examples

## Not run: 
# 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)