Skip to contents

Species Corridors Estimation

EGCorrs.Rd

Sea Currents To Evolutionary Game Theoretic Model for Species Corridors Estimation

Usage

EGCorrs(component_u, component_v, origin_areas, destination_areas,
         npoints = 40L, lambda = 1, niters = 100L, k_neighbors = 7L,
         nearest_grid_nodes = 4L, mask_shapefile = NULL, all_networks = FALSE,
         progBar = TRUE)

Arguments

component_u

SpatRaster object with horizontal direction.

component_v

SpatRaster object with vertical direction.

origin_areas

sf object with origin areas, as POLYGON or MULTIPOLYGON rows.

destination_areas

sf object with destination areas, as POLYGON or MULTIPOLYGON rows.

npoints

integer object with the number of random points for origin and destination areas. It must be positive. The default is 40L.

lambda

numeric object with the aggregation parameter \(\lambda\). The default value is 1.

niters

integer object with the number of points for origin and destination areas. It must be positive. The default value is 100L.

k_neighbors

integer object indicating the number of \(k\) of the nearest neighbors to use from the components of horizontal and vertical directions. The default value is 7L nearest neighbors.

nearest_grid_nodes

integer object indicating the number of \(k\) of the nearest neighbors to use from the random points inside origin and destination areas. The default value is 4L nearest neighbors.

mask_shapefile

Optional sf or SpatVector object for masking component_u and component_v SpatRaster objects. The default value is NULL, indicating that no mask is performed.

all_networks

logical object indicating the return of sfnetwork per iteration.

progBar

logical object indicating whether to print progress bar or not. The default is printing (progBar=TRUE).

Details

Sea currents data of the input are transformed into weighted directed graph connectivity data. Each centroid of component_u and component_v is considered as a separate graph node. Except from these points, random npoints random origin points are generated inside the origin_areas polygons/multipolygons and npoints random destination points are generated inside the destination_areas polygons/multipolygons. These points are equally or near equally distributed between each group of points, in a way that totally npoints random points are contained inside origin_areas and npoints random points are contained inside destination_areas. The directions produced from these points are calculated, multiplied by \(\lambda\) and finally minmax-scaled in \([0-1]\). Thereafter, shortest paths between origin and destination points are computed niters times, following a evolutionary game theoretic model.

Extent, resolution and coordinate system of both must have the same for both component_u and component_v; otherwise an error stops the function's execution. In case of mismatches between the area of these two components and origin_areas or destination_areas, then the intersection of these areas and the components is used instead of these areas. In case that a mask_shapefile is provided, then it is internally assured that it has the same resolution or coordinates with component_u and a warning is prompted. Reproducibility of the results could be guranteed by the use of base::set.seed before using the function.

Value

SeaGraphs object, which is also a list object containing the following elements:

  • solution_edges: sf object representing the final edges of the solution after niters iterations.

  • net_result_congestion: sfnetwork object representing the final solution after niters iterations. Each row has the following items for each graph edge/link \(l\):

    • from: edge start for a graph vertex ID.

    • to: edge end for a graph vertex ID.

    • c_l: value of cost function \(c_l\).

    • u_l: value of utility \(u_l\).

    • u_l_population: value of utility compared to the total population of the game (where \(population = niters * npoints\)).

    • u_l_perc: value of u_l_population normalized by the population of the current iteration (\(u_{l_{_{perc}}}\)).

    • u_l_perc_times_c_l: u_l_perc * c_l.

  • list_of_edges_freq: list object containing data.frame objects with the the frequency that shortest path corridors pass through each graph vertex, for each iteration.

  • list_of_congestion: list object containing data.frame objects with congenstion metrics per graph edge for each one of the niters iterations. Each row has a number indicating the graph edge/link ID, according to the column link. All the other columns are as in net_result_congestion output.

  • metrics_df: data.frame object with summarization of list_of_congestion values accross, where:

    • niters: number of the corresponding iteration.

    • rmse_u_l_perc: \(RMSE(u_{l_{_{perc}}})\).

    • rmse_u_l_perc_times_c_l: \(RMSE(u_{l_{_{perc}}} * c_l)\).

    • rmse_c_l: \(RMSE(c_l)\).

    • sum_c_l: \(\sum _l{c_l}\).

  • origin_points: sf POINT object representing the origin points.

  • destination_points: sf POINT object representing the destination points.

  • list_of_networks: If all_networks = TRUE, then it is a list containing net_result_congestion item for each iteration. Else, it is NULL.

Examples

set.seed(42)
component_u       <- get_component_u()
component_v       <- get_component_v()
origin_areas      <- get_origin_areas()
#> Reading layer `origin_areas' from data source 
#>   `/home/runner/work/_temp/Library/EGCorrs/external/origin_areas/origin_areas.shp' 
#>   using driver `ESRI Shapefile'
#> Simple feature collection with 1 feature and 1 field
#> Geometry type: POLYGON
#> Dimension:     XY
#> Bounding box:  xmin: 22.86969 ymin: 36.04912 xmax: 23.13855 ymax: 36.39421
#> Geodetic CRS:  WGS 84
destination_areas <- get_destination_areas()
#> Reading layer `destination_areas' from data source 
#>   `/home/runner/work/_temp/Library/EGCorrs/external/destination_areas/destination_areas.shp' 
#>   using driver `ESRI Shapefile'
#> Simple feature collection with 1 feature and 1 field
#> Geometry type: POLYGON
#> Dimension:     XY
#> Bounding box:  xmin: 24.3053 ymin: 36.62173 xmax: 24.49323 ymax: 36.75966
#> Geodetic CRS:  WGS 84
# Warnings are thrown because of reassuring that components u/v and
# origin/destination areas are intersecting
out               <- EGCorrs(component_u, component_v, origin_areas,
                         destination_areas, npoints = 1,  niters = 10,
                         progBar=FALSE)
#> Warning: attribute variables are assumed to be spatially constant throughout all geometries
#> Warning: attribute variables are assumed to be spatially constant throughout all geometries
## Warning messages:
## 1: attribute variables are assumed to be spatially constant throughout all
## geometries
## 2: attribute variables are assumed to be spatially constant throughout all
## geometries