Author: Heraldo Borges, Amin Bazaz, Eduardo Ogasawara
Date: 2026-03-29

# STMotif R Package

#### Heraldo Borges, Amin Bazaz, Eduardo Ogasawara

#### 2026-03-29

The goal of the `STMotif` R package is to allow the discovery and ranking of motifs in spatial-time series quickly and efficiently.

    library(STMotif)

### Introduction

A pattern that significantly occurs in a time series is called a motif. In spatial time series data, these patterns may not be substantially present in a single time series but dispersed over several time series, limited in both space and time. The `STMotif` package was developed to simplify spatio-temporal data mining in the search for these motifs. We present the functions available in the package through the sample dataset, also available in this package.

Install the package from CRAN:

    install.packages("STMotif")

The package provides two categories of functions: functions for discovering and ranking motifs (`CSAMiningProcess`) and functions for viewing the identified motifs.

### 1. CSAMiningProcess

1. The function `NormSAX` normalizes the dataset and applies SAX encoding.

    # Load the example dataset
    dim(D <- STMotif::example_dataset)
    #> [1] 20 12

    # Normalization and SAX encoding
    DS <- NormSAX(D = STMotif::example_dataset, a = 5)

    # Preview the SAX-encoded dataset
    head(NormSAX(D = STMotif::example_dataset, a = 5)[, 1:10])
    #>
    #> 1 a c c c c c c c e c
    #> 2 a a e c e e e c c e
    #> 3 c e e e c e d e e e
    #> 4 e e b e e d e e d b
    #> 5 e c c b b c b c a e
    #> 6 b d c a a a b e a d

2. The function `SearchSTMotifs` checks and filters the motifs, grouping motifs from neighboring blocks.

    # Discover motifs
    stmotifs <- SearchSTMotifs(D, DS, 4, 5, 4, 10, 2, 2)
    stmotifs[[1]]
    #> $isaxcod
    #> [1] "ceeb"
    #>
    #> $recmatrix
    #>      [,1] [,2] [,3]
    #> [1,]    1    0    0
    #> [2,]    0    0    0
    #>
    #> $vecst
    #>   s t
    #> 1 1 3
    #> 2 3 1
    #> 3 4 2

3. The function `RankSTMotifs` ranks the motifs, balancing distance among occurrences with the encoded information of the motif and its quantity.

    # Rank the discovered motifs
    rstmotifs <- RankSTMotifs(stmotifs)
    rstmotifs[[1]]
    #> $isaxcod
    #> [1] "bded"
    #>
    #> $recmatrix
    #>      [,1] [,2] [,3]
    #> [1,]    0    0    0
    #> [2,]    1    1    1
    #>
    #> $vecst
    #>    s  t
    #> 1  1 11
    #> 2  2 11
    #> 3  4 17
    #> 4  5 17
    #> 5  8 15
    #> 6 10 15
    #> 7 12 12
    #>
    #> $rank
    #> $rank$dist
    #> [1] 0.5259316
    #>
    #> $rank$word
    #> [1] 1.5
    #>
    #> $rank$qtd
    #> [1] 2.807355
    #>
    #> $rank$proj
    #>       [,1]
    #> 3 1.522208

4. The complete workflow is wrapped in `CSAMiningProcess`:

    # Full CSA workflow in one call
    rstmotifs <- CSAMiningProcess(D, DS, 4, 5, 4, 10, 2, 2)
    rstmotifs[[1]]
    #> $isaxcod
    #> [1] "bded"
    #>
    #> $recmatrix
    #>      [,1] [,2] [,3]
    #> [1,]    0    0    0
    #> [2,]    1    1    1
    #>
    #> $vecst
    #>    s  t
    #> 1  1 11
    #> 2  2 11
    #> 3  4 17
    #> 4  5 17
    #> 5  8 15
    #> 6 10 15
    #> 7 12 12
    #>
    #> $rank
    #> $rank$dist
    #> [1] 0.5259316
    #>
    #> $rank$word
    #> [1] 1.5
    #>
    #> $rank$qtd
    #> [1] 2.807355
    #>
    #> $rank$proj
    #>       [,1]
    #> 3 1.522208

### 2. Visualization

Plot a heatmap of the dataset with the selected motifs highlighted:

    display_motifsDataset(
      dataset = STMotif::example_dataset,
      rstmotifs[c(1:4)],
      5
    )

Plot the selected spatial-time series with the motifs highlighted:

    display_motifsSTSeries(
      dataset = STMotif::example_dataset,
      rstmotifs[c(1:4)],
      space = c(1:4, 10:12)
    )