stewart: Stewart Potentials

Description

This function computes the potentials as defined by J.Q. Stewart (1942).

Usage

stewart(
  knownpts,
  unknownpts,
  matdist,
  varname,
  typefct = "exponential",
  span,
  beta,
  resolution,
  mask,
  bypassctrl = FALSE,
  longlat = TRUE,
  returnclass = "sp"
)

Value

Point object with the computed potentials in a new field named OUTPUT.

Arguments

knownpts: sp or sf object; this is the set of known observations to estimate the potentials from.
unknownpts: sp or sf object; this is the set of unknown units for which the function computes the estimates. Not used when resolution is set up. (optional)
matdist: matrix; distance matrix between known observations and unknown units for which the function computes the estimates. Row names match the row names of knownpts and column names match the row names of unknownpts. matdist can contain any distance metric (time distance or euclidean distance for example). If matdist is missing, the distance matrix is built with CreateDistMatrix. (optional)
varname: character; name of the variable in the knownpts dataframe from which potentials are computed. Quantitative variable with no negative values.
typefct: character; spatial interaction function. Options are "pareto" (means power law) or "exponential". If "pareto" the interaction is defined as: (1 + alpha * mDistance) ^ (-beta). If "exponential" the interaction is defined as: exp(- alpha * mDistance ^ beta). The alpha parameter is computed from parameters given by the user (beta and span).
span: numeric; distance where the density of probability of the spatial interaction function equals 0.5.
beta: numeric; impedance factor for the spatial interaction function.
resolution: numeric; resolution of the output grid (in map units). If resolution is not set, the grid will contain around 7250 points. (optional)
mask: sp or sf object; the spatial extent of this object is used to create the regularly spaced points output. (optional)
bypassctrl: logical; bypass the distance matrix size control (see CreateDistMatrix Details).
longlat: logical; if FALSE, Euclidean distance, if TRUE Great Circle (WGS84 ellipsoid) distance.
returnclass: "sp" or "sf"; class of the returned object.

References

STEWART J.Q. (1942) "Measure of the influence of a population at a distance", Sociometry, 5(1): 63-71.

Examples

Run this code

# Create a grid of paris extent and 200 meters
# resolution
data(hospital)
mygrid <- CreateGrid(w = paris, resolution = 200, returnclass = "sf")
# Create a distance matrix between known points (spatPts) and mygrid
mymat <- CreateDistMatrix(knownpts = hospital, unknownpts = mygrid)
# Compute Stewart potentials from known points (spatPts) on a given
# grid (mygrid) using a given distance matrix (mymat)
mystewart <- stewart(knownpts = hospital, unknownpts = mygrid,
                     matdist = mymat, varname = "capacity",
                     typefct = "exponential", span = 1250,
                     beta = 3, mask = paris, returnclass = "sf")
# Compute Stewart potentials from known points (spatPts) on a
# grid defined by its resolution
mystewart2 <- stewart(knownpts = hospital, varname = "capacity",
                      typefct = "exponential", span = 1250, beta = 3,
                      resolution = 200, mask = paris, returnclass = "sf")
# The two methods have the same result
identical(mystewart, mystewart2)
# the function output a sf data.frame
class(mystewart)
# Computed values
summary(mystewart$OUTPUT)