---
title: "An integrated co-occurrence matrix (incoma) representation"
author: "Jakub Nowosad"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{(3) An integrated co-occurrence matrix (incoma) representation}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

This vignette explains what an integrated co-occurrence matrix (*incoma*) representation is and how to calculate it using the **comat** package. 
If you do not know what a co-occurrence matrix is, it could be worth to read [the first package vignette](coma.html) first.
This representation is inspired by the work of Vadivel et al. (2007) and explained in details in Nowosad and Stepinski (2021).
The examples below assume the **comat** package is attached, and the `raster_x` and `raster_y` datasets are loaded:

```{r setup}
library(comat)
data(raster_x, package = "comat")
data(raster_y, package = "comat")
```

The `raster_x` object is a matrix with three rows and columns with values of 1, 2, and 3.

```{r}
raster_x
```

We can imagine that the yellow color represents agriculture, green is forest, and orange color represents grassland.

```{r, echo=FALSE, fig.width=4, fig.height=4}
op = par(mar = rep(0, 4))
raster_x2 = apply(raster_x, 2, rev)
image(1:3, 1:3, t(raster_x2),
      col = c("#ffff64", "#006400", "#BE9600"),
      axes = FALSE, xlab = "", ylab = "")
par(op)
```

The `raster_y` object is also a matrix of the same dimensions. 
It has values 5 and 6.

```{r}
raster_y
```

We can imagine that light yellow color represents flat plains and brown color represents mountains.

```{r, echo=FALSE, fig.width=4, fig.height=4}
op = par(mar = rep(0, 4))
raster_y2 = apply(raster_y, 2, rev)
image(1:3, 1:3, t(raster_y2),
      col = c("#fcffc2", "#724501"),
      axes = FALSE, xlab = "", ylab = "")
par(op)
```

The integrated co-occurrence matrix (*incoma*) representation consists of co-occurrence matrices (*coma*) and co-located co-occurrence matrices (*cocoma*).
In the co-occurrence matrix, we only use one matrix and count adjacent categories of each cell.
The co-located co-occurrence matrix uses two matrices and counts neighbors in the second matrix for each cell in the first matrix.

We can use the `get_incoma()` function to calculate this integrated co-occurrence matrix (*incoma*) representation.
It requires a list of two or more matrices of the same dimensions.

```{r}
get_incoma(list(raster_x, raster_y))
```

The *incoma* representation, for two matrices, consists of four sectors:

1. A co-occurrence matrix for the first matrix.
It is between the first and third column and the first and third row.
2. A co-located co-occurrence matrix between the first matrix and the second matrix.
It is between the first and third column and the third and fourth row.
3. A co-located co-occurrence matrix between the second and the first matrix. 
It is between the fourth and fifth column and the third and fourth row.
4. A co-occurrence matrix for the second matrix.
It is between the fourth and fifth column and the fourth and fifth row.

For example, there are four times a cell of class 1 in the first matrix is adjacent to another cell of class 1 in the second matrix (*agriculture next to agriculture*).
Also, five times agriculture is adjacent to flat plains, etc.

Similarly to the co-occurrence matrix (*coma*), it is possible to convert *incoma* to its 1D representation.
This new form is called an integrated co-occurrence vector (*incove*), and can be created using the `get_incove()` function, which accepts an output of `get_incoma()`:

```{r}
my_incoma = get_incoma(list(raster_x, raster_y))
get_wecove(my_incoma, normalization = "pdf")
```

## References

- Vadivel, A., Sural, S., & Majumdar, A. K. (2007). An integrated color and intensity co-occurrence matrix. Pattern recognition letters, 28(8), 974-983.
- Nowosad J, Stepinski TF (2021) Pattern-based identification and mapping of landscape types using multi-thematic data, International Journal of Geographical Information Science, DOI: 10.1080/13658816.2021.1893324