Skip to contents

Build pgeometry objects from a point dataset

Source: R/construction_module.R
spa_creator.Rd

spa_creator() builds a set of spatial plateau objects from a given point dataset assigned with domain-specific numerical values.

Usage

spa_creator(tbl, fuzz_policy = "fsp", const_policy = "voronoi", ...)

Arguments

tbl

A data.frame or tibble object with three columns: (x, y, z).

fuzz_policy

The fuzzification policy to be employed by the algorithm. See details below.

const_policy

The construction policy to be used by the algorithm. See details below.

...

<dynamic-dots> Parameters for the chosen policies. See details below.

Value

A tibble in the format (class, pgeometry), where class is a character column and pgeometry is a list of pgeometry objects. This means that a spatial plateau object is created for representing a specific class of the point dataset.

Details

The spa_creator() function implements a two-stage construction method that takes as input a point dataset and produces a set of spatial plateau objects as output.

The input tbl is a point dataset (data.frame or tibble object) where each point represents the location of a phenomenon treated by the application. Further, each point is annotated with numerical data that describe its meaning in the application. Therefore, tbl must have three columns: (x, y, z). The columns x, y are the coordinate pairs, and z is the column containing domain-specific numeric values.

The parameter fuzz_policy refers to the method used by the fuzzification stage. This stage aims to assign membership degrees to each point of the dataset. It accepts two possible values: "fsp" (default) or "fcp".

"fsp" stands for fuzzy set policy and requires two parameters that should be informed in ...:

  • classes: A character vector containing the name of classes.

  • mfs: A vector of membership functions. Each membership function i represents the class i, where i in length(classes). See the provided examples for more information on how to build membership functions.

"fcp" stands for fuzzy clustering policy and requires the e1071 package. Its possible parameters informed in ... are:

  • k: A numeric value that refers to the number of groups to be created.

  • method: A fuzzy clustering method of the package e1071, which can be either "cmeans" (default) or "cshell".

  • use_coords: A Boolean value to indicate whether the columns (x, y) should be used in the clustering algorithm (default is FALSE).

  • iter: A numeric indicating the number of maximum iterations of the clustering algorithm (default is 100).

An optional and common parameter for both fuzzification stages is "digits". This is an integer value that indicates the number of decimal digits of the membership degrees calculated by the fuzzification stage. That is, it is used to round membership degrees to the specified number of decimal places. Be careful with this optional parameter! If you specify a low value for "digits", some membership degrees could be rounded to 0 and thus, some components would not be created.

The parameter const_policy refers to the method used by the construction stage. This stage aims to create polygons from the labeled point dataset and use them to build spatial plateau objects. It accepts three possible values: "voronoi" (default), "delaunay", or "convex_hull".

"voronoi" stands for Voronoi diagram policy and has two optional parameter that can be provided in ...:

  • base_poly: An sfg object that will be used to clip the generated polygons. If this parameter is not provided, the Voronoi is created by using a bounding box (standard behavior of the package sf).

  • d_tolerance: It refers to the parameter dTolerance employed by the function st_voronoi() of the package sf.

"delaunay" stands for Delaunay triangulation policy, which accepts the following parameters in ...:

  • base_poly: An sfg object that will be used to clip the generated triangles.

  • tnorm: A t-norm used to calculate the membership degree of the triangle. It should be the name of a vectorized function. Possible values are "min" (default) and "prod". Note that it is possible to use your own t-norms. A t-norm should has the following signature: FUN(x) where x is a numeric vector. Such a function should return a single numeric value.

  • d_tolerance: It refers to the parameter dTolerance employed by the function st_triangulate() of the package sf.

"convex_hull" stands for Convex hull policy, which accepts the following parameters in ...:

  • degrees: A numeric vector containing the membership degrees that will be used to create the components. The default vector is defined by seq(0.05, 1, by = 0.05).

  • d: A numeric value representing the tolerance distance to compute the membership degree between the elements of m and the membership degrees of the points. The default is 0.05.

  • base_poly: An sfg object that will be used to clip the generated polygons.

References

Carniel, A. C.; Venâncio, P. V. A. B; Schneider, M. fsr: An R package for fuzzy spatial data handling. Transactions in GIS, vol. 27, no. 3, pp. 900-927, 2023.

