The supercells() function

Jakub Nowosad

2026-01-31

Version note: This vignette documents the supercells() interface as it existed in version 1.0 of the package. Some arguments, defaults, and behaviors may differ in newer releases. For up-to-date details, see ?supercells and the current reference docs.

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 supercells are stored as sf polygons with four or more columns containing identification numbers of supercells, y and x coordinates of their centers, and one or more columns with average values of variables for each supercell.

The number of resulting supercells can be specified with either k or step arguments. k relates to the desired number of supercells. When the k value is set, the algorithm automatically calculates the value of step. As, by default, supercell centers are located regularly, the resulting number of supercells 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 supercell centers. 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 supercell centers are used, with each of them attracting cells in the surrounding $2S \times 2S$ region.

While k or step determines the number of supercells, the compactness argument controls their spatial shape, with its large value giving more importance to spatial distances between cells and supercells’ 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.

Table: Overview of the arguments accepted by the supercells() function

argument	description
x	An object of class SpatRaster (terra) or class stars (stars)
k	A number of supercells 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 supercell centers
compactness	A compactness value. Larger values cause supercells to be more compact/even (squarish)
dist_fun	A distance function used
avg_fun	An averaging function specifying how the values of the supercells’ 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 supercells’ centers
minarea	A minimal size of the output supercells in cells
chunks	A boolean or numeric value specifying if the input (x) should be split into chunks before deriving supercells
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 supercells’ 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 supercells. 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 supercells. 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 supercells, 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 supercells (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 the chunks argument.

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 supercells 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 chunks argument is set by default to FALSE.

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

Achanta, Radhakrishna, Appu Shaji, Kevin Smith, Aurelien Lucchi, Pascal Fua, and Sabine Süsstrunk. 2012. “SLIC Superpixels Compared to State-of-the-Art Superpixel Methods.” IEEE Transactions on Pattern Analysis and Machine Intelligence 34 (11): 2274–82.

Dorst, HG. 2018. “Philentropy: Information Theory and Distance Quantification with R.” Journal of Open Source Software 3 (26): 765.

Lin, Jianhua. 1991. “Divergence Measures Based on the Shannon Entropy.” IEEE Transactions on Information Theory 37 (1): 145–51. https://doi.org/djxkkh.

Nowosad, Jakub, and Tomasz F. Stepinski. 2022. “Extended SLIC Superpixels Algorithm for Applications to Non-Imagery Geospatial Rasters.” International Journal of Applied Earth Observation and Geoinformation 112 (August): 102935. https://doi.org/10.1016/j.jag.2022.102935.