flow.dispersion: Compute flow-based cost or conductance

In rWind: Download, Edit and Include Wind and Sea Currents Data in Ecological and Evolutionary Analysis

Compute flow-based cost or conductance

Description

flow.dispersion computes movement conductance through a flow such as sea or wind currents. Passive movement uses a restricted version of the formula described in Felícisimo et al. (2008):

Usage

cost.FMGS(
  wind.direction,
  wind.speed,
  target,
  type = c("passive", "active"),
  speed.scale = NULL
)

flow.dispersion(
  x,
  fun = cost.FMGS,
  output = "transitionLayer",
  type = c("passive", "active"),
  speed.scale = NULL,
  ...
)

Arguments

wind.direction	A vector or scalar containing wind directions.
wind.speed	A vector or scalar containing wind speeds.
target	direction of the target cell
type	Movement model. In "passive" mode, deviations of 90 degrees or more from the flow direction are forbidden. In "active" mode, supportive flow lowers relative cost and opposing flow raises it; movement against the flow remains possible.
speed.scale	Positive reference speed for the active model. If NULL, the median positive speed of the complete raster layer is used. For comparisons among dates or regions, supply one fixed value in the same units as wind.speed.
x	A SpatRaster returned by wind2raster() with direction and speed layers, a legacy RasterStack, or a list of either type.
fun	A function to compute the cost to move between cells. The default is cost.FMGS from Felicísimo et al. (2008), see details.
output	This argument allows to select different kinds of output. "raw" mode creates a matrix (class "dgCMatrix") with transition costs between all cells in the raster. "transitionLayer" creates a TransitionLayer object with conductance values to be used with "gdistance" package.
...	Further arguments passed to or from other methods.

Details

Cost=(1/Speed)*(HorizontalFactor)

where HorizontalFactor incrementally penalizes angular deviations from the flow direction and prevents passive movement at deviations of 90 degrees or more. Active movement uses a general relative index based on signed flow support rather than the original formula.

Value

flow.dispersion() returns a gdistance::TransitionLayer for output = "transitionLayer", with directed conductances (1/cost) between the eight neighbouring cells, or a sparse matrix of class dgCMatrix containing edge costs for output = "raw". Rows index origins and columns index destinations. Costs average local costs at both cells and are multiplied by sqrt(2) for diagonal moves. In the raw matrix, Inf marks forbidden neighbouring moves; zeros represent absent edges, not free moves. In the conductance matrix, forbidden moves have zero conductance. A list input returns a list of the corresponding output objects.

cost.FMGS() returns numeric local movement costs for the supplied flow values and target direction (a vector, or a matrix for matrix inputs). Passive costs are the horizontal factor divided by speed, with Inf for forbidden moves. Active costs follow cost.active().

Note

The active model is a relative connectivity index, not a mechanistic model of animal movement. It ignores the component of flow perpendicular to movement.

Costs are relative per grid step. The diagonal correction assumes a square grid, but no correction is made for the changing physical distances of longitude/latitude cells. Do not interpret results as physical time, energy, or distance or compare them directly across grid resolutions or distant latitude ranges.

Note that for large data sets, it could take a while. For large study areas is strongly advised perform the analysis in a remote computer or a cluster.

Author(s)

Javier Fernández-López; Klaus Schliep; Yurena Arjona

References

Felicísimo, Á. M., Muñoz, J., & González-Solis, J. (2008). Ocean surface winds drive dynamics of transoceanic aerial movements. PLoS One, 3(8), e2928.

Jacob van Etten (2017). R Package gdistance: Distances and Routes on Geographical Grids. Journal of Statistical Software, 76(13), 1-21. doi:10.18637/jss.v076.i13

See Also

wind.dl, wind2raster

Examples

require(gdistance)

data(wind.data)

wind <- wind2raster(wind.data)

Conductance <- flow.dispersion(wind, type = "passive")

conductance_matrix <- gdistance::transitionMatrix(Conductance)
conductance_matrix[1:6, 1:6]
Matrix::image(conductance_matrix)

rWind documentation built on Oct. 18, 2026, 5:08 p.m.