Package {regional}

Title: Intra- and Inter-Regional Similarity
Version: 0.5.1
Description: Calculates intra-regional and inter-regional similarities based on user-provided spatial vector objects (regions) and spatial raster objects (cells with values). Implemented metrics include inhomogeneity, isolation (Haralick and Shapiro (1985) <doi:10.1016/S0734-189X(85)90153-7>, Jasiewicz et al. (2018) <doi:10.1016/j.cageo.2018.06.003>), and distinction (Nowosad (2021) <doi:10.1080/13658816.2021.1893324>).
License: MIT + file LICENSE
Encoding: UTF-8
Imports: philentropy (≥ 0.6.0), terra
BugReports: https://github.com/Nowosad/regional/issues
URL: https://jakubnowosad.com/regional/
Suggests: supercells, sf, testthat (≥ 3.0.0), covr, proxy, dtwclust
Config/testthat/edition: 3
Config/roxygen2/version: 8.1.0
NeedsCompilation: no
Packaged: 2026-11-07 16:44:41 UTC; jn
Author: Jakub Nowosad ORCID iD [aut, cre]
Maintainer: Jakub Nowosad <nowosad.jakub@gmail.com>
Repository: CRAN
Date/Publication: 2026-11-07 17:40:02 UTC

regional: Intra- and Inter-Regional Similarity

Description

Calculates intra-regional and inter-regional similarities based on user-provided spatial vector objects (regions) and spatial raster objects (cells with values). Implemented metrics include inhomogeneity, isolation (Haralick and Shapiro (1985) doi:10.1016/S0734-189X(85)90153-7, Jasiewicz et al. (2018) doi:10.1016/j.cageo.2018.06.003), and distinction (Nowosad (2021) doi:10.1080/13658816.2021.1893324).

Author(s)

Maintainer: Jakub Nowosad nowosad.jakub@gmail.com (ORCID)

Authors:

See Also

Useful links:

Distinction

Description

Distinction is an average distance between the focus region and all of the other regions.

Usage

reg_distinction(
  region,
  raster,
  dist_fun = "euclidean",
  sample_size = 1,
  unit = "log2",
  na.rm = FALSE,
  optimize_for = c("memory", "speed"),
  ...
)

Arguments

region

An object of class sf with a POLYGON or MULTIPOLYGON geometry type

raster

An object of class SpatRaster (terra)

dist_fun

Distance measure used. This function uses philentropy::distance (run philentropy::getDistMethods() to find possible distance measures) or proxy::dist (run names(proxy::pr_DB$get_entries()) to find possible distance measures) in the background. It is also possible to use "dtw" (dynamic time warping)

sample_size

Proportion of the cells inside of each region to be used in calculations. Value between 0 and 1. It is also possible to specify an integer larger than 1, in which case the specified number of cells of each region will be used in calculations.

unit

a character string specifying the logarithm unit that should be used to compute distances that depend on log computations.

na.rm

Whether NA values should be stripped from the calculations.

optimize_for

A character string specifying what to optimize for (default: "memory"). "memory" extracts values on the fly for each comparison, which minimizes memory usage but can be substantially slower for large rasters or many regions. "speed" caches per-region extracts once and reuses them across comparisons, which increases memory usage but is typically much faster.

...

Additional arguments for philentropy::dist_one_one, proxy::dist, or dtwclust::dtw_basic. When dist_fun = "dtw" is used, ndim should be set to specify how many dimension the input raster time-series has.

Value

A vector with the distinction values

Examples

## Not run: 
  library(terra)
  if (requireNamespace("sf", quietly = TRUE)) {
    library(sf)
    volcano = rast(system.file("raster/volcano.tif", package = "regional"))
    vr = read_sf(system.file("regions/volcano_regions.gpkg", package = "regional"))
    vr$dis = reg_distinction(vr, volcano, sample_size = 0.5)

    mean(vr$dis)

    plot(volcano)
    plot(vect(vr), add = TRUE)
    plot(volcano)
    plot(vr["dis"], add = TRUE)
 }

