Title: Creates Co-Occurrence Matrices of Spatial Data
Version: 0.9.6
Description: Builds co-occurrence matrices based on spatial raster data. It includes creation of weighted co-occurrence matrices (wecoma) and integrated co-occurrence matrices (incoma; Vadivel et al. (2007) <doi:10.1016/j.patrec.2007.01.004>).
License: MIT + file LICENSE
Encoding: UTF-8
LazyData: false
RoxygenNote: 7.3.3
Depends: R (≥ 2.10)
LinkingTo: Rcpp, RcppArmadillo
Imports: Rcpp
Suggests: tinytest, covr, knitr, rmarkdown
URL: https://jakubnowosad.com/comat/
BugReports: https://github.com/Nowosad/comat/issues
VignetteBuilder: knitr
NeedsCompilation: yes
Packaged: 2025-09-25 09:57:04 UTC; jn
Author: Jakub Nowosad ORCID iD [aut, cre], Maximillian H.K. Hesselbarth [ctb] (Co-author of underlying C++ code for get_class_index_map(), get_unique_values(), and rcpp_get_coma() functions), Marco Sciaini [ctb] (Co-author of underlying C++ code for get_class_index_map(), get_unique_values(), and rcpp_get_coma() functions), Sebastian Hanss [ctb] (Co-author of underlying C++ code for get_class_index_map(), get_unique_values(), and rcpp_get_coma() functions)
Maintainer: Jakub Nowosad <nowosad.jakub@gmail.com>
Repository: CRAN
Date/Publication: 2025-09-26 22:00:08 UTC

comat: Creates Co-Occurrence Matrices of Spatial Data

Description

Builds co-occurrence matrices based on spatial raster data. It includes creation of weighted co-occurrence matrices (wecoma) and integrated co-occurrence matrices (incoma; Vadivel et al. (2007) doi:10.1016/j.patrec.2007.01.004).

Author(s)

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

Other contributors:

See Also

Useful links:

Create neighborhood coordinates

Description

This function creates a neighborhood coordinates matrix based on the directions parameter.

Usage

create_neighborhood(directions)

Arguments

directions

The number of directions in which cells should be connected: 4 (rook's case), 8 (queen's case), or a neighbourhood matrix. The neighbourhood matrix should have one cell with value 0 (the focal cell), and at least one cell with value 1 (the adjacent cells). Cells with other values (e.g. NA) are ignored.

Create a co-located co-occurrence matrix (cocoma)

Description

Create a co-located co-occurrence matrix (cocoma)

Usage

get_cocoma(x, y, neighbourhood = 4, classes = NULL)

Arguments

x

A matrix with categories

y

A matrix with categories

neighbourhood

The number of directions in which cell adjacencies are considered as neighbours: 4 (rook's case) or 8 (queen's case). The default is 4.

classes

A list of length 2 with the values of selected classes from the x and y objects. It is used to calculate cocoma only for selected classes.

Value

A co-located co-occurrence matrix

Examples

library(comat)
data(raster_x, package = "comat")
data(raster_x_na, package = "comat")

coom = get_cocoma(raster_x, raster_x_na)
coom

get_cocoma(raster_x, raster_x_na, classes = list(c(1, 2), 3))

Create a co-located co-occurrence vector (cocove)

Description

Converts a co-located co-occurrence matrix (cocoma) to a co-located co-occurrence vector (cocove)

Usage

get_cocove(x, ordered = TRUE, normalization = "none")

Arguments

x

A matrix - an output of the get_cocoma() function

ordered

The type of pairs considered. Either "ordered" (TRUE) or "unordered" (FALSE). The default is TRUE.

normalization

Should the output vector be normalized? Either "none" or "pdf". The "pdf" option normalizes a vector to sum to one. The default is "none".

Value

A co-located co-occurrence vector

Examples

library(comat)
data(raster_x, package = "comat")
data(raster_x_na, package = "comat")

coom = get_cocoma(raster_x, raster_x_na)
coom

coov = get_cocove(coom)
coov

Create a co-occurrence matrix (coma)

Description

Create a co-occurrence matrix (coma)

