detectFronts: Apply gradient-based methodologies to environmental data

Description Usage Arguments Details Value References Examples

View source: R/grec-main.R

Description

This function takes a environmental map (as a numeric matrix, array, XYZlist or RasterLayer) and allows the users to apply methodologies based on gradient-searching.

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
## S3 method for class 'RasterLayer'
detectFronts(x, method = "BelkinOReilly2009", intermediate = FALSE, ...)

## S3 method for class 'array'
detectFronts(x, method = "BelkinOReilly2009", intermediate = FALSE, ...)

## Default S3 method:
detectFronts(
  x,
  method = "BelkinOReilly2009",
  intermediate = FALSE,
  ConvolNormalization = TRUE,
  ...
)

detectFronts(
  x,
  method = "BelkinOReilly2009",
  intermediate = FALSE,
  ConvolNormalization = TRUE,
  ...
)

## S3 method for class 'list'
detectFronts(x, method = "BelkinOReilly2009", intermediate = FALSE, ...)

## S3 method for class 'matrix'
detectFronts(x, method = "BelkinOReilly2009", intermediate = FALSE, ...)

Arguments

x

Main input of class matrix, array, XYZ list or RasterLayer. See 'Details.'

method

character string indicating the method that will be used. See 'Details'.

intermediate

logical indicating whether to get the intermediate matrices (TRUE) or just the final one (FALSE).

...

Extra arguments that will depend on the selected method. See Details.

ConvolNormalization

logical indicating if convolutions will make a normalization (TRUE by default). See Details.

Details

Version 1.3.x performs two methods:

  1. BelkinOReilly2009 (default): Based on Belkin & O'Reilly (2009) paper, it uses a Contextual Median Filter (CMF) for smoothing the original data.

  2. median_filter: it uses a typical median filter (MF) for smoothing the original data. It also allows the user to change the window size for median filter (3 as default).

x could be given as a single numeric matrix from an environmental map. Othersiwe it also can be set as a three-dimension XYZ list: 'x' (a vector of longitudes), 'y' (vector of latitudes) and 'z' as a matrix of dimensions length(x$x)xxlength(x$y). You can also specify x as a RasterLayer or array object. If x is an array, it must have 3 dimensions: lon, lat and time. It is not required to specify the dimnames. The output will preserve all the attributes of input.

... allows the (advanced) users to modify some aspects of filter application. Depending on the selected methodology, some parameters can be modified:

times

numeric. How many times do you want to apply the method?

kernelValues

numeric. Vector with which are going to be used in convolution to identify Vertical and Horizontal gradients. By default, it will be the typical Sobel kernels.

radius

numeric. If median filter method was selected, it allows to change the window size of the filter.

Normalization is a common practice in convolution in order to ensure that outputs are weighted within original range of values. It is achieved dividing outputs of convolution by sum(abs(kernel)). It is hardly recomended to use normalization in order to have always coherent values in regards of the original inputs; however, it can be deactivated by using ConvolNormalization argument.

Finally, Belkin & O'Reilly work proposed a log transformation after the gradient calculation. However, this step has not been considered as default in the function due to its application is focused on Chlorophyll values (maps).

Value

The output will preserve the input class (matrix, array, list or RasterLayer).

References

Belkin, I. M., & O'Reilly, J. E. (2009). An algorithm for oceanic front detection in chlorophyll and SST satellite imagery. Journal of Marine Systems, 78(3), 319-326 (http://dx.doi.org/10.1016/j.jmarsys.2008.11.018).

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
data(sst)
exampleSSTData <- list(x = sst$longitude,
                       y = sst$latitude,
                       z = sst$sst[,,1])

data(chl)
exampleChlData <- list(x = chl$longitude,
                       y = chl$latitude,
                       z = chl$chlorophyll[,,1])

# Simple application (over a XYZ list)
out_sst <- detectFronts(x = exampleSSTData)
out_chl <- detectFronts(x = exampleChlData)

# External transformation for chl data
out_chl$z <- log10(out_chl$z)

par(mfrow = c(2, 2), mar = rep(0, 4), oma = rep(0, 4))

image(exampleSSTData, col = colPalette, axes = FALSE)
mtext(text = "Original SST", side = 3, line = -2, adj = 0.99, cex = 1.2)

image(out_sst, col = colPalette, axes = FALSE)
mtext(text = "SST gradient", side = 3, line = -2, adj = 0.99, cex = 1.2)

image(exampleChlData, col = colPalette, axes = FALSE)
mtext(text = "Original Chlorophyll", side = 3, line = -2, adj = 0.99, cex = 1.2)

image(out_chl, col = colPalette, axes = FALSE)
mtext(text = "Chlorophyll gradient\n(log scale)", side = 3, line = -4, adj = 0.99,
      cex = 1.2)

Example output

Loading required package: imagine
Loading required package: raster
Loading required package: sp

grec documentation built on Feb. 19, 2020, 5:07 p.m.