Skip to contents

Calculate Non-Contiguous Cartogram Boundaries

Source: R/cartogram_ncont.R
cartogram_ncont.Rd

Construct a non-contiguous area cartogram (Olson 1976).

Usage

cartogram_ncont(
  x,
  weight,
  k = 1,
  inplace = TRUE,
  n_cpu = getOption("cartogram_n_cpu", "respect_future_plan"),
  show_progress = getOption("cartogram.show_progress", TRUE)
)

# S3 method for class 'SpatialPolygonsDataFrame'
cartogram_ncont(
  x,
  weight,
  k = 1,
  inplace = TRUE,
  n_cpu = getOption("cartogram_n_cpu", "respect_future_plan"),
  show_progress = getOption("cartogram.show_progress", TRUE)
)

# S3 method for class 'sf'
cartogram_ncont(
  x,
  weight,
  k = 1,
  inplace = TRUE,
  n_cpu = getOption("cartogram_n_cpu", "respect_future_plan"),
  show_progress = getOption("cartogram.show_progress", TRUE)
)

Arguments

x

a polygon or multiplogyon sf object

weight

Name of the weighting variable in x

k

Factor expansion for the unit with the greater value

inplace

If TRUE, each polygon is modified in its original place, if FALSE multi-polygons are centered on their initial centroid

n_cpu

Number of cores to use. Defaults to "respect_future_plan". Available options are:

  • "respect_future_plan" - By default, the function will run on a single core, unless the user specifies the number of cores using plan (e.g. future::plan(future::multisession, workers = 4)) before running the cartogram_ncont function.

  • "auto" - Use all except available cores (identified with availableCores) except 1, to keep the system responsive.

  • a numeric value - Use the specified number of cores. In this case cartogram_ncont will use set the specified number of cores internally with future::plan(future::multisession, workers = n_cpu) and revert that back by switching the plan back to whichever plan might have been set before by the user. If only 1 core is set, the function will not require future and future.apply and will run on a single core.

show_progress

A logical value. If TRUE, show progress bar. Defaults to TRUE.

Value

An object of the same class as x with resized polygon boundaries

References

Olson, J. M. (1976). Noncontiguous Area Cartograms. In The Professional Geographer, 28(4), 371-380.

Examples

# ========= Basic example =========
library(sf)
library(cartogram)

nc = st_read(system.file("shape/nc.shp", package="sf"), quiet = TRUE)

# transform to NAD83 / UTM zone 16N
nc_utm <- st_transform(nc, 26916)

# Create cartogram
nc_utm_carto <- cartogram_ncont(nc_utm, weight = "BIR74")

# Plot
par(mfrow=c(2,1))
plot(nc[,"BIR74"], main="original", key.pos = NULL, reset = FALSE)
plot(st_geometry(nc_utm), main="distorted", reset = FALSE)
plot(nc_utm_carto[,"BIR74"], add =TRUE)



# ========= Advanced example 1 =========
# Faster cartogram using multiple CPU cores
# using n_cpu parameter
library(sf)
library(cartogram)

nc = st_read(system.file("shape/nc.shp", package="sf"), quiet = TRUE)

# transform to NAD83 / UTM zone 16N
nc_utm <- st_transform(nc, 26916)

# Create cartogram using 2 CPU cores on local machine
nc_utm_carto <- cartogram_ncont(nc_utm, weight = "BIR74", n_cpu = 2)

# Plot
par(mfrow=c(2,1))
plot(nc[,"BIR74"], main="original", key.pos = NULL, reset = FALSE)
plot(st_geometry(nc_utm), main="distorted", reset = FALSE)
plot(nc_utm_carto[,"BIR74"], add =TRUE)



# ========= Advanced example 2 =========
# Faster cartogram using multiple CPU cores
# using future package plan
library(sf)
library(cartogram)
library(future)

nc = st_read(system.file("shape/nc.shp", package="sf"), quiet = TRUE)

# transform to NAD83 / UTM zone 16N
nc_utm <- st_transform(nc, 26916)
# Set the future plan with 2 CPU local cores
# You can of course use any other plans, not just multisession
future::plan(future::multisession, workers = 2)

# Create cartogram with multiple CPU cores
# The cartogram_cont() will respect the plan set above
nc_utm_carto <- cartogram_ncont(nc_utm, weight = "BIR74")

# Shutdown the R processes that were created by the future plan
future::plan(future::sequential)

# Plot
par(mfrow=c(2,1))
plot(nc[,"BIR74"], main = "original", key.pos = NULL, reset = FALSE)
plot(st_geometry(nc_utm), main = "distorted", reset = FALSE)
plot(nc_utm_carto[,"BIR74"], add = TRUE)