Usage

get_coma(x, neighbourhood = 4, classes = NULL)

Arguments

x

A matrix with categories

neighbourhood

The number of directions in which cell adjacencies are considered as neighbours: 4 (rook's case) or 8 (queen's case). The default is 4.

classes

A vector or a list with the values of selected classes from the x object. It is used to calculate coma only for selected classes.

Value

A co-occurrence matrix

Examples

#library(comat)
data(raster_x, package = "comat")

com = get_coma(raster_x)
com

com2 = get_coma(raster_x, classes = c(1, 3))
com2

data(raster_x_na, package = "comat")
com3 = get_coma(raster_x_na, classes = c(0:3, NA))
com3

Create a co-occurrence vector (cove)

Description

Converts a co-occurrence matrix (coma) to a co-occurrence vector (cove)

Usage

get_cove(x, ordered = TRUE, normalization = "none")

Arguments

x

A matrix - an output of the get_coma() function

ordered

The type of pairs considered. Either "ordered" (TRUE) or "unordered" (FALSE). The default is TRUE.

normalization

Should the output vector be normalized? Either "none" or "pdf". The "pdf" option normalizes a vector to sum to one. The default is "none".

Value

A co-occurrence vector

Examples

library(comat)
data(raster_x, package = "comat")

com = get_coma(raster_x)
com

cov = get_cove(com)
cov

cov = get_cove(com, normalization = "pdf")
cov

Create an integrated co-occurrence matrix (incoma)

Description

Create an integrated co-occurrence matrix (incoma)

Usage

get_incoma(x, neighbourhood = 4, classes = NULL)

Arguments

x

A list object containing categorical matrices with categories

neighbourhood

The number of directions in which cell adjacencies are considered as neighbours: 4 (rook's case) or 8 (queen's case). The default is 4.

classes

A list of the same length as x with the values of selected classes from all of the objects in x. It is used to calculate incoma only for selected classes.

Value

An integrated co-occurrence matrix

Examples

data(raster_x, package = "comat")
data(raster_w, package = "comat")
x = list(raster_x, raster_w, raster_x)

get_incoma(x)

get_incoma(x, classes = list(1:2, 2:4, 1))

Create an integrated co-occurrence vector (incove)

Description

Converts an integrated co-occurrence matrix (incoma) to an integrated co-occurrence vector (incove)

Usage

get_incove(x, ordered = TRUE, repeated = TRUE, normalization = "none")

Arguments

x

A matrix - an output of the get_incoma() function

ordered

The type of pairs considered. Either "ordered" (TRUE) or "unordered" (FALSE). The default is TRUE. See details for more explanation.

repeated

Should the repeated co-located co-occurrence matrices be used? Either "repeated" (TRUE) or "unrepeated" (FALSE). The default is TRUE. See details for more explanation.

normalization

Should the output vector be normalized? Either "none" or "pdf". The "pdf" option normalizes a vector to sum to one. The default is "none".

Details

All values are kept when ordered = TRUE and repeated = TRUE. When ordered = TRUE and repeated = FALSE all values from cocoma (but only one cocoma for each pair) and all coma values are kept. ordered = FALSE and repeated = TRUE keeps all values from cocoma, but divides coma values by 2. ordered = FALSE and repeated = FALSE keeps all values from cocoma (but only one cocoma for each pair), and divides coma values by 2.

Value

An integrated co-occurrence vector

Examples

library(comat)

data(raster_x, package = "comat")
data(raster_w, package = "comat")
x = list(raster_x, raster_w, raster_x)

incom = get_incoma(x)
incom

incov1 = get_incove(incom)
incov1

incov2 = get_incove(incom, ordered = FALSE)
incov2

incov3 = get_incove(incom, ordered = FALSE, normalization = "pdf")
incov3

Create a weighted co-occurrence matrix (wecoma)

Description

Create a weighted co-occurrence matrix (wecoma)

Usage

get_wecoma(
  x,
  w,
  neighbourhood = 4,
  classes = NULL,
  fun = "mean",
  na_action = "replace"
)

Arguments

x

A matrix with categories

w

