specnumperpatch-probs: Initiate a specific number of agents in a map of patches

In SpaDES.tools: Additional Tools for Developing Spatially Explicit Discrete Event Simulation (SpaDES) Models

Initiate a specific number of agents in a map of patches

Description

Instantiate a specific number of agents per patch. The user can either supply a table of how many to initiate in each patch, linked by a column in that table called pops.

Usage

specificNumPerPatch(patches, numPerPatchTable = NULL, numPerPatchMap = NULL)

Arguments

patches	SpatRaster of patches, with some sort of a patch id.
numPerPatchTable	A data.frame or data.table with a column named pops that matches the patches patch ids, and a second column num.in.pop with population size in each patch.
numPerPatchMap	A SpatRaster exactly the same as patches but with agent numbers rather than ids as the cell values per patch.

Value

A raster with 0s and 1s, where the 1s indicate starting locations of agents following the numbers above.

Examples

library(data.table)

origDTThreads <- data.table::setDTthreads(2L)
origNcpus <- options(Ncpus = 2L)

set.seed(1234)
Ntypes <- 4
ras <- randomPolygons(numTypes = Ntypes)
if (interactive()) {
  terra::plot(ras)
}

# Use numPerPatchTable
patchDT <- data.table(pops = 1:Ntypes, num.in.pop = c(1, 3, 5, 7))
rasAgents <- specificNumPerPatch(ras, patchDT)
rasAgents[is.na(rasAgents)] <- 0

if (require(testthat))
  expect_true(all(unname(table(ras[rasAgents])) == patchDT$num.in.pop))

# Use numPerPatchMap
# Remap in one pass: rewriting in place would collide, because a patch
# rewritten to a value that is also a later patch's id gets overwritten
# again on that iteration.
rasPatches <- ras
terra::values(rasPatches) <-
  patchDT$num.in.pop[match(terra::values(ras)[, 1], patchDT$pops)]
if (interactive()) {
  terra::plot(c(ras, rasPatches))
}
rasAgents <- specificNumPerPatch(ras, numPerPatchMap = rasPatches)
rasAgents[is.na(rasAgents)] <- 0
if (interactive()) {
  terra::plot(rasAgents)
}

# clean up
data.table::setDTthreads(origDTThreads)
options(Ncpus = origNcpus)

SpaDES.tools documentation built on Aug. 29, 2026, 1:07 a.m.