Underlying concepts and formal definitions of the two-stage construction method is introduced in:

Examples

library(tibble)
library(sf)
library(ggplot2)
 
# Defining two different types of membership functions
trap_mf <- function(a, b, c, d) {
  function(x) {
    pmax(pmin((x - a)/(b - a), 1, (d - x)/(d - c), na.rm = TRUE), 0)
  }
}

trim_mf <- function(a, b, c) {
  function(x) {
    pmax(pmin((x - a)/(b - a), (c - x)/(c - b), na.rm = TRUE), 0)
  }
}

set.seed(7)
tbl = tibble(x = runif(10, min = 0, max = 30), 
             y = runif(10, min = 0, max = 50), 
             z = runif(10, min = 0, max = 100))
classes <- c("cold", "hot")
cold_mf <- trap_mf(0, 10, 20, 35)
hot_mf <- trim_mf(35, 50, 100)

# Using the standard fuzzification policy based on fuzzy sets
res <- spa_creator(tbl, classes = classes, mfs = c(cold_mf, hot_mf))
# \dontrun{
res  
#> # A tibble: 2 × 2
#>   class pgeometry
#>   <chr> <list>   
#> 1 cold  <pregion>
#> 2 hot   <pregion>
plot(res$pgeometry[[1]]) + ggtitle("Cold")

plot(res$pgeometry[[2]]) + ggtitle("Hot")


# Getting the convex hull on the points to clip plateau region objects during their constructions
pts <- st_as_sf(tbl, coords = c(1, 2))
ch <- st_convex_hull(do.call(c, st_geometry(pts)))
res <- spa_creator(tbl, classes = classes, mfs = c(cold_mf, hot_mf), base_poly = ch)
plot(res$pgeometry[[1]]) + ggtitle("Cold (with clipped boundaries)")

plot(res$pgeometry[[2]]) + ggtitle("Hot (with clipped boundaries)")

 
# Using the fuzzification policy based on fuzzy clustering
spa_creator(tbl, fuzz_policy = "fcp", k = 4)
#> # A tibble: 4 × 2
#>   class  pgeometry
#>   <chr>  <list>   
#> 1 group1 <pregion>
#> 2 group2 <pregion>
#> 3 group3 <pregion>
#> 4 group4 <pregion>

spa_creator(tbl, fuzz_policy = "fcp", k = 4, digits = 2)
#> # A tibble: 4 × 2
#>   class  pgeometry
#>   <chr>  <list>   
#> 1 group1 <pregion>
#> 2 group2 <pregion>
#> 3 group3 <pregion>
#> 4 group4 <pregion>

# Varying the construction policy
spa_creator(tbl, fuzz_policy = "fcp", k = 3, const_policy = "delaunay")
#> # A tibble: 3 × 2
#>   class  pgeometry
#>   <chr>  <list>   
#> 1 group1 <pregion>
#> 2 group2 <pregion>
#> 3 group3 <pregion>

spa_creator(tbl, fuzz_policy = "fcp", const_policy = "delaunay", k = 3, tnorm = "prod")
#> # A tibble: 3 × 2
#>   class  pgeometry
#>   <chr>  <list>   
#> 1 group1 <pregion>
#> 2 group2 <pregion>
#> 3 group3 <pregion>

spa_creator(tbl, fuzz_policy = "fcp", k = 2, digits = 2, 
            degrees = seq(0.1, 1, by = 0.1), d = 0.05, const_policy = "convex_hull")
#> # A tibble: 2 × 2
#>   class  pgeometry
#>   <chr>  <list>   
#> 1 group1 <pregion>
#> 2 group2 <pregion>

spa_creator(tbl, classes = classes, mfs = c(cold_mf, hot_mf), const_policy = "delaunay")
#> # A tibble: 2 × 2
#>   class pgeometry
#>   <chr> <list>   
#> 1 cold  <pregion>
#> 2 hot   <pregion>
            
spa_creator(tbl, classes = classes, mfs = c(cold_mf, hot_mf), 
            digits = 2, const_policy = "convex_hull")
#> # A tibble: 2 × 2
#>   class pgeometry
#>   <chr> <list>   
#> 1 cold  <pregion>
#> 2 hot   <pregion>
# }