A matrix with weights

neighbourhood

The number of directions in which cell adjacencies are considered as neighbours: 4 (rook's case) or 8 (queen's case). The default is 4.

classes

A vector or a list with the values of selected classes from the x object. It is used to calculate wecoma only for selected classes.

fun

Function to calculate values from adjacent cells to contribute to output matrix, "mean" - calculate average values from adjacent cells of weight matrix, "geometric_mean" - calculate geometric mean values from adjacent cells of weight matrix, or "focal" assign value from the focal cell.

na_action

Decides on how to behave in the presence of missing values in w. Possible options are "replace", "omit", "keep". The default, "replace", replaces missing values with 0, "omit" does not use cells with missing values, and "keep" keeps missing values.

Value

A weighted co-occurrence matrix

Examples

library(comat)
data(raster_x, package = "comat")
data(raster_w, package = "comat")

wom = get_wecoma(raster_x, raster_w)
wom

get_wecoma(raster_x, raster_w, classes = list(c(1, 3)))

Create a weighted co-occurrence vector (wecove)

Description

Converts a weighted co-occurrence matrix (wecoma) to a weighted co-occurrence vector (wecove)

Usage

get_wecove(x, ordered = TRUE, normalization = "none")

Arguments

x

A matrix - an output of the get_wecoma() function

ordered

The type of pairs considered. Either "ordered" (TRUE) or "unordered" (FALSE). The default is TRUE.

normalization

Should the output vector be normalized? Either "none" or "pdf". The "pdf" option normalizes a vector to sum to one. The default is "none".

Value

A weighted co-occurrence vector

Examples

library(comat)
data(raster_x, package = "comat")
data(raster_w, package = "comat")

wom = get_wecoma(raster_x, raster_w)
wom

wov = get_wecove(wom)
wov

Calculates an Information Theory-based metric

Description

Calculates a selected Information Theory-based metric based on a provided co-occurrence matrix

Usage

it_metric(x, metric, base = "log2", ordered = TRUE)

Arguments

x

A matrix - an output of the get_coma() function

metric

One of the following: "ent" (Marginal entropy), "joinent" (Joint entropy), "condent" (Conditional entropy), "mutinf" (Mutual information), or "relmutinf" (Relative mutual information)

base

The unit in which entropy is measured. The default is "log2", which compute entropy in "bits". "log" and "log10" can be also used.

ordered

The type of pairs considered. Either "ordered" (TRUE) or "unordered" (FALSE). The default is TRUE.

Value

A single numeric value

References

Nowosad J., TF Stepinski. 2019. Information theory as a consistent framework for quantification and classification of landscape patterns. https://doi.org/10.1007/s10980-019-00830-x

Examples

library(comat)
data(raster_x, package = "comat")

com = get_coma(raster_x)
com

it_metric(com, metric = "ent")
it_metric(com, metric = "joinent")
it_metric(com, metric = "condent")
it_metric(com, metric = "mutinf")
it_metric(com, metric = "relmutinf")

A matrix with weights

Description

A matrix with weights

Usage

data(raster_w)

Format

A matrix

A matrix with weights and missing values

Description

A matrix with weights and missing values

Usage

data(raster_w_na)

Format

A matrix

A matrix with categories

Description

A matrix with categories

Usage

data(raster_x)

Format

A matrix

A matrix with categories and missing values

Description

A matrix with categories and missing values

Usage

data(raster_x_na)

Format

A matrix

A matrix with categories

Description

A matrix with categories

Usage

data(raster_y)

Format

A matrix

Get cell number

Description

Get cell number(s) of a matrix from row and column numbers. Cell numbers start at 0 in the upper left corner, and increase from top to bottom, and then from left to right.

Usage

rcpp_cell_from_xy(x, y)

Arguments

x

A matrix

y

A matrix with two columns (row and column numbers)

Coordinates from a matrix

Description

This function gets coordinates (row and column numbers) of the matrix cells.

Usage

rcpp_xy_from_matrix(x, cell = NULL)

Arguments

x

A matrix

cell

A vector of cell number. If NULL, the coordinates will be calculated for the whole matrix