STMotif: Discovery and Ranking of Motifs in Spatial-Time Series

Description

Identifies motifs in spatial-time series using the Combined Series Approach (CSA). A motif is a previously unknown subsequence of a spatial time series with a relevant number of occurrences. The package provides functions for SAX encoding, motif discovery, ranking, and visualization.

Details

The main workflow consists of:

1. NormSAX: Normalize and encode the dataset with SAX.

2. SearchSTMotifs: Discover motifs in spatio-temporal blocks.

3. RankSTMotifs: Rank motifs by quality metrics.

These three steps are wrapped in the convenience function CSAMiningProcess.

Visualization functions:

• display_motifsDataset: Heatmap with highlighted motifs.

• display_motifsSTSeries: Time series plots with highlighted motifs.

Author(s)

Maintainer: Heraldo Borges stmotif@eic.cefet-rj.br (CEFET/RJ)

Authors:

• Amin Bazaz (Polytech'Montpellier)

• Esther Pacciti (INRIA/Polytech'Montpellier)

• Eduardo Ogasawara (CEFET/RJ)

See Also

vignette("STMotif") for a comprehensive introduction.

CSA Datamining Process

Description

Performs the complete Combined Series Approach (CSA) workflow: normalization with SAX encoding, motif discovery, and ranking. This is a convenience wrapper around NormSAX, SearchSTMotifs, and RankSTMotifs.

Usage

CSAMiningProcess(D, DS, w, a, sb, tb, si, ka)

Arguments

Value

A list of ranked motifs. Each motif contains:

isaxcode

Motif sequence in character format.

recmatrix

Matrix indicating which blocks contain this motif.

vecst

Data frame with columns s (spatial) and t (temporal) giving the start positions of the motif in the original dataset.

rank

List with ranking components: dist, word, qtd, proj.

Examples

D  <- STMotif::example_dataset
DS <- NormSAX(STMotif::example_dataset, 5)
rmotif <- CSAMiningProcess(D, DS, 4, 5, 4, 10, 2, 2)

Normalize and SAX Encode a Dataset

Description

Applies z-score normalization to the entire dataset and encodes the values using the Symbolic Aggregate approXimation (SAX) with an alphabet of size a.

Usage

NormSAX(D, a)

Arguments

Value

A data frame with the same dimensions as D, containing SAX letter encodings (characters from a to the a-th letter of the alphabet).

Examples

DS <- NormSAX(STMotif::example_dataset, 5)

Rank Spatial-Time Motifs

Description

Ranks the discovered motifs by computing a composite quality score that balances spatial-temporal proximity of occurrences, entropy of the SAX encoding, and quantity of occurrences.

Usage

RankSTMotifs(stmotifs)

Arguments

Value

A list of motifs sorted by decreasing quality score. Each motif gains a rank component with dist, word, qtd, and proj values.

Examples

D  <- STMotif::example_dataset
DS <- NormSAX(STMotif::example_dataset, 5)
stmotifs <- SearchSTMotifs(D, DS, 4, 5, 4, 10, 2, 2)
rstmotifs <- RankSTMotifs(stmotifs)

Adjust a Dataset

Description

Adjusts the dimensions of a dataset so that it can be evenly divided into spatio-temporal blocks of size tb x sb.

Usage

STSADatasetAdjust(D, tb, sb)

Arguments

Value

Dataset with rows and columns trimmed to be divisible by tb and sb, respectively.

Examples

D <- STSADatasetAdjust(STMotif::example_dataset, 20, 12)

Search for Spatial-Time Motifs

Description

Discovers motifs in the spatio-temporal blocks of the dataset, validates occurrence constraints, and groups motifs from neighboring blocks.

Usage

SearchSTMotifs(D, DS, w, a, sb, tb, si = 3, ka = 3)

Arguments

Value

A list of identified motifs. Each motif contains:

isaxcode

Motif sequence in character format.

recmatrix

Matrix indicating which blocks contain this motif.

vecst

Data frame with columns s and t giving the start positions in the original dataset.

Examples

D  <- STMotif::example_dataset
DS <- NormSAX(STMotif::example_dataset, 5)
stmotifs <- SearchSTMotifs(D, DS, 4, 5, 4, 10, 2, 2)

Plot Heatmap with Highlighted Motifs

Description

Displays the dataset as a heatmap (encoded via SAX binning) and overlays colored markers at the positions where the selected motifs occur.

Usage

display_motifsDataset(dataset, rstmotifs, alpha)

Arguments

Value

A ggplot object showing the heatmap with motif positions highlighted as colored squares.

Examples

D  <- STMotif::example_dataset
DS <- NormSAX(STMotif::example_dataset, 5)
stmotifs <- SearchSTMotifs(D, DS, 4, 5, 4, 10, 2, 2)
rstmotifs <- RankSTMotifs(stmotifs)
display_motifsDataset(
  dataset = STMotif::example_dataset,
  rstmotifs[c(1:4)],
  5
)

Plot Spatial-Time Series with Highlighted Motifs

Description

Displays the selected spatial-time series and highlights the segments corresponding to the discovered motifs using distinct colors.

Usage

display_motifsSTSeries(dataset, rstmotifs, space = seq_len(ncol(dataset)))

Arguments

Value

A ggplot object showing the time series with motif occurrences highlighted in color.

Examples

D  <- STMotif::example_dataset
DS <- NormSAX(STMotif::example_dataset, 5)
stmotifs <- SearchSTMotifs(D, DS, 4, 5, 4, 10, 2, 2)
rstmotifs <- RankSTMotifs(stmotifs)
display_motifsSTSeries(
  dataset = STMotif::example_dataset,
  rstmotifs[c(1:4)],
  space = c(1:4, 10:12)
)

Example Spatial-Time Series Dataset

Description

A synthetic toy dataset containing 12 spatial-time series, each with 20 time points. Used to demonstrate the motif discovery functions in this package.

Usage

example_dataset

Format

A data frame with 20 rows and 12 columns. Each column represents a spatial-time series and each row represents a time point. All values are numeric.

Source

Synthetic data generated for demonstration purposes.

Examples

data(example_dataset)
dim(example_dataset)
# [1] 20 12