Get a table or matrix with the distances between pairs of nodes.

Source: R/distancefile.R

Get a table or matrix with the distances (Euclidean or cost distances) between pairs of nodes. It can be used as a connector file.

distancefile(
  nodes,
  id,
  type = "centroid",
  distance_unit = NULL,
  keep = NULL,
  resistance = NULL,
  resist.units = FALSE,
  CostFun = NULL,
  ngh = NULL,
  mask = NULL,
  threshold = NULL,
  geometry_out = NULL,
  bounding_circles = NULL,
  parallel = FALSE,
  ActiveParallel = FALSE,
  least_cost.java = FALSE,
  cores.java = 1,
  ram.java = NULL,
  pairwise = TRUE,
  write = NULL
)

Arguments

nodes

object of class sf, SpatialPolygons, RasterLaryer or SpatRaster (terra package). It must be in a projected coordinate system. If nodes is a raster layer then raster values (Integer) will be taken as "id".

id

character. If nodes is a shapefile then you must specify the column name with the node ID in the shapefile data table.

type

character. Choose one of the distance options:
- "centroid" (faster option, default), where Euclidean distance is calculated from feature centroid - "edge", where Euclidean distance is calculated from feature edges.
- "least-cost" that takes into account obstacles and local friction of the landscape (see, gdistance package).
- "commute-time" that is analogous to the resistance distance of circuitscape. The commute-time distance is based on the random walk theory and calculated using the electrical circuit theory (See, gdistance package).
If the type is equal to "least-cost" or "commute-time", then you have to use the "resistance" argument.

distance_unit

character. If "least-cost" or "commute-time" is selected or resist.units = TRUE then you can set a distance unit ("m", "km", "inch", "foot", "yard", "mile"). Default equal to meters "m" (see, unit_convert).

keep

numeric. In case you have selected the "edge" distance, use this option to simplify the geometry and reduce the number of vertices. The value can range from 0 to 1 and is the proportion of points to retain (default equal to NULL). The lower the value, the higher the speed but less precision.

resistance

raster. Raster object with resistance values. If least_cost.java = TRUE, then resistance must bee an integer raster (i.e., integer values).

resist.units

logical. If resist.units = TRUE and type = "least-cost" then cost units are converted to metric units by multiplying the cost by the raster resolution.

CostFun

function. A function to compute the cost to move between cells. Available only if you you have selected the "least-cost" or "commute-time" distance. The default is the mean (isotropic cost distance): function(x) 1/mean(x). If resistance is a conductance raster then you can use: function(x) mean(x)

ngh

numeric. Neighbor graph (directions) for distance calculations: 4 (von Neu-mann neighbourhood), 8 (Moore neighborhood) or 16. Available only if you have selected the "least-cost" or "commute-time" distance.

mask

object of class sf, sfc, sfg. SpatialPolygons. For higher processing speed of "least-cost" or "commute-time" distances. Use this option to clip the resistance at the extent of the mask.

threshold

numeric. Distance threshold, pairs of nodes with a distance value above this threshold will be discarded.

geometry_out

numeric. You can use this argument if you have selected the "least-cost" or "commute-time" distance. If some spatial geometries are out of the resistance extent, then a buffer zone the large enough to cover these spatial geometries and with this numeric value will be added to the resistance, so that it is possible to calculate a cost distance value for the pairs of nodes that involve these geometries and avoid an error. If NULL, then the Euclidean distance between centroids (type = "centroid") will be calculated to find these distances.

bounding_circles

numeric. If a value is entered, this will create bounding circles around pairs of core areas (recommended for speed, large resistance rasters or pixel resolution < 150 m). Buffer distances are entered in map units.

parallel

logical or numerical. Recommended for a large number of nodes or very large RasterLayer.

ActiveParallel

logical. It should be TRUE if there is already an open parallelization plan.

least_cost.java

logical. If TRUE then the programming language and computing platform 'java' will be used to estimate the least-cost distance using a resistance raster and the following formula: function(x) 1/mean(x). It is necessary to have java installed. This option use the package graph4lg to reduce computation times.

cores.java

numeric. Computer cores used to run the .jar file (see, graph4lg ), default = 1.

ram.java

numeric. RAM gigabytes to run the .jar file (see, graph4lg ), default = NULL.

pairwise

logical. If TRUE a pairwise table of class data.frame is returned (From, To, distance) otherwise it will be a matrix.

write

character. Output path, with name and extension ".txt".

Value

Exports a euclidean or cost distance table between pairs of nodes.