Skip to contents

Process a given function using a hierarchy in input data

Source: R/scale_process.R
par_hierarchy.Rd

"Hierarchy" refers to a system, which divides the entire study region into multiple subregions. It is oftentimes reflected in an area code system (e.g., FIPS for US Census geographies, HUC-4, -6, -8, etc.). future::multicore, future::multisession, future::cluster will parallelize the work by splitting lower level features into several higher level feature group. For details of the terminology in future package, refer to plan. Each thread will process the number of lower level features in each higher level feature. Please be advised that accessing the same file simultaneously with multiple processes may result in errors.

Usage

par_hierarchy(
  regions,
  regions_id = NULL,
  unit_id = NULL,
  debug = FALSE,
  fun_dist,
  ...
)

Arguments

regions

sf/SpatVector object. Computational regions. Only polygons are accepted.

regions_id

character(nrow(regions)) or character(1). The regions will be split by the common level value. The level should be higher than the original data level. A field name with the higher level information is also accepted.

unit_id

character(1). Default is NULL. If NULL, the lower level units will be split by the intersection between a higher level region and lower level units. Otherwise, the first element of the ellipsis argument ... is used to split the lower level units.

debug

logical(1). Default is FALSE If a unit computation fails, the error message and the regions_id value where the error occurred will be included in the output.

fun_dist

sf, terra, or chopin functions.

...

Arguments passed to the argument fun_dist. The second place should get a vector or raster dataset from which you want to extract or calculate values. For example, a raster dataset when vector-raster overlay is performed.

Value

a data.frame object with computation results. For entries of the results, consult the function used in fun_dist argument.

Note

In dynamic dots (...), the first and second arguments should be the fun_dist arguments where sf/SpatVector objects are accepted. Virtually any sf/terra functions that accept two arguments can be put in fun_dist, but please be advised that some spatial operations do not necessarily give the exact result from what would have been done single-thread. For example, distance calculated through this function may return the lower value than actual because the computational region was reduced. This would be the case especially where the target features are spatially sparsely distributed.

See also

Other Parallelization: par_cut_coords(), par_fallback(), par_grid(), par_group_grid(), par_make_grid(), par_make_gridset(), par_merge_grid(), par_multirasters()

Author

Insang Song geoissong@gmail.com

Examples