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
  1. 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
  1. 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
  1. 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)
)