# The supercells() function

#### Jakub Nowosad

#### 2024-02-11

Source:`vignettes/articles/main-function.Rmd`

`main-function.Rmd`

The main function in this package (Nowosad and
Stepinski 2022) is called `supercells()`

. An overview
of its arguments is shown in the table below.

This function expects raster data with one or more layers
(representing, for example, different bands, variables, or dates) in the
form of a **terra**’s `SpatRaster`

object or a
**stars**’s `stars`

object. The resulting
superpixels are stored as `sf`

polygons with four or more
columns containing identification numbers of superpixels, y and x
coordinates of their centroids, and one or more columns with average
values of variables for each superpixel.

The number of resulting superpixels can be specified with either
`k`

or `step`

arguments. `k`

relates to
the desired number of superpixels. When the `k`

value is set,
the algorithm automatically calculates the value of `step`

.
As, by default, cluster centroids are located regularly, the resulting
number of superpixels may slightly differ from the number provided as
`k`

, e.g., a square raster cannot be divided into five equal
square areas. `step`

is the expected distance, in the number
of cells, between initial superpixels’ centroids. This parameter also
defines a zone of influence of each cluster center (\(2S \times 2S\) region).

In our software, it is also possible to provide a set of points (an
`sf`

object) as `k`

together with the
`step`

value. This way, custom cluster centers are used, with
each of them attracting cells in the surrounding \(2S \times 2S\) region.

While `k`

or `step`

determines the number of
superpixels, the `compactness`

argument controls their
spatial shape, with its large value giving more importance to spatial
distances between cells and superpixels’ centers and its smaller value
putting more weight (importance) to the value distance. The impact of
the compactness value depends on the range of input cell values and the
selected distance measure.

argument | description |
---|---|

`x` |
An object of class SpatRaster (terra) or class stars (stars) |

`k` |
A number of superpixels desired by the user. It is also possible to provide a set of points (an sf object) as k together with the step value to create custom cluster centers |

`compactness` |
A compactness value. Larger values cause clusters to be more compact/even (squarish) |

`dist_fun` |
A distance function used |

`avg_fun` |
An averaging function specifying how the values of the superpixels’ centers are recalculated |

`clean` |
A boolean specifying if the additional process of connectivity enforcement should be performed |

`iter` |
A number of iterations performed to create the final output |

`step` |
A distance, in the number of cells, between initial superpixels’ centers |

`minarea` |
A minimal size of the output superpixels in cells |

`chunks` |
A boolean or numeric value specifying if the input (x) should be split into chunks before deriving superpixels |

`future` |
A boolean specifying if the future package should be used for parallelization of the calculations |

`verbose` |
An integer specifying the verboseness of text messages printed during calculations |

By default, the `supercells`

function behaves accordingly
to the original algorithm described by Achanta et
al. (2012) with Euclidean distance used to calculate the distance
between values, and the arithmetic mean used to calculate an average
value of each superpixel. However, in this package, both of the above
parameters can be customized with the `dist_fun`

and
`avg_fun`

arguments.

The role of the `dist_fun`

argument is to specify the
distance function used to obtain the distance between values. It can be
done with one of three mechanisms. The first is to use one of internal
C++ functions, such as `"euclidean"`

, `"jsd"`

(the
Jensen-Shannon distance, Lin (1991)), and
`"dtw"`

(dynamic time warping). The second mechanism allows
selecting one of 46 distance and similarity measures implemented in the
R package `philentropy`

(Dorst
2018). Thirdly, this argument also accepts any user-defined R
function that returns one value based on provided two vectors.

The `avg_fun`

function, on the other hand, specifies how
the values of the superpixels’ centers are calculated. It has two
internal functions implemented in C++ - `"mean"`

and
`"median"`

, but also accepts any fitting R function such as,
`base::mean()`

or `psych::geometric.mean()`

. This
also allows providing any other user-defined R function that returns one
value based on an R vector. For example, the `"median"`

function can be used when our input data is categorical.

Due to its simplicity, the SLIC algorithm does not consider spatial
connectivity directly. For example, it makes it possible to create a
superpixel consisting of two or more distinct patches, where one patch
is large while additional ones are distinctly smaller. The
`supercells`

function has two arguments, `clean`

and `minarea`

, allowing to enforce connectivity of the
superpixels. The first argument, `clean`

, is a boolean
(`TRUE`

by default) specifying if the connectivity should be
enforced by removing small disconnected patches (by merging with larger
neighborhood ones) or promoting small patches to new superpixels. The
role of the second one, `minarea`

, is to control how large
disconnected patches must be not be removed. By default, when
`clean = TRUE`

, an average area (\(A\)) is calculated automatically based on
the total number of cells divided by a number of superpixels, and next,
the minimal size of a superpixel equals \(A/(2^2)\). Alternatively, users can also
specify the minimum size of a superpixel by themselves by providing an
area in the unit of a number of cells in the `minarea`

argument.

The next argument is `iter`

- specifying the number of
iterations to create the output. Its default value of 10 follows the
advice by Achanta et al. (2012) This
argument defines how many times superpixels (and their centers) are
recalculated before obtaining the final results.

By default, the `supercells`

function, as R language, is
single-threaded – runs only on a single thread on the CPU and reads the
input raster values into the computer memory. These features may limit
the function’s usability for raster datasets with millions or more cells
and many variables, for which calculations can either be too slow or
require more memory that is available. To overcome the aforementioned
issues, the `supercells`

function has two related optional
arguments - `chunks`

and `future`

.

The `chunks`

argument is set by default to
`FALSE`

. However, when it is either `TRUE`

or some
numerical value, then the split, apply, combine procedure is used: input
raster is divided into several chunks, each chunk is read into RAM
independently and has a set of superpixels derived; this process is
repeated for every chunk, and all the results are combined into one
final object. When the user sets this argument to `TRUE`

, the
chunks’ sizes are calculated automatically, while when the user provides
a numerical value to this argument, then the input raster data is split
into chunks with user-defined side length (in the number of pixels). The
`future`

argument is also set by default to
`FALSE`

. If it is `TRUE`

, the user also needs to
specify how parallel processing should be performed and on how many CPU
threads with `future::plan()`

.

The final argument is called `verbose`

, which takes an
integer value of 0 or larger, where 0 means no additional messages
during the calculations, and 1 provides basic messages about the current
calculation stage.

## References

*IEEE Transactions on Pattern Analysis and Machine Intelligence*34 (11): 2274–82.

*Journal of Open Source Software*3 (26): 765.

*IEEE Transactions on Information Theory*37 (1): 145–51. https://doi.org/djxkkh.

*International Journal of Applied Earth Observation and Geoinformation*112 (August): 102935. https://doi.org/10.1016/j.jag.2022.102935.