## End(Not run)

Inhomogeneity

Description

Inhomogeneity measures a degree of mutual dissimilarity between values of all cells in a region.

Usage

reg_inhomogeneity(
  region,
  raster,
  dist_fun = "euclidean",
  sample_size = 1,
  unit = "log2",
  na.rm = FALSE,
  ...
)

Arguments

region

An object of class sf with a POLYGON or MULTIPOLYGON geometry type

raster

An object of class SpatRaster (terra)

dist_fun

Distance measure used. This function uses philentropy::distance (run philentropy::getDistMethods() to find possible distance measures) or proxy::dist (run names(proxy::pr_DB$get_entries()) to find possible distance measures) in the background. It is also possible to use "dtw" (dynamic time warping)

sample_size

Proportion of the cells inside of each region to be used in calculations. Value between 0 and 1. It is also possible to specify an integer larger than 1, in which case the specified number of cells of each region will be used in calculations.

unit

A character string specifying the logarithm unit that should be used to compute distances that depend on log computations.

na.rm

Whether NA values should be stripped from the calculations.

...

Additional arguments for philentropy::dist_one_one, proxy::dist, or dtwclust::dtw_basic. When dist_fun = "dtw" is used, ndim should be set to specify how many dimension the input raster time-series has.

Value

A vector with the inhomogeneity values

Examples

## Not run: 
  library(terra)
  if (requireNamespace("sf", quietly = TRUE)) {
    library(sf)
    volcano = rast(system.file("raster/volcano.tif", package = "regional"))
    vr = read_sf(system.file("regions/volcano_regions.gpkg", package = "regional"))
    vr$inh = reg_inhomogeneity(vr, volcano, sample_size = 1)

    mean(vr$inh)

    plot(volcano)
    plot(vect(vr), add = TRUE)
    plot(volcano)
    plot(vr["inh"], add = TRUE)
 }

## End(Not run)

Isolation

Description

Isolation is an average distance between the focus region and all of its neighbors.

Usage

reg_isolation(
  region,
  raster,
  dist_fun = "euclidean",
  sample_size = 1,
  unit = "log2",
  na.rm = FALSE,
  optimize_for = c("memory", "speed"),
  ...
)

Arguments

region

An object of class sf with a POLYGON or MULTIPOLYGON geometry type

raster

An object of class SpatRaster (terra)

dist_fun

Distance measure used. This function uses philentropy::distance (run philentropy::getDistMethods() to find possible distance measures) or proxy::dist (run names(proxy::pr_DB$get_entries()) to find possible distance measures) in the background. It is also possible to use "dtw" (dynamic time warping)

sample_size

Proportion of the cells inside of each region to be used in calculations. Value between 0 and 1. It is also possible to specify an integer larger than 1, in which case the specified number of cells of each region will be used in calculations.

unit

a character string specifying the logarithm unit that should be used to compute distances that depend on log computations.

na.rm

Whether NA values should be stripped from the calculations.

optimize_for

A character string specifying what to optimize for (default: "memory"). "memory" extracts values on the fly for each comparison, which minimizes memory usage but can be substantially slower for large rasters or many regions. "speed" caches per-region extracts once and reuses them across comparisons, which increases memory usage but is typically much faster.

...

Additional arguments for philentropy::dist_one_one, proxy::dist, or dtwclust::dtw_basic. When dist_fun = "dtw" is used, ndim should be set to specify how many dimension the input raster time-series has.

Value

A vector with the isolation values

Examples

## Not run: 
 library(terra)
 if (requireNamespace("sf", quietly = TRUE)) {
   library(sf)
   volcano = rast(system.file("raster/volcano.tif", package = "regional"))
   vr = read_sf(system.file("regions/volcano_regions.gpkg", package = "regional"))
   vr$iso = reg_isolation(vr, volcano, sample_size = 1)

   mean(vr$iso)

   plot(volcano)
   plot(vect(vr), add = TRUE)
   plot(volcano)
   plot(vr["iso"], add = TRUE)
 }

## End(